@sun-asterisk/sungen 3.3.0-alpha.1 → 3.3.0-alpha.10

package/src/harness/provenance.ts

@@ -1,22 +1,110 @@
 /**
- * Provenance stamp for deterministic reports (score-determinism D1).
+ * Provenance stamp for deterministic reports (score-determinism D1), and the RULES the audit's
+ * verdict was judged by (#933, owner decision W4).
  *
- * The audit score is a pure function of the project files + the bundled catalog.
- * Stamping the sungen version + a catalog hash into the report lets two users who
- * get different scores see IMMEDIATELY whether the cause is a version/catalog
- * mismatch (the main residual source of cross-user variance) rather than a real
- * difference in their test design.
+ * The audit score is a pure function of the project files + the bundled catalogs + the scoring
+ * code. Stamping them into the report lets two users who get different scores see IMMEDIATELY
+ * whether the cause is a rules mismatch rather than a real difference in their test design — and
+ * lets `verifyAuditReport` tell a report judged by today's rules from one judged by other rules:
+ *
+ *   sungenVersion   which package wrote it — informational: a newer sungen with the same rules
+ *                   gives the same verdict, so the version alone never makes a report stale
+ *   catalogHash     sha256(universal-viewpoints.yaml), first 12 hex — the viewpoint catalog
+ *   rulesHash       sha256(AUDIT_RULES_VERSION + every catalog file under harness/catalog/ + each
+ *                   bundled driver's sources/catalogs), first 12 hex — everything the verdict
+ *                   depends on that is not the project's own files. No package VERSION is hashed:
+ *                   packages are lockstep-versioned, so a release would stale every report
  */
 import * as fs from 'fs';
 import * as path from 'path';
 import * as crypto from 'crypto';
 
+/**
+ * The version of the audit's SCORING CODE. Bump it (by one) in the same change whenever what
+ * `runAudit` computes for the same project can change: a sensor, a threshold, a gate term
+ * (audit-gate-terms.ts), the score model or weights, a finding that feeds the verdict, or the
+ * audit sensor of a bundled driver. Every report scored before the bump then reads stale and asks
+ * for one `sungen audit`. Catalog edits (harness/catalog/*.yaml) and bundled-driver changes (their
+ * sources and catalogs are hashed) need no bump.
+ * A release that changes none of these keeps every report trusted across the upgrade.
+ * Enforced by tests/audit/run.ts: its rules lock (tests/audit/audit-rules.lock.json) fails when the
+ * fixtures' audit output changes under an unchanged rules hash. After the bump, re-record it:
+ *   npx tsx tests/audit/run.ts --record-rules-lock
+ */
+export const AUDIT_RULES_VERSION = 1;
+
 export interface Provenance {
   sungenVersion: string;
   catalogHash: string; // sha256(universal-viewpoints.yaml), first 12 hex — the catalog that drives the score
+  rulesHash: string;   // sha256(AUDIT_RULES_VERSION + harness/catalog/*.yaml + bundled drivers), first 12 hex — the verdict's rules
+}
+
+/** A bundled driver as an input of the rules: its package dir, or null when it is not installed. */
+export interface DriverRulesInput { name: string; version?: string; dir: string | null }
+
+/** What is not a driver's rule: dependencies, build output, tests, docs, editor and lock files. */
+const SKIP_DIR = new Set(['node_modules', 'dist', 'tests', 'test', 'coverage']);
+const SKIP_FILE = /^(?:\.|package(?:-lock)?\.json$|tsconfig.*\.json$|.*\.(?:md|tsbuildinfo)$)/;
+
+function driverFiles(root: string, rel = ''): string[] {
+  const out: string[] = [];
+  for (const e of fs.readdirSync(path.join(root, rel), { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name, 'en'))) {
+    if (e.name.startsWith('.')) continue;
+    const r = rel ? `${rel}/${e.name}` : e.name;
+    if (e.isDirectory()) { if (!SKIP_DIR.has(e.name)) out.push(...driverFiles(root, r)); }
+    else if (e.isFile() && !SKIP_FILE.test(e.name)) out.push(r);
+  }
+  return out;
+}
+
+/** The package root above a driver's resolved entry file (the dir whose package.json names it). */
+function packageRootOf(entry: string, name: string): string | null {
+  let dir = path.dirname(entry);
+  for (let i = 0; i < 8; i++) {
+    try { if (JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'))?.name === name) return dir; } catch { /* keep walking */ }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
 }
 
+/** Each bundled driver as discovery would load it (project anchor, then core's), or `absent`. */
+export function bundledDriverRulesInputs(): DriverRulesInput[] {
+  // Lazy: discovery pulls the capability registry, which nothing else here needs.
+  const { bundledDriverNames, resolveDriverCopy } = require('../capabilities/discover') as typeof import('../capabilities/discover');
+  return bundledDriverNames().map((name) => {
+    const copy = resolveDriverCopy(name);
+    const dir = copy ? packageRootOf(copy.resolved, name) : null;
+    return { name, version: copy?.version, dir };
+  });
+}
+
+const CATALOG_DIR = path.join(__dirname, 'catalog');
+const sha12 = (s: string | Buffer): string => crypto.createHash('sha256').update(s).digest('hex').slice(0, 12);
+
+/**
+ * The rules hash: the scoring version, every *.yaml of the catalog dir (by name), and each bundled
+ * driver — every source / catalog file of its package (by relative path; build output, tests and
+ * dependencies excluded), or a stable `absent` marker when it is not installed. A driver's version is
+ * deliberately left out: releases bump every package in lockstep, and only content changes the rules.
+ */
+export function rulesHashOf(rulesVersion: number, catalogDir: string = CATALOG_DIR, drivers: DriverRulesInput[] = bundledDriverRulesInputs()): string {
+  const files = fs.readdirSync(catalogDir).filter((f) => f.endsWith('.yaml')).sort();
+  const h = crypto.createHash('sha256').update(`audit-rules:${rulesVersion}\n`);
+  for (const f of files) h.update(`${f}\n`).update(fs.readFileSync(path.join(catalogDir, f))).update('\n');
+  for (const d of [...drivers].sort((a, b) => a.name.localeCompare(b.name, 'en'))) {
+    h.update(`driver:${d.name}\n`);
+    if (!d.dir) { h.update('absent\n'); continue; }
+    for (const f of driverFiles(d.dir)) h.update(`${f}\n`).update(fs.readFileSync(path.join(d.dir, f))).update('\n');
+  }
+  return h.digest('hex').slice(0, 12);
+}
+
+let cached: Provenance | null = null;
+
 export function getProvenance(): Provenance {
+  if (cached) return cached;
   let sungenVersion = 'unknown';
   try {
     const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', '..', 'package.json'), 'utf-8'));
@@ -24,10 +112,10 @@ export function getProvenance(): Provenance {
   } catch { /* version stays 'unknown' */ }
 
   let catalogHash = 'unknown';
-  try {
-    const cat = fs.readFileSync(path.join(__dirname, 'catalog', 'universal-viewpoints.yaml'), 'utf-8');
-    catalogHash = crypto.createHash('sha256').update(cat).digest('hex').slice(0, 12);
-  } catch { /* hash stays 'unknown' */ }
+  try { catalogHash = sha12(fs.readFileSync(path.join(CATALOG_DIR, 'universal-viewpoints.yaml'), 'utf-8')); } catch { /* hash stays 'unknown' */ }
+  let rulesHash = 'unknown';
+  try { rulesHash = rulesHashOf(AUDIT_RULES_VERSION); } catch { /* hash stays 'unknown' */ }
 
-  return { sungenVersion, catalogHash };
+  cached = { sungenVersion, catalogHash, rulesHash };
+  return cached;
 }

package/src/harness/triage-manual-classification.ts

@@ -0,0 +1,76 @@
+/**
+ * `sungen triage --screen <u> --case <id> --as product|test-defect|environment --reason "…"` (#928):
+ * classify one red by hand — the one `sungen triage` left unclassified, or one it got wrong — as a
+ * `triage-classification` decision in the unit's `decisions/` (read back by graph/manual-triage-decisions.ts).
+ *
+ *   validated first   the class, a reason, a case that exists, is red and is not exempt — before any
+ *                     prompt, so a human never confirms something that is then rejected
+ *   product           stricter than any automatic class (it leads to a QA decision): anyone may record it
+ *   test-defect,      can hide a product defect behind "fix the test" / "re-run": a human types a
+ *   environment       confirmation on a terminal (DOS-13.4); without one it is refused, nothing is
+ *                     written and the exact command is printed. Only after the typed phrase does the
+ *                     entry carry `humanConfirmed: true`, and a reader ignores one without it
+ *   bound             evidence_hash = the case's red as it reads now; a re-run voids the classification
+ */
+import type { AppendResult } from '../decisions/append-decision';
+import { appendDecision } from '../decisions/append-decision';
+import type { DecisionDraft } from '../decisions/decision-schema';
+import { gitUserName } from '../decisions/decision-source';
+import { ConfirmationIO, formatCommand, requireTypedConfirmation } from '../decisions/human-confirmation';
+import { resolveUnitCandidates } from '../cli/resolve-unit';
+import { HUMAN_ONLY_TRIAGE, MANUAL_TRIAGE_AS, ManualTriageClass, TRIAGE_DECISION_KIND } from '../graph/manual-triage-decisions';
+import { exemptionOf } from '../graph/test-case-satisfied';
+import { testCaseStates } from '../graph/test-case-states';
+import { unitScopeOfDir } from './gates/unit-gate-overrides';
+
+export interface ClassifyRedCaseInput {
+  projectRoot: string;
+  unit: string;
+  caseId: string;
+  /** product | test-defect | environment */
+  as: string;
+  reason?: string;
+  io: ConfirmationIO;
+}
+
+export interface ClassifyRedCaseResult extends AppendResult { caseId: string; class: ManualTriageClass }
+
+export async function classifyRedCase(i: ClassifyRedCaseInput): Promise<ClassifyRedCaseResult> {
+  const cls = Object.prototype.hasOwnProperty.call(MANUAL_TRIAGE_AS, i.as) ? MANUAL_TRIAGE_AS[i.as] : undefined;
+  if (!cls) throw new Error(`--as must be one of ${Object.keys(MANUAL_TRIAGE_AS).join(', ')} (got "${i.as}")`);
+  const reason = (i.reason ?? '').trim();
+  if (!reason) throw new Error('--reason is required: a classification records WHY this red is what you say it is');
+  const found = resolveUnitCandidates(i.unit, i.projectRoot);
+  if (found.length !== 1) throw new Error(`"${i.unit}" does not name exactly one unit under qa/screens, qa/flows or qa/api`);
+  const unitDir = found[0].dir;
+  const scope = unitScopeOfDir(i.projectRoot, unitDir);
+  if (!scope) throw new Error(`"${i.unit}" has no decisions scope`);
+  const cases = testCaseStates(i.projectRoot, i.unit, { unitDir, auditFindings: [] });
+  const tc = cases.find((c) => c.id === i.caseId);
+  if (!tc) {
+    const known = cases.slice(0, 8).map((c) => c.id).join(', ');
+    throw new Error(`no test case "${i.caseId}" in ${i.unit}${known ? ` — known: ${known}${cases.length > 8 ? ', …' : ''}` : ''}`);
+  }
+  if (tc.result !== 'failed' || !tc.evidence) throw new Error(`${tc.id} has no red result to classify (result: ${tc.result})`);
+  const exempt = exemptionOf(tc);
+  if (exempt) throw new Error(`${tc.id} is exempt (${exempt}) — it needs no classification`);
+
+  const human = HUMAN_ONLY_TRIAGE.has(cls);
+  if (human) {
+    await requireTypedConfirmation({
+      what: `classify the red ${tc.id} of ${i.unit} as ${cls}`,
+      phrase: tc.id,
+      command: formatCommand(['sungen', 'triage', found[0].kind === 'api' ? '--api' : '--screen', i.unit, '--case', tc.id, '--as', i.as, '--reason', reason]),
+      summary: [`case: ${tc.title}`, `automatic triage: ${tc.triage ? `${tc.triage.class} (${tc.triage.ruleId})` : 'none current'}`, `reason: ${reason}`,
+        `recorded by: ${gitUserName(i.projectRoot)}`, `as ${cls} it leaves the product-defect path — confirm only after reading its evidence (trace, error)`,
+        'it stops counting as soon as the case runs again'],
+      io: i.io,
+    });
+  }
+  const draft: DecisionDraft = {
+    kind: TRIAGE_DECISION_KIND, anchors: [], text: `${tc.id} is ${cls}: ${tc.title}`, reason,
+    payload: { case: tc.id, class: cls, ...(human ? { humanConfirmed: true } : {}) },
+    source: { by: gitUserName(i.projectRoot), where: 'cli' }, valid_from: new Date().toISOString(), visibility: 'internal', evidence_hash: tc.evidence,
+  };
+  return { ...appendDecision(i.projectRoot, scope, draft), caseId: tc.id, class: cls };
+}

package/src/harness/unit-paths.ts

@@ -49,3 +49,22 @@ export function featureFilesFor(unitDir: string, unit: string): string[] {
     ...names.filter((n) => n !== canonicalName),
   ].map((n) => path.join(dir, n));
 }
+
+/**
+ * The catalog-resolution id for a unit dir (relative to qa/): screen · flows/<flow> · api/<area> ·
+ * api/flows/<flow>; a bare screen is its basename. Shared by the audit, which scores and links the
+ * unit under this id, and its inputsHash, which reads what the audit reads under the same id.
+ */
+export function catalogIdFromScreenDir(screenDir: string): string {
+  const parts = screenDir.split(path.sep);
+  const qa = parts.lastIndexOf('qa');
+  if (qa >= 0) {
+    if (parts[qa + 1] === 'api' && parts[qa + 2] === 'flows' && parts[qa + 3]) return `api/flows/${parts[qa + 3]}`;
+    if (parts[qa + 1] === 'api' && parts[qa + 2]) return `api/${parts[qa + 2]}`;
+    if (parts[qa + 1] === 'flows' && parts[qa + 2]) return `flows/${parts[qa + 2]}`;
+  }
+  return path.basename(screenDir);
+}
+
+/** A screen unit — the only kind a sibling flow credits (TQ-4); flows and api units are not. */
+export const isScreenUnitId = (catalogId: string): boolean => !/^(flows|api)\//.test(catalogId);

package/src/hooks/bash-read-only-segment.ts

@@ -0,0 +1,130 @@
+/**
+ * Which Bash segments only READ, so they may name a protected path freely (bash-protected-mention).
+ *
+ * An allowlist, fail-closed (#968): a command is read-only only in the forms listed here. It drops
+ * back to "the guard cannot tell" when
+ *   - the command word has a `/` outside the system bin dirs (`./cat`, `/tmp/evil/jq`),
+ *   - a word holds `$`, `{`, `*`, `?` or `[` (`$'--output'`, `${…}`, `--{output=…,stat}`, a `q*` glob can
+ *     hide an option name or a path),
+ *   - an option runs a program or writes a file, also abbreviated where the tool accepts that
+ *     (`rg --pre`, `git diff --output` / `--outp`, ugrep's `grep --filter` / `--save-config` / `--pager`
+ *     / `--config`, `sort -o` / `--o…` / `--c…`),
+ *   - git has any global option before its subcommand except `--no-pager` / `-P` / `--no-optional-locks`
+ *     (`-c`, `--config-env`, `--exec-path`, `-C`, `--git-dir`… can point it at another program),
+ *   - its output is piped into anything that is not a read-only command or filter (`| xargs rm`, `| sh`).
+ * And the whole LINE loses the exemption (lineKeepsReadOnlyExemption) when it uses command
+ * substitution or changes shell state that a later command obeys: any `NAME=value`, `export`,
+ * `declare`, `typeset`, `set`, `setopt`, `shopt`, `alias`, `unalias`, `hash`, `unset`, `read`,
+ * `enable`, `builtin`, `trap`, `source` / `.`, `eval`, or a function definition.
+ * `git grep` is not read-only at all: `-O` runs a program, also inside a flag cluster (`-nOrm`) and
+ * as an abbreviation (`--open=`). `node -e|-p` counts only when its script can do nothing but read
+ * (isReadOnlyNodeEval).
+ *
+ * Accepted floor, not closed here: `sungen` is listed read-only (it writes approval records only
+ * through its own human gates); a path built at runtime (`$VAR` away from a protected name), a
+ * symlink, or a script that writes without naming the path is out of reach; a bare directory
+ * (`rm -rf qa/decisions`, `cd qa && rm -rf decisions/`) is not a protected-path mention (#970);
+ * `git -C <dir> …` is not followed; a same-line `D=qa/decisions; … $D` is not tracked; pathless
+ * destructive git (`clean -fdx`, `stash`, `reset --hard`, `checkout .`, `apply`, `am`) is not seen;
+ * and a quoting trick the tokenizer reads differently from the shell can turn a deny into an ask.
+ * The backstop is release-time decision integrity: the git HEAD comparison and the in-run rule.
+ */
+import * as path from 'path';
+import type { BashSegment } from './bash-write-targets';
+
+const READ_ONLY = new Set(['cat', 'ls', 'head', 'tail', 'grep', 'rg', 'wc', 'diff', 'stat', 'jq', 'sungen', 'sungen.js']);
+const GIT_READ_ONLY = new Set(['diff', 'log', 'show', 'status', 'check-ignore', 'ls-files', 'ls-tree', 'blame', 'rev-parse', 'cat-file']);
+/** The only git global options allowed before a read-only subcommand. */
+const GIT_SAFE_GLOBALS = new Set(['--no-pager', '-P', '--no-optional-locks']);
+/** Filters that write only to stdout — safe as a pipe sink, in the forms isPipeFilter allows. */
+const FILTERS = new Set(['sort', 'uniq', 'cut', 'tr']);
+
+/** A command word with a `/` counts only from these dirs: `./cat` or `/tmp/evil/jq` is not `cat` / `jq`. */
+const SYSTEM_BIN = new Set(['/usr/bin', '/bin', '/usr/local/bin', '/opt/homebrew/bin']);
+/** Characters that let the shell build a word the guard cannot read: expansions, braces, globs. */
+const OPAQUE_WORD = /[$*?[{]/;
+
+/** Is `word` the long option `--<one of names>`, or an abbreviation of one at least `min` chars long? */
+const longOpt = (names: string[], min: number) => (word: string): boolean => {
+  const m = /^--([^=]+)/.exec(word);
+  return !!m && names.some((n) => n === m[1] || (m[1].length >= min && n.startsWith(m[1])));
+};
+/** Options that make an otherwise read-only command run a program or write a file. */
+const UNSAFE_OPT: Record<string, (word: string) => boolean> = {
+  rg: (w) => /^--(?:pre|hostname-bin)(?:=|$)/.test(w),
+  git: longOpt(['output', 'ext-diff', 'textconv'], 2),
+  // `grep` may be ugrep: --filter runs programs, --save-config writes, --pager / --view run one, --config / ---FILE load those
+  grep: (w) => w.startsWith('---') || longOpt(['filter', 'save-config', 'pager', 'view', 'config'], 3)(w),
+};
+const trustedWords = (seg: BashSegment): boolean =>
+  !seg.assigns.length && !seg.words.some((w) => OPAQUE_WORD.test(w))
+  && (!seg.cmdPath.includes('/') || SYSTEM_BIN.has(path.posix.dirname(seg.cmdPath)));
+
+/** `$(…)`, backticks, `<(…)`, `>(…)`: a command's output becomes another command's words. */
+const SUBSTITUTION = /\$\(|`|[<>]\(/;
+/** Commands that change shell state a later command on the line obeys. */
+const SHELL_STATE = new Set([
+  'export', 'declare', 'typeset', 'local', 'readonly', 'set', 'setopt', 'shopt', 'alias', 'unalias', 'hash', 'unset',
+  'read', 'enable', 'builtin', 'trap', 'source', '.', 'eval', 'function',
+]);
+/** `name() {` / `name() (` — a function definition (`function name` is caught by SHELL_STATE). */
+const FUNCTION_DEF = /(?:^|[\s;&|])[\w.:-]+\s*\(\s*\)\s*[{(]/;
+
+/** May any read-only segment of this line keep its exemption? */
+export function lineKeepsReadOnlyExemption(command: string, segs: BashSegment[]): boolean {
+  return !SUBSTITUTION.test(command) && !FUNCTION_DEF.test(command)
+    && !segs.some((s) => s.assigns.length || SHELL_STATE.has(s.cmd));
+}
+
+/** `node -e` / `node -p` whose script can only read: no write/exec API, no computed access, no escapes. */
+const NODE_EVAL_FLAGS = new Set(['-e', '-p', '--eval', '--print']);
+const NODE_UNSAFE = new RegExp([
+  '[`\\[\\\\]', // template literals, computed property access, string escapes
+  'flag', // `readFileSync(p, { flag: 'w' })` truncates p
+  'write', 'append', '\\brm', 'unlink', 'rename', 'copy', '\\bcp', 'mkd', 'truncate', 'stream', 'open', 'link',
+  'chmod', 'chown', 'utime', 'exec', 'spawn', 'fork', 'child', 'eval', 'function', 'import', 'constructor',
+  'proto', 'reflect', 'proxy', 'global', 'process', 'module', 'object', 'concat', '\\bvm\\b', 'worker', 'binding',
+].join('|'), 'i');
+const SAFE_REQUIRE = /\brequire\(\s*(['"])(?:(?:node:)?(?:fs|path)|[./][^'"]*\.json)\1\s*\)/g;
+
+export function isReadOnlyNodeEval(args: string[]): boolean {
+  if (args.length !== 2 || !NODE_EVAL_FLAGS.has(args[0])) return false;
+  const script = args[1];
+  return !NODE_UNSAFE.test(script) && !/\brequire\b/.test(script.replace(SAFE_REQUIRE, ''));
+}
+
+/** `git [--no-pager|-P|--no-optional-locks]… <read-only subcommand> …` — anchored, no other global option. */
+function isReadOnlyGit(words: string[]): boolean {
+  let k = 0;
+  while (GIT_SAFE_GLOBALS.has(words[k])) k++;
+  return GIT_READ_ONLY.has(words[k] ?? '');
+}
+
+/** Does this segment only read? (`words` holds its arguments and redirection targets.) */
+export function isReadOnlySegment(seg: BashSegment): boolean {
+  if (!seg.cmd || !trustedWords(seg)) return false;
+  const unsafe = UNSAFE_OPT[seg.cmd];
+  if (unsafe && seg.words.some(unsafe)) return false;
+  if (seg.cmd === 'git') return isReadOnlyGit(seg.words);
+  if (seg.cmd === 'node') return isReadOnlyNodeEval(seg.words);
+  return READ_ONLY.has(seg.cmd);
+}
+
+/** A pipe sink that cannot act on what it reads: a read-only command, or a stdout-only filter. */
+function isPipeFilter(seg: BashSegment): boolean {
+  if (isReadOnlySegment(seg)) return true;
+  if (!FILTERS.has(seg.cmd) || !trustedWords(seg)) return false;
+  // `sort -o out` / `--compress-program=…` (any `--o…` / `--c…` abbreviation) write or run; `uniq in out` writes its second operand.
+  if (seg.cmd === 'sort') return !seg.words.some((w) => /^(?:-[^-]*o|--[oc])/.test(w));
+  if (seg.cmd === 'uniq') return seg.words.every((w) => w.startsWith('-'));
+  return true;   // cut, tr: operands are inputs or character sets
+}
+
+/** Does everything downstream of segment `i` in its pipeline only read / filter? */
+export function pipelineStaysReadOnly(segs: BashSegment[], i: number): boolean {
+  for (let j = i; segs[j]?.pipesTo; j++) {
+    const next = segs[j + 1];
+    if (!next || !isPipeFilter(next)) return false;
+  }
+  return true;
+}

package/src/hooks/bash-write-targets.ts

@@ -1,18 +1,47 @@
 /**
  * The files a Bash command line WRITES through the three forms the pre-tool guard covers (P0.1):
- * output redirection (`>`, `>>`, `>|`, `&>`, `2>`…), `tee`, and in-place `sed -i`.
+ * output redirection (`>`, `>>`, `>|`, `&>`, `2>`, `>&file`, zsh `>!`…), `tee`, in-place `sed -i`, and
+ * `git … --output <file>` (also abbreviated, `--outp=`) (#968).
  *
- * A floor, not a shell interpreter: quotes, escapes, `;`/`&&`/`||`/`|` and a leading `cd` are
- * understood; anything else that can write a file (`cp`, a script, `python -c`) is out of scope by
+ * A floor, not a shell interpreter: quotes, escapes, `$'…'` ANSI-C strings, backslash-newline
+ * continuations, `;`/`&&`/`||`/`|` and `cd` / `pushd` (with their options; an operand it cannot resolve
+ * marks the directory unknown) are understood; anything else that can write a file (`cp`, a script, `python -c`) is out of scope by
  * design. The command string is untrusted — it is only tokenized here, never executed.
  */
 import * as path from 'path';
 
-type Tok = { kind: 'word'; value: string } | { kind: 'sep' } | { kind: 'redir'; writes: boolean };
+type Tok = { kind: 'word'; value: string } | { kind: 'sep'; pipe?: boolean } | { kind: 'redir'; writes: boolean; dup?: boolean };
 
 /** Commands that run another command: the real one is the next word. */
 const WRAPPERS = new Set(['sudo', 'env', 'command', 'nohup', 'time', 'exec', 'nice']);
 const ASSIGNMENT = /^[A-Za-z_]\w*=/;
+const ANSI_C: Record<string, string> = {
+  a: '\x07', b: '\b', e: '\x1b', E: '\x1b', f: '\f', n: '\n', r: '\r', t: '\t', v: '\v', '\\': '\\', "'": "'", '"': '"', '?': '?',
+};
+
+/** Decode a bash `$'…'` body starting at `j` (just past `$'`); returns the text and the index past the closing `'`. */
+function ansiC(cmd: string, j: number): [string, number] {
+  let out = '';
+  while (j < cmd.length && cmd[j] !== "'") {
+    if (cmd[j] !== '\\' || j + 1 >= cmd.length) { out += cmd[j++]; continue; }
+    const e = cmd[j + 1];
+    j += 2;
+    if (e in ANSI_C) out += ANSI_C[e];
+    else if (/[0-7]/.test(e)) {
+      let m = e;
+      while (m.length < 3 && /[0-7]/.test(cmd[j] ?? '')) m += cmd[j++];
+      out += String.fromCharCode(parseInt(m, 8) & 0xff);
+    } else if (e === 'x' || e === 'u' || e === 'U') {
+      const max = e === 'x' ? 2 : e === 'u' ? 4 : 8;
+      let h = '';
+      while (h.length < max && /[0-9a-fA-F]/.test(cmd[j] ?? '')) h += cmd[j++];
+      const cp = parseInt(h, 16);
+      out += !h ? `\\${e}` : cp <= 0x10ffff ? String.fromCodePoint(cp) : '\ufffd';   // never throw: a throw fails open
+    } else if (e === 'c' && j < cmd.length) out += String.fromCharCode(cmd.charCodeAt(j++) & 31);
+    else out += `\\${e}`;
+  }
+  return [out, j + 1];
+}
 
 function tokenize(cmd: string): Tok[] {
   const toks: Tok[] = [];
@@ -21,25 +50,39 @@ function tokenize(cmd: string): Tok[] {
   const flush = (): void => { if (inWord) toks.push({ kind: 'word', value: word }); word = ''; inWord = false; };
   for (let i = 0; i < cmd.length;) {
     const ch = cmd[i];
-    if (ch === "'") {
+    if (ch === '$' && cmd[i + 1] === "'") {
+      const [text, next] = ansiC(cmd, i + 2);
+      word += text; inWord = true; i = next;
+    } else if (ch === '$' && cmd[i + 1] === '"') {
+      i++;   // `$"…"` (locale translation) reads as `"…"`
+    } else if (ch === "'") {
       const end = cmd.indexOf("'", i + 1);
       word += cmd.slice(i + 1, end < 0 ? cmd.length : end); inWord = true; i = end < 0 ? cmd.length : end + 1;
     } else if (ch === '"') {
       let j = i + 1;
-      for (; j < cmd.length && cmd[j] !== '"'; j++) { if (cmd[j] === '\\' && j + 1 < cmd.length) j++; word += cmd[j]; }
+      for (; j < cmd.length && cmd[j] !== '"'; j++) {
+        if (cmd[j] === '\\' && cmd[j + 1] === '\n') { j++; continue; }   // line continuation
+        if (cmd[j] === '\\' && j + 1 < cmd.length) j++;
+        word += cmd[j];
+      }
       inWord = true; i = j + 1;
+    } else if (ch === '\\' && cmd[i + 1] === '\n') {
+      i += 2;   // line continuation: removed entirely
     } else if (ch === '\\' && i + 1 < cmd.length) {
       word += cmd[i + 1]; inWord = true; i += 2;
     } else if (ch === ' ' || ch === '\t') {
       flush(); i++;
     } else if ('\n;|()'.includes(ch) || (ch === '&' && cmd[i + 1] !== '>')) {
-      flush(); toks.push({ kind: 'sep' }); i += (ch === '|' || ch === '&') && cmd[i + 1] === ch ? 2 : 1;
+      const doubled = (ch === '|' || ch === '&') && cmd[i + 1] === ch;
+      flush(); toks.push({ kind: 'sep', pipe: ch === '|' && !doubled }); i += doubled ? 2 : 1;
     } else if (ch === '>' || (ch === '&' && cmd[i + 1] === '>')) {
       if (ch === '>' && inWord && /^\d+$/.test(word)) { word = ''; inWord = false; } else flush(); // `2>`: an fd, not a word
       i += ch === '&' ? 2 : 1;
-      if (cmd[i] === '>' || cmd[i] === '|') i++;
-      if (cmd[i] === '&') { i++; toks.push({ kind: 'redir', writes: false }); } // `>&2`: an fd dup
-      else toks.push({ kind: 'redir', writes: true });
+      if (cmd[i] === '>') i++;                          // `>>`, `&>>`
+      const dup = cmd[i] === '&';                       // `>&x`, `>>&x`: an fd dup only when x is an fd
+      if (dup) i++;
+      if (cmd[i] === '|' || cmd[i] === '!') i++;        // clobber: `>|`, `>!`, `>>!`, `&>!`, `>&|`, `>&!`
+      toks.push({ kind: 'redir', writes: true, dup });
     } else if (ch === '<') {
       flush(); i++;
       while (cmd[i] === '<') i++;
@@ -58,43 +101,86 @@ const isInPlaceFlag = (a: string): boolean => a === '--in-place' || a.startsWith
 export interface BashSegment {
   /** The command name (basename, after env assignments and wrappers like `sudo`), or ''. */
   cmd: string;
+  /** The command word as written (`./cat`, `/usr/bin/grep`, `cat`). */
+  cmdPath: string;
   /** Its arguments, and every redirection target, as written. */
   words: string[];
   /** The directory it runs in — a preceding `cd` in the same line is followed. */
   dir: string;
-  /** Absolute paths it writes via redirection, `tee` or `sed -i`. */
+  /** Absolute paths it writes via redirection, `tee`, `sed -i` or `git … --output`. */
   writes: string[];
+  /** False once a `cd` / `pushd` / `popd` on the line went somewhere the guard cannot resolve. */
+  dirKnown: boolean;
+  /** It writes a relative path while `dirKnown` is false — the guard cannot tell where. */
+  writesInUnknownDir: boolean;
+  /** Leading `NAME=value` assignments (a lone `X=…` is a segment too, with cmd ''). */
+  assigns: string[];
+  /** Its stdout feeds the next segment through `|`. */
+  pipesTo: boolean;
+}
+
+/** `git diff|log|show … --output=<file>` / `--output <file>` writes that file (git takes `--outp` for `--output`). */
+function gitOutputTargets(args: string[]): string[] {
+  const out: string[] = [];
+  args.forEach((a, k) => {
+    const m = /^--([\w-]+)(=([\s\S]*))?$/.exec(a);
+    if (!m || m[1].length < 2 || !'output'.startsWith(m[1])) return;
+    if (m[2] !== undefined) out.push(m[3]);
+    else if (args[k + 1]) out.push(args[k + 1]);
+  });
+  return out.filter((t) => t && t !== '/dev/null' && t !== '-');
+}
+
+/** The operand of `cd` / `pushd` after its options (`-L -P -e -@`, pushd `-n`, `--`), or null when there is not exactly one. */
+function cdOperand(args: string[]): string | null {
+  let k = 0;
+  while (k < args.length && /^-[LPe@n]+$/.test(args[k])) k++;
+  if (args[k] === '--') k++;
+  return args.length - k === 1 ? args[k] : null;
 }
 
 export function bashSegments(command: string, cwd: string): BashSegment[] {
   const out: BashSegment[] = [];
   const toks = tokenize(command);
   let dir = cwd;
+  let dirKnown = true;
   let seg: string[] = [];
   let redirected: string[] = [];
-  let writes: string[] = [];
-  const endSegment = (): void => {
+  let rawWrites: string[] = [];
+  const endSegment = (pipesTo = false): void => {
     let k = 0;
     while (k < seg.length && (ASSIGNMENT.test(seg[k]) || WRAPPERS.has(seg[k]))) k++;
-    const cmd = path.basename(seg[k] ?? '');
+    const assigns = seg.slice(0, k).filter((w) => ASSIGNMENT.test(w));
+    const cmdPath = seg[k] ?? '';
+    const cmd = path.basename(cmdPath);
     const args = seg.slice(k + 1).filter((a) => a !== '');
-    if (cmd === 'tee') writes.push(...args.filter((a) => !a.startsWith('-')).map((a) => path.resolve(dir, a)));
-    else if ((cmd === 'sed' || cmd === 'gsed') && args.some(isInPlaceFlag)) {
-      writes.push(...args.filter((a) => !a.startsWith('-')).map((a) => path.resolve(dir, a)));
+    if (cmd === 'tee') rawWrites.push(...args.filter((a) => !a.startsWith('-')));
+    else if ((cmd === 'sed' || cmd === 'gsed') && args.some(isInPlaceFlag)) rawWrites.push(...args.filter((a) => !a.startsWith('-')));
+    else if (cmd === 'git') rawWrites.push(...gitOutputTargets(args));
+    const writes = rawWrites.map((a) => path.resolve(dir, a));
+    const writesInUnknownDir = !dirKnown && rawWrites.some((a) => !path.isAbsolute(a));
+    if (cmd || redirected.length || assigns.length) {
+      out.push({ cmd, cmdPath, words: [...args, ...redirected], dir, dirKnown, writes, writesInUnknownDir, assigns, pipesTo });
+    }
+    if (cmd === 'cd' || cmd === 'pushd' || cmd === 'popd') {
+      const target = cmd === 'popd' ? null : cdOperand(args);
+      if (target && !/[$~`]/.test(target) && target !== '-' && !/^[+-]\d+$/.test(target)) {
+        dir = path.resolve(dir, target);
+        dirKnown = dirKnown || path.isAbsolute(target);
+      } else dirKnown = false;   // `cd`, `cd ~`, `cd $D`, `cd -`, `popd`: somewhere the guard cannot resolve
     }
-    if (cmd || redirected.length) out.push({ cmd, words: [...args, ...redirected], dir, writes });
-    if (cmd === 'cd' && args.length === 1 && !/^[-~]/.test(args[0])) dir = path.resolve(dir, args[0]);
-    seg = []; redirected = []; writes = [];
+    seg = []; redirected = []; rawWrites = [];
   };
   for (let t = 0; t < toks.length; t++) {
     const tok = toks[t];
-    if (tok.kind === 'sep') { endSegment(); continue; }
+    if (tok.kind === 'sep') { endSegment(tok.pipe === true); continue; }
     if (tok.kind === 'redir') {
       const target = toks[t + 1];
       if (target?.kind !== 'word') continue;
       t++;
       redirected.push(target.value);
-      if (tok.writes && target.value && target.value !== '/dev/null' && target.value !== '-') writes.push(path.resolve(dir, target.value));
+      const fd = tok.dup && /^(?:\d+-?|-)$/.test(target.value);   // `2>&1`, `>&2`, `2>&-`
+      if (tok.writes && !fd && target.value && target.value !== '/dev/null' && target.value !== '-') rawWrites.push(target.value);
       continue;
     }
     seg.push(tok.value);
@@ -103,7 +189,7 @@ export function bashSegments(command: string, cwd: string): BashSegment[] {
   return out;
 }
 
-/** Absolute paths the command writes via redirection, `tee` or `sed -i`, resolved against `cwd`. */
+/** Absolute paths the command writes via redirection, `tee`, `sed -i` or `git --output`, resolved against `cwd`. */
 export function bashWriteTargets(command: string, cwd: string): string[] {
   return bashSegments(command, cwd).flatMap((s) => s.writes);
 }

package/src/hooks/guard-protected-paths.ts

@@ -10,7 +10,8 @@
  *     — the CLI still writes the last two itself; the guard only judges an agent's tool calls
  *   trace evidence — DENY an agent write (phase 08; the verdict trusts it only as far as this guard and git review):
  *     .sungen/trace-identity/**                    (the driver's identity answers — written by the CLI)
- *     test-results/sungen-run-record*.json         (run id + test-file hashes — written by the Playwright reporter)
+ *     test-results[-free]/sungen-run-record*.json  (run id + test-file hashes — written by the Playwright reporter;
+ *                                                  test-results-free/ is the free run's own outputDir, #941)
  *   hook control — ASK before an agent write (the agent must not switch its own guard off):
  *     qa/sungen.config.yaml · .claude/settings.json · .claude/settings.local.json ·
  *     .claude/hooks/sungen-hook.cjs
@@ -25,7 +26,7 @@ const LOCK = /^qa\/(?:.+\/)?contracts\.lock\.yaml$/i;
 const DECISION = /^qa\/(?:(?:screens|flows|api(?:\/flows)?)\/[^/]+\/)?decisions\/[^/]+/i;
 const APPROVAL_STATE = /^\.sungen\/(?:journey\/[^/]+\.state\.json|viewpoint-baseline\.json)$/i;
 /** Trace evidence (phase 08, DOS-14.6): the driver's identity answers and the run records. */
-const TRACE_EVIDENCE = /^(?:\.sungen\/trace-identity\/.+|test-results\/sungen-run-record(?:\.[A-Za-z0-9._-]+)?\.json)$/i;
+const TRACE_EVIDENCE = /^(?:\.sungen\/trace-identity\/.+|test-results(?:-free)?\/sungen-run-record(?:\.[A-Za-z0-9._-]+)?\.json)$/i;
 const HOOK_CONTROL = ['qa/sungen.config.yaml', '.claude/settings.json', '.claude/settings.local.json', '.claude/hooks/sungen-hook.cjs'];
 
 /** The same paths as they appear INSIDE a command string (e.g. in `bash -c "…"` or `python -c "…"`). */
@@ -62,9 +63,18 @@ export function hookControlPath(abs: string): string | null {
   return HOOK_CONTROL.find((rel) => p.endsWith(`/${rel}`)) ?? null;
 }
 
+/** Names near a protected path — for a word the shell expands (`$Q/decisions/x`), whose real text is unknown. */
+const NEAR_PROTECTED = /qa|\.sungen|\.claude|decision|contracts|lock\.ya?ml|run-record|trace-identity|viewpoint|journey|settings|sungen-hook|sungen\.config/i;
+
+/** A word the shell rewrites at runtime (`$…`, a literal `\`) that sits near a protected name: the guard cannot read it. */
+export const opaqueNearProtected = (word: string): boolean => /[$\\]/.test(word) && NEAR_PROTECTED.test(word);
+
+/** Does this text (a command word, a heredoc, a whole command line) name a protected path as written? */
+export const mentionsProtectedText = (text: string): boolean => MENTIONS.some((re) => re.test(text));
+
 /** Does this command word name a protected path — as text, or once resolved against `dir`? */
 export function mentionsProtectedPath(word: string, dir: string): boolean {
-  if (MENTIONS.some((re) => re.test(word))) return true;
+  if (mentionsProtectedText(word)) return true;
   const abs = path.resolve(dir, word);
   return approvalRecordPath(abs) !== null || traceEvidencePath(abs) !== null || hookControlPath(abs) !== null;
 }