@xhulz/nina 0.55.1 → 0.57.0

package/releases/0.57.0/surfaces/money/tree/.claude/patterns.md

@@ -0,0 +1,49 @@
+<!-- nina:slot money.1 -->
+
+---
+
+## Monetary values & percentages
+
+- **Money is an integer of the currency's minor unit**, end to end — {{MINOR_UNIT}}, never a float, never a type that can hold a fraction of one. Source of precision: `{{MONEY_MODULE}}`.
+- **Percentages are basis points** (`40% → 4000`, `100% → 10000`) so a distribution is exact without floating point.
+- **Parsing, formatting and percentage arithmetic live in one module and nowhere else.** A second place that turns a string into money is a second rounding rule, and the two will disagree on a value somebody is owed.
+- **Never** convert to a floating-point type before formatting, and never let a display format round a stored value.
+- Monetary database columns are integer. JSON responses serialize them as **strings**, not numbers, so no client parses them into a float. The service owns the conversion.
+
+<!-- nina:slot money.2 -->
+
+---
+
+## Distribution invariants (enforced by reviewer + unit tests)
+
+The distribution engine lives in `{{CORE_PKG}}`. It is pure and total over integer {{MINOR_UNIT}}:
+
+- A destination is either a percentage (basis points of the amount) or a fixed value.
+- `total = Σ destinations`, computed in {{MINOR_UNIT}}.
+- `total > amount` → **reject.** Never clamp, never distribute what is not there.
+- `total < amount` → **allow**, surface the shortfall, and leave the remainder **parked**. Silence is the defect here: an unexplained remainder is indistinguishable from a bug.
+- `total = amount` → OK.
+- A retention is just another destination — the same arithmetic applies to it, with no special case.
+
+<!-- nina:slot money.3 -->
+
+---
+
+## State machines & idempotency (enforced by reviewer)
+
+- **Every money-moving entity is a state machine.** Its states and legal transitions are declared in `.claude/architecture.md`; the code follows the declaration, not the other way round. Illegal transitions throw; they are never silently coerced.
+- **Every transition writes an audit row** (entity type, entity id, from, to, actor). No transition without a trail — the trail is what makes a money bug diagnosable after the money has moved.
+- **Outbound transfers are idempotent.** Each carries a unique key, and dedupe happens before the side effect, at the serialization point.
+- **One serialization point per balance.** Whatever computes and dispatches against a single balance never runs concurrently with itself. Two concurrent runs over one balance is how a double send happens even when every individual write is correct.
+
+<!-- nina:slot money.4 -->
+- **Money computation and dispatch go through the serialization point.** Routes, queue consumers and tools never run a distribution or a transfer synchronously in the request path.
+
+<!-- nina:slot money.5 -->
+- **The distribution engine lives in `{{CORE_PKG}}`.** Services call it as a pure function; they do not embed money logic inline.
+
+<!-- nina:slot money.6 -->
+- Idempotency on money-moving writes: the record carries an idempotency key, and the serialization point refuses the second attempt *before* the side effect.
+
+<!-- nina:slot money.7 -->
+- `{{CORE_PKG}}` is the most-tested package — pure functions over fixtures. Cover the distribution invariants exhaustively: over, under, exact, mixed percentage and fixed, and rounding.

package/releases/0.57.0/surfaces/money/tree/.claude/pipeline.md

@@ -0,0 +1,2 @@
+<!-- nina:slot money.1 -->
+  - **Money invariants respected** — a distribution never exceeds the amount; a shortfall is parked, not distributed; transfers idempotent; every transition audited.

package/releases/0.57.0/surfaces/money/tree/.claude/retrieval.md

@@ -0,0 +1,2 @@
+<!-- nina:slot money.1 -->
+| New distribution / transfer logic | `.claude/architecture.md` § *Money*, `.claude/patterns.md` § *Distribution invariants*, `{{CORE_PKG}}/` | architect → implementer → reviewer → qa |

package/releases/0.57.0/surfaces/money/tree/CLAUDE.md

@@ -0,0 +1,11 @@
+<!-- nina:slot money.1 -->
+3. **An outbound transfer is idempotent — it is NEVER sent twice.** Every transfer carries an idempotency key, and deduplication happens at a single serialization point **before** the side effect, never after it. A retry, a re-delivered queue message, a double-click and a replayed webhook must all collapse to one transfer. This is the highest-blast-radius invariant in the system: almost everything else can be corrected afterwards, and a duplicated transfer cannot.
+
+<!-- nina:slot money.2 -->
+4. **Conservation — what comes in equals what goes out plus what is retained.** A distribution may NEVER exceed the amount it distributes → **block**. If it is **less**, **alert** and leave the remainder **parked** and visible — never silently distributed, never silently absorbed. All arithmetic is integer {{MINOR_UNIT}}; percentages are basis points. The LLM never computes a monetary value.
+
+<!-- nina:slot money.3 -->
+5. **State-machine integrity.** Every money-moving entity has an explicit set of states and legal transitions, declared in `.claude/architecture.md` § *State machines* — not inferred from whatever code happens to exist. Only declared transitions are legal; an illegal one throws and is never silently coerced. **Every transition writes an audit row** (entity, id, from → to, actor, when). Skipping a state, inventing one, or landing a transition with no audit row is a hard reject.
+
+<!-- nina:slot money.4 -->
+- **money movement**: anything that creates, moves, settles or records a balance

package/releases/0.57.0/surfaces/pii/tree/.claude/agents/dba.md

@@ -0,0 +1,2 @@
+<!-- nina:slot pii.1 -->
+- **Privacy.** No sensitive value in clear text where it must not be. The categories are declared in `.claude/architecture.md` § *Privacy* — they are not decided per query, and not decided by you. **Document bytes live only in the object store, referenced by key: the column holds the key, never the bytes.** Any column the architect's spec flagged for masking must be encrypted at rest. Reject a schema that widens what is stored in the clear.

package/releases/0.57.0/surfaces/pii/tree/.claude/agents/devops.md

@@ -0,0 +1,8 @@
+<!-- nina:slot pii.1 -->
+
+**Point it at an UNAUTHENTICATED route — a sign-in page is the right one.** Never sign in, and never
+screenshot a signed-in page. Accounts on deployed environments hold real personal data, and a
+screenshot or a console dump pulls it into agent transcripts and logs, where it persists and nobody
+ever looks for it again. That is a privacy leak with no upside here: the sign-in page proves
+everything this check is for. It renders from the same bundle, it exercises the same build-time env
+inlining (a missing variable blanks it identically), and it needs no session.

package/releases/0.57.0/surfaces/pii/tree/.claude/agents/reviewer.md

@@ -0,0 +1,8 @@
+<!-- nina:slot pii.1 -->
+- Check for privacy regressions: **no sensitive value in a log, an error message — a library's own included — a URL or a test fixture**, per the categories in `.claude/architecture.md` § *Privacy*; document bytes only in the object store, never plaintext in the database; no leaked secret.
+
+<!-- nina:slot pii.2 -->
+- **privacy** — the privacy check above, in full: no sensitive value in a log, an error message, a
+  URL or a test fixture; document bytes only in the object store; no leaked secret. Where
+  **tenant-and-privacy** is dispatched, its reviewer owns this too and there is no separate one; where
+  it is not, this is a dimension of its own. Either way it is never nobody's.

package/releases/0.57.0/surfaces/pii/tree/.claude/agents/secops.md

@@ -0,0 +1,2 @@
+<!-- nina:slot pii.1 -->
+- **Privacy (Hard Rule #8)** — the categories declared in `.claude/architecture.md` § *Privacy* must never appear in logs, in responses that do not need them, in error paths, or in the database in clear text. Check every endpoint that returns a person's record for fields it includes by accident: a `select` that quietly grew a column is the usual way this leaks. Check the error paths too — they are written last and reviewed least — and what the libraries on them print or carry in their own errors, bound values included.

package/releases/0.57.0/surfaces/pii/tree/.claude/agents/solidity-auditor.md

@@ -0,0 +1,5 @@
+<!-- nina:slot pii.1 -->
+- **Nothing personal reaches the chain.** What is written on-chain is public, permanent, and beyond
+  deletion by anyone — including by you, and including after a subject asks. A hash of a personal
+  identifier is not a protection: it is a lookup table for whoever holds the input set. Reject a
+  personal datum stored in state, emitted in an event, or passed as calldata.

package/releases/0.57.0/surfaces/pii/tree/CLAUDE.md

@@ -0,0 +1,5 @@
+<!-- nina:slot pii.1 -->
+8. **Sensitive personal data is classified, and the classification is enforced.** What counts as sensitive here — identity documents, financial identifiers, anything a person would not expect to be readable by whoever can read a log — is declared in `.claude/architecture.md` § *Privacy*, along with the regime that governs it ({{PRIVACY_REGIME}}). Encrypted at rest. **No sensitive value in a log, an error message, a URL, an analytics event, or an agent transcript** — the places nobody thinks about are exactly the ones that persist. That includes what a library puts in its own errors and prints itself: a database client's error can carry the query and every bound value, and a framework can log a whole error past the logger it was given. A database error is mapped at the data layer to a typed error from a closed list before anything logs or returns it, and a test proves that a bound value it writes reaches no thrown error. Document bytes live only in the object store, referenced by key, never in the database in clear text.
+
+<!-- nina:slot pii.2 -->
+- **personal data**: where it is collected, stored, logged or sent

package/releases/0.57.0/surfaces/prisma/tree/.claude/agents/architect.md

@@ -0,0 +1,2 @@
+<!-- nina:slot prisma.1 -->
+| `prisma-client-api` | a new or changed Prisma query |

package/releases/0.57.0/surfaces/prisma/tree/.claude/agents/dba.md

@@ -0,0 +1,42 @@
+<!-- nina:slot prisma.1 -->
+| `prisma-cli` | **before ANY `prisma` CLI command** — `validate`, `format`, `migrate dev`, `migrate diff`, `migrate deploy`. Flags differ between versions, and one of them (`migrate diff --shadow-database-url` against a live database) destroys the database it points at |
+| `prisma-client-api` | auditing a new or changed query — filters, operators, `$transaction` semantics. Through a driver adapter, cite the adapter's installed source for what a transaction does: the skill describes the default engine, and an adapter can roll back less |
+
+<!-- nina:slot prisma.2 -->
+Neither skill covers a **caching or edge layer sitting on top of the client** — cache strategy,
+edge-client behaviour and the rule about never caching a read that authorizes a write belong to that
+layer's own integration doc, declared like any other integration. A skill does not replace it.
+
+<!-- nina:slot prisma.3 -->
+- **With Prisma, both offline.** Run `pnpm --filter {{DB_PKG_NAME}} exec prisma validate`; it must pass. Then run `prisma migrate diff` in its **offline, file-only form** and read the generated SQL, not just the Prisma delta. Its flags changed in Prisma 7, so read the installed major (`prisma --version`) before writing the command:
+
+   ```
+   # Prisma 6. Compare the PREVIOUS schema against the working one — pure file-to-file, no database.
+   git show HEAD:{{DB_PKG}}/prisma/schema.prisma > /tmp/schema-head.prisma
+   pnpm --filter {{DB_PKG_NAME}} exec prisma migrate diff \
+     --from-schema-datamodel /tmp/schema-head.prisma \
+     --to-schema-datamodel prisma/schema.prisma \
+     --script
+   ```
+
+   From Prisma 7 the two flags are `--from-schema` and `--to-schema`, and the schema engine starts from the
+   datasource in `prisma.config.ts` even for this diff: with none there, it prints nothing and exits 0. For
+   SQLite a placeholder the diff never opens is enough, a `file:` URL under a gitignored directory; for any
+   other provider, find out what the diff opens before you give it one. Never a real database's URL. A first schema has nothing at `HEAD`: diff it `--from-empty`. Compare the output against the
+   hand-written `migration.sql` to confirm the declarative parts match.
+
+   ⚠️ **Do NOT reach for `--from-migrations`.** It looks like the natural choice and it is a trap:
+   Prisma refuses it without a shadow database (`--shadow-database-url`, or from Prisma 7 a
+   `shadowDatabaseUrl` in `prisma.config.ts`), which pushes you toward supplying a database URL — the exact move that destroys databases (below). The file-to-file form above answers the
+   same question with no database involved.
+
+   ⛔ **NEVER point `--shadow-database-url`, `--from-url`, `--to-url`, `--from-schema-datasource` — or, from Prisma 7, a `shadowDatabaseUrl` or the config datasource behind `--from-config-datasource` — at a real database, most of all not the one `{{SECRETS_LOCAL}}` names.** Prisma **executes** the entire migration history against whatever database those flags name, which **DESTROYS ALL DATA** in it. A shadow database must be a disposable, empty database and nothing else. It does not announce itself: the command completes with a reassuring "empty migration" result and no error, having already destroyed everything in the database it was pointed at. If the offline form above cannot answer your question, **STOP and report that to the orchestrator** instead of reaching for a database URL.
+
+<!-- nina:slot prisma.4 -->
+- **Where reads are cached through Prisma Accelerate,** every `findUnique` / `findMany` on a hot read path names its `cacheStrategy` (`ttl` / `swr`), and one that feeds a correctness-critical write names none.
+
+<!-- nina:slot prisma.5 -->
+- **On an edge runtime,** new Prisma code paths use the edge client of the installed major: `@prisma/client/edge` up to Prisma 6; from 7, the client the `prisma-client` generator writes with the platform's `runtime` set, imported from where it is generated — `@prisma/client/edge` fails there with `MODULE_NOT_FOUND`.
+
+<!-- nina:slot prisma.6 -->
+- Run a Prisma command that writes to a real database — `prisma migrate dev`, `migrate deploy`, `migrate reset`, `migrate resolve`, `db push`, `db execute`, `$executeRaw*` — or **any `prisma migrate diff` variant carrying a database URL**, which silently wipes the database it points at.

package/releases/0.57.0/surfaces/prisma/tree/.claude/agents/devops.md

@@ -0,0 +1,11 @@
+<!-- nina:slot prisma.1 -->
+- **`prisma-cli`** — before `migrate deploy` or any other Prisma CLI command against a real database.
+
+<!-- nina:slot prisma.2 -->
+- **Prisma migrations go out with `prisma migrate deploy`**, and nothing else changes a shared database's schema.
+
+<!-- nina:slot prisma.3 -->
+- Run `prisma migrate diff --shadow-database-url <url>` against any live database. It **executes** the migration history against that database, destroying everything in it, and reports success. Use a disposable shadow database or don't run it.
+
+<!-- nina:slot prisma.4 -->
+- Run `prisma migrate reset` against a shared database, ever.

package/releases/0.57.0/surfaces/prisma/tree/.claude/agents/implementer.md

@@ -0,0 +1,2 @@
+<!-- nina:slot prisma.1 -->
+| `prisma-client-api` | a new or changed Prisma query |

package/releases/0.57.0/surfaces/prisma/tree/.claude/agents/integration-tester.md

@@ -0,0 +1,2 @@
+<!-- nina:slot prisma.1 -->
+| `prisma-cli` | a Prisma CLI command |

package/releases/0.57.0/surfaces/prisma/tree/.claude/agents/reviewer.md

@@ -0,0 +1,2 @@
+<!-- nina:slot prisma.1 -->
+| `prisma-client-api` | a new or changed Prisma query |

package/releases/0.57.0/surfaces/prisma/tree/.claude/patterns.md

@@ -0,0 +1,15 @@
+<!-- nina:slot prisma.1 -->
+- **Database table/column names** (Prisma `@map` / `@@map`): `snake_case` in SQL, `camelCase` in TS.
+
+<!-- nina:slot prisma.2 -->
+- Where Prisma reads are cached through Accelerate, `cacheStrategy` lives in `{{DB_PKG}}`: services do not add, strip, or override cache policies.
+
+<!-- nina:slot prisma.3 -->
+
+### Prisma
+
+- Schema lives in `{{DB_PKG}}/prisma/schema.prisma`. Nowhere else.
+- **Never write raw SQL** unless justified in a code comment with perf data.
+- N+1 is solved with `include` / `select`, chosen deliberately.
+- Where reads are cached through Accelerate, every `findUnique` / `findMany` on a hot path defines its `cacheStrategy`, and no direct connection string is embedded in code.
+- Tests run a real Prisma client against a real database; the client is never mocked.

package/releases/0.57.0/surfaces/prisma/tree/CLAUDE.md

@@ -0,0 +1,5 @@
+<!-- nina:slot prisma.1 -->
+| Run any `prisma` CLI command (the database gate, devops, and the integration gate where there is one) | `prisma-cli` | flags differ between versions; `migrate diff --shadow-database-url` against a live DB wiped dev/staging once |
+
+<!-- nina:slot prisma.2 -->
+| Write or audit a Prisma query (architect, implementer, the database gate, reviewer) | `prisma-client-api` | filters, operators, `$transaction` semantics. a caching or edge layer on top of the client is **NOT covered** — its cache strategy belongs to that layer's own integration doc |

package/src/commands/export.mjs

@@ -29,7 +29,7 @@ import { BATCH, SETTLE_MINUTES, contextMode, postScore, postScores, postSpans, s
 import { runOf, transcriptsOf } from '../transcripts.mjs';
 import { exportsDir, snapshotsDir } from '../paths.mjs';
 import { readStoreFile } from '../store.mjs';
-import { readConfig, statusPath, targetOf } from './langfuse.mjs';
+import { readConfig, readStatus, targetOf, writeStatus } from './langfuse.mjs';
 import { projectName } from './stats.mjs';
 import { handsToModel } from '../detectors.mjs';
 import { takeLock } from '../lock.mjs';
@@ -137,11 +137,11 @@ export async function autoExport(slug, records, now = new Date()) {
   const setting = (await readConfig()).projects[slug];
   if (!setting) return null;
   let finding = null;
-  const last = JSON.parse(await readFile(statusPath(slug), 'utf8').catch(() => 'null'));
+  const last = await readStatus(slug);
   if (last?.error && !last.reported) {
     finding = `the export to Langfuse failed (${last.at}) — ${last.error}; \`nina langfuse status\` says where it stands`;
     // Said on every run until the prompt hook hands it to the model, and not after (`handsToModel`).
-    if (handsToModel()) await writeFile(statusPath(slug), JSON.stringify({ ...last, reported: true }));
+    if (handsToModel()) await writeStatus(slug, { ...last, reported: true });
   }
   const sent = await sentOf(slug);
   if (typeof sent === 'string') return finding ?? sent;
@@ -180,9 +180,9 @@ export async function exportCommand(argv, ctx = {}) {
       if (result.spans > 0 || result.scores > 0 || result.error) {
         // The same failure again is not news: it was reported once, and repeating it every turn it is
         // retried would be the noise the detectors exist to remove.
-        const before = JSON.parse(await readFile(statusPath(only), 'utf8').catch(() => 'null'));
+        const before = await readStatus(only);
         const reported = Boolean(result.error && before?.error === result.error && before.reported);
-        await writeFile(statusPath(only), JSON.stringify({ at: new Date().toISOString(), spans: result.spans, scores: result.scores, error: result.error, reported }));
+        await writeStatus(only, { at: new Date().toISOString(), spans: result.spans, scores: result.scores, error: result.error, reported });
       }
       return result.error ? 1 : 0;
     } finally {

package/src/commands/langfuse.mjs

@@ -38,6 +38,35 @@ const SHORT = { full: 'with context', prompts: 'with prompts and reports', none:
 /** Where the background export leaves what it last did, per project. */
 export const statusPath = (slug) => join(exportsDir(), 'langfuse', `${slug}.status.json`);
 
+/**
+ * What the background export last did for a project, or null. The export writes it while each turn's detector reads
+ * it, and a plain write empties the file before it fills it: read in between, it threw in the hook. It is written by
+ * rename now (`writeStatus`); one left unreadable some other way reads as nothing sent.
+ *
+ * @param {string} slug
+ * @returns {Promise<object|null>}
+ */
+export async function readStatus(slug) {
+  try {
+    return JSON.parse(await readFile(statusPath(slug), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Writes it by rename, so a reader finds the last one whole or this one whole.
+ *
+ * @param {string} slug
+ * @param {object} status
+ */
+export async function writeStatus(slug, status) {
+  await mkdir(join(exportsDir(), 'langfuse'), { recursive: true });
+  const tmp = `${statusPath(slug)}.${process.pid}.tmp`;
+  await writeFile(tmp, JSON.stringify(status));
+  await rename(tmp, statusPath(slug));
+}
+
 /**
  * The configuration on disk: keys, host, and the projects that are on.
  *
@@ -163,7 +192,7 @@ export async function langfuse(argv, ctx = {}) {
     const on = Object.entries(config.projects);
     if (on.length === 0) console.log('  no project sends its runs — `nina langfuse on` in one');
     for (const [name, setting] of on) {
-      const last = JSON.parse(await readFile(statusPath(name), 'utf8').catch(() => 'null'));
+      const last = await readStatus(name);
       const said = !last ? 'nothing sent yet' : last.error ? `✗ ${last.at}: ${last.error}` : `last sent ${last.at}: ${last.spans} trace(s), ${last.scores} score(s)`;
       console.log(`  ${projectName(name)}: ${SHORT[contextMode(setting) ?? 'none']}, since ${setting.since.slice(0, 10)} — ${said}`);
     }

package/src/commands/stats.mjs

@@ -592,6 +592,9 @@ function proportionReport(records, stepLimit = () => null, lineLimit = () => nul
       ),
     );
   }
+  if (d.unmeasured) {
+    console.log(note(`${d.unmeasured} implementer round(s) also wrote files through the shell, where no count of lines reaches: their size is not measured.`));
+  }
 }
 
 /**
@@ -646,6 +649,9 @@ export function proportionData(records, stepLimit = () => null, lineLimit = () =
     return limit !== null && r.lines_written > limit;
   });
   const longest = longer.length ? longer.reduce((a, b) => (b.lines_written > a.lines_written ? b : a)) : null;
+  // A round that also wrote through the shell holds only what its edit tools wrote: under the limit, its size is not
+  // measured, not small. One project's implementers wrote most of their files so, and every such round read as 0 lines.
+  const unmeasured = records.filter((r) => r.role === 'implementer' && ranUnder(r, 'stepLines') && r.shell_writes > 0 && !longer.includes(r)).length;
   return {
     rows: rows.map(({ label, cycles: n, designed }) => ({ label, cycles: n, designed })),
     built,
@@ -655,6 +661,7 @@ export function proportionData(records, stepLimit = () => null, lineLimit = () =
       ? { count: over.length, limit: stepLimit(largest.project), largest: largest.files_touched, readM: typeof largest.tokens?.read === 'number' ? Math.round(largest.tokens.read / 1e6) : null }
       : null,
     overLines: longest ? { count: longer.length, limit: lineLimit(longest.project), largest: longest.lines_written } : null,
+    unmeasured,
   };
 }
 

package/src/dashboard.html

@@ -359,7 +359,8 @@ const RENDER = {
       d.proportion ? [el('h3', {}, 'proportion · the size of a change against its chain'),
         table(['largest write', 'cycles', 'with a planner or architect', ''], d.proportion.rows.map((r) => [r.label, String(r.cycles), r.cycles ? `${r.designed} (${pct(r.designed, r.cycles)})` : '—', bar([[r.cycles ? r.designed / r.cycles : 0, 'var(--pink)']])]), [1, 2]),
         d.proportion.over ? el('p', { class: 'note warn' }, `${d.proportion.over.count} implementer round(s) wrote more files than one step may (${d.proportion.over.limit}); the largest wrote ${d.proportion.over.largest}.`) : null,
-        d.proportion.overLines ? el('p', { class: 'note warn' }, `${d.proportion.overLines.count} implementer round(s) wrote more lines than one step may (${d.proportion.overLines.limit}); the largest wrote ${d.proportion.overLines.largest}.`) : null] : null,
+        d.proportion.overLines ? el('p', { class: 'note warn' }, `${d.proportion.overLines.count} implementer round(s) wrote more lines than one step may (${d.proportion.overLines.limit}); the largest wrote ${d.proportion.overLines.largest}.`) : null,
+        d.proportion.unmeasured ? el('p', { class: 'note faint' }, `${d.proportion.unmeasured} implementer round(s) also wrote files through the shell, where no count of lines reaches: their size is not measured.`) : null] : null,
     );
   },
 };

package/src/transcripts.mjs

@@ -124,6 +124,220 @@ const WRITES = { Edit: 'file_path', Write: 'file_path', MultiEdit: 'file_path',
 /** How many lines a text written through an edit tool holds: none for an empty one, a last newline ending one. */
 const linesIn = (text) => (typeof text === 'string' && text.length > 0 ? text.replace(/\n$/, '').split('\n').length : 0);
 
+/** A temporary directory named in a command: what it writes there is scratch, not the tree. */
+const TEMP = /(?:^|[^\w.-])(?:\/private)?\/tmp\/|\/var\/folders\/|\$\{?TMPDIR\b|\bmktemp\b|\/scratchpad\b/;
+
+/** A script, in a heredoc or a quoted `-e`, that opens a file to write it. */
+const SCRIPT_WRITES = /\bopen\([^)\n]*,\s*(?:mode\s*=\s*)?['"](?:w|a|x|r\+)[bt+]?['"]|\.write_(?:text|bytes)\(|\b(?:writeFileSync|appendFileSync|writeFile|appendFile|createWriteStream)\(/;
+
+/** A script's write to a file it names as a literal: the path, judged as the shell's own writes are. */
+const LITERAL_WRITES = [
+  /\bopen\(\s*(['"])([^'"\n]+)\1\s*,\s*(?:mode\s*=\s*)?['"](?:w|a|x|r\+)/g,
+  /\bPath\(\s*(['"])([^'"\n]+)\1\s*\)\.write_(?:text|bytes)\(/g,
+  /\b(?:writeFileSync|appendFileSync|writeFile|appendFile|createWriteStream)\(\s*(['"`])([^'"`\n]+)\1/g,
+];
+
+/** A redirect's own words, which are not a command's last argument. */
+const REDIRECTS = /(?:^|\s)(?:\d?[<>]{1,2}\|?|&>>?)(?:&\d+|\s*\S+)/g;
+
+/** What may stand before a simple command's own name: a function it opens, `do`, `then`, a group, `nohup`. */
+const LEADS = String.raw`^\s*(?:[A-Za-z_][\w-]*\(\)\s*)?(?:(?:do|then|else|time|nohup|\{|\(|!)\s*)*`;
+
+/** A simple command that opens a function's body. */
+const FUNCTION = /^\s*(?:function\s+[A-Za-z_][\w-]*\s*(?:\(\))?|[A-Za-z_][\w-]*\s*\(\))\s*\{/;
+
+/** A `cd` or `pushd`, and where it goes. */
+const CD = new RegExp(String.raw`${LEADS}(?:cd|pushd)\b(?:\s+(\S+))?`);
+
+/**
+ * The shell's own ways to write a file, read in a simple command's words, each with where it writes: the redirect's
+ * or `tee`'s file, the last word of an in-place `sed` or `perl`, of a `cp` or a `mv`; a formatter's `--write` or
+ * `--fix`, `git apply` and `patch` write where the command stands.
+ */
+const SHELL_WRITES = [
+  [/(?:^|[\s;&|(){}])\d?>>?\|?\s*(?!&)(?!\/dev\/(?:null|stdout|stderr)\b)([^\s;&|<>()]+)/, 1],
+  [/(?:^|[\s;&|(])tee\s+(?:-a\s+)?(?!\/dev\/null\b)([^\s;&|<>()-][^\s;&|<>()]*)/, 1],
+  [new RegExp(String.raw`${LEADS}(?:sed|perl)\s+(?:-\S*\s+)*(?:-[a-zA-Z]*i\b|--in-place)`), 'last'],
+  [new RegExp(String.raw`${LEADS}(?:cp|mv)\s`), 'last'],
+  [/\s--(?:write|fix)(?=\s|=|$)/, null],
+  [new RegExp(String.raw`${LEADS}(?:git\s+apply|patch)\b`), null],
+];
+
+/** A simple command that runs an interpreter, whose script — a heredoc, a `-e` or `-c` — may open a file to write. */
+const INTERPRETER = new RegExp(String.raw`${LEADS}(?:[A-Za-z_]\w*=\S*\s+)*(?:(?:pnpm|npx)\s+(?:exec\s+)?)?(?:python3?|node|deno|bun|perl|ruby|tsx)\b`);
+
+/** A quoted word that is only a path or a variable, kept as a word rather than emptied as a string. */
+const PLAIN = /^[\w$./{}~@:+,=-]*$/;
+
+/**
+ * A command's simple commands, in order, as the shell splits them at `&&`, `||`, `;`, `|`, `&` and line ends outside
+ * quotes: each with its text as written, a heredoc's body joined to the command that opened it, and its words — a
+ * quoted path kept, any other quoted string emptied, no body — so that `a > b` in a script, or an arrow function in
+ * `node -e "…"`, is no redirect.
+ *
+ * @param {string} command
+ * @returns {{raw: string, words: string}[]}
+ */
+function simpleCommands(command) {
+  const out = [];
+  let raw = '';
+  let words = '';
+  let quote = null;
+  let opened = 0;
+  const bodies = [];
+  const end = () => {
+    if (raw.trim()) out.push({ raw, words });
+    raw = '';
+    words = '';
+  };
+  for (let i = 0; i < command.length; i += 1) {
+    const c = command[i];
+    const prev = command[i - 1];
+    const next = command[i + 1];
+    if (quote) {
+      raw += c;
+      if (c === '\\' && quote === '"' && next !== undefined) {
+        raw += next;
+        i += 1;
+      } else if (c === quote) {
+        const inside = raw.slice(opened, -1);
+        words += PLAIN.test(inside) ? inside : '""';
+        quote = null;
+      }
+      continue;
+    }
+    if (c === '\\' && next !== undefined) {
+      // A backslash before a line end joins the lines; before anything else, it keeps that character as it is.
+      raw += next === '\n' ? ' ' : c + next;
+      words += next === '\n' ? ' ' : c + next;
+      i += 1;
+      continue;
+    }
+    if (c === '$' && next === '(' && command[i + 2] === '(') {
+      // Arithmetic, `$((1 << n))` or `$((a > b))`: neither a heredoc nor a redirect.
+      let depth = 0;
+      let j = i + 1;
+      for (; j < command.length; j += 1) {
+        if (command[j] === '(') depth += 1;
+        else if (command[j] === ')' && (depth -= 1) === 0) break;
+      }
+      raw += command.slice(i, j + 1);
+      words += '0';
+      i = j;
+      continue;
+    }
+    if (c === "'" || c === '"') {
+      quote = c;
+      raw += c;
+      opened = raw.length;
+      continue;
+    }
+    // A comment runs to the line's end: what it says is not run.
+    if (c === '#' && (prev === undefined || /[\s;&|(]/.test(prev))) {
+      while (i + 1 < command.length && command[i + 1] !== '\n') i += 1;
+      continue;
+    }
+    const heredoc = c === '<' && prev !== '<' ? /^<<(-?)\s*\\?(['"]?)([A-Za-z_][\w.-]*)\2/.exec(command.slice(i)) : null;
+    if (heredoc) {
+      bodies.push({ delimiter: heredoc[3], tabs: heredoc[1] === '-' });
+      raw += heredoc[0];
+      words += '<<';
+      i += heredoc[0].length - 1;
+      continue;
+    }
+    if (c === '\n') {
+      // Each heredoc opened on the line: the lines up to its delimiter, kept with the command that opened it.
+      let at = i + 1;
+      for (const { delimiter, tabs } of bodies.splice(0)) {
+        while (at < command.length) {
+          const stop = command.indexOf('\n', at);
+          const line = command.slice(at, stop === -1 ? command.length : stop);
+          raw += `\n${line}`;
+          at = stop === -1 ? command.length : stop + 1;
+          if ((tabs ? line.replace(/^\t+/, '') : line) === delimiter) break;
+        }
+      }
+      i = at - 1;
+      end();
+      continue;
+    }
+    const pair = (c === '&' || c === '|') && next === c;
+    const pipe = c === '|' && prev !== '>';
+    const background = c === '&' && prev !== '>' && prev !== '<' && next !== '>';
+    if (c === ';' || pair || pipe || background) {
+      end();
+      if (pair || (c === '|' && next === '&')) i += 1;
+      continue;
+    }
+    raw += c;
+    words += c;
+  }
+  end();
+  return out;
+}
+
+/**
+ * Whether a shell command writes a file outside a temporary directory: a redirect into a file, `tee`, `sed -i` or
+ * `perl -i`, `cp` or `mv`, a formatter's `--write` or `--fix`, `git apply` or `patch`, or an interpreter's script that
+ * opens a file to write it. Each write is placed where it lands: a path, a variable the command bound — to a temporary
+ * directory or not — or, for a relative one, where the command stands after its `cd`s, which starts in the project
+ * and keeps its place through a relative `cd`. A variable the command did not bind, a function's `$1`, is nowhere
+ * known, and not counted. One project's implementers wrote their files so, through a script that kept an escape the
+ * edit tools decode, and the count of the edit tools read those rounds as having written nothing. Read from the
+ * command alone, it is a sign, not a count: a script run from a file is missed, and so is one that writes the tree
+ * through a variable while it names a temporary directory.
+ *
+ * @param {string} command - A Bash tool call's command.
+ * @returns {boolean}
+ */
+export function writesThroughShell(command) {
+  if (typeof command !== 'string') return false;
+  const vars = new Map();
+  let here = 'tree';
+  // Where each open subshell's `(` found the command standing: its `cd`s end with it.
+  const outside = [];
+  // A function's body runs where it is called, on what it is given: nowhere this command says.
+  let functions = 0;
+  let standing = here;
+  const place = (target) => {
+    if (typeof target !== 'string' || target === '') return standing;
+    const name = /^\$\{?(\w+|[@*#?$!-])/.exec(target);
+    if (name) return /^\$\{?TMPDIR\b/.test(target) ? 'scratch' : (vars.get(name[1]) ?? 'unknown');
+    if (TEMP.test(target) || target.startsWith('/dev/')) return 'scratch';
+    if (target.startsWith('~') || target.includes('""')) return 'unknown';
+    return target.startsWith('/') ? 'tree' : standing;
+  };
+  for (const { raw, words } of simpleCommands(command)) {
+    const groups = words.replace(/\$\([^()]*\)/g, '');
+    for (let n = /^\s*(\(*)/.exec(groups)[1].length; n > 0; n -= 1) outside.push(here);
+    for (let n = (groups.match(/\)/g) ?? []).length - (groups.match(/\(/g) ?? []).length; n > 0 && outside.length; n -= 1) here = outside.pop();
+    if (FUNCTION.test(words)) functions += 1;
+    standing = functions > 0 ? 'unknown' : here;
+    for (const [, name, value] of words.matchAll(/(?:^|\s)(?:export\s+)?([A-Za-z_]\w*)=(\S*)/g)) vars.set(name, place(value));
+    const cd = CD.exec(words);
+    if (cd) {
+      if (functions === 0) here = cd[1] === undefined ? 'unknown' : place(cd[1]);
+    } else {
+      for (const [rule, at] of SHELL_WRITES) {
+        const found = rule.exec(words);
+        if (!found) continue;
+        const target = at === 'last' ? words.replace(REDIRECTS, ' ').trim().split(/\s+/).at(-1) : at === null ? undefined : found[at];
+        if (place(target) === 'tree') return true;
+      }
+      if (INTERPRETER.test(raw) && SCRIPT_WRITES.test(raw)) {
+        // A script names its files inside it: a literal one is placed; with none, a script that names a temporary
+        // directory is taken to write there.
+        const literal = LITERAL_WRITES.flatMap((re) => [...raw.matchAll(re)].map((m) => m[2]));
+        if (literal.some((path) => place(path) === 'tree')) return true;
+        const names = TEMP.test(raw) || [...vars].some(([v, p]) => p !== 'tree' && new RegExp(`\\$\\{?${v}\\b`).test(raw));
+        if (literal.length === 0 && standing === 'tree' && !names) return true;
+      }
+    }
+    if (functions > 0 && /(?:^|[\s;])\}\s*$/.test(words)) functions -= 1;
+  }
+  return false;
+}
+
 /** The line under a declared verdict that names what the report sends back. */
 const ISSUES = /^\s*ISSUES:(.*)$/;
 
@@ -646,7 +860,7 @@ async function attachAgentDetail(projectDir, dispatches) {
       if (
         run.agent_read_bytes === size &&
         !('resumes' in run) &&
-        [...records, ...later].every((r) => settled(r) && 'round' in r && 'lessons_read' in r && 'tokens' in r && 'files_touched' in r && 'lines_written' in r && 'effort' in r && 'turns' in r && 'prompt_chars' in r)
+        [...records, ...later].every((r) => settled(r) && 'round' in r && 'lessons_read' in r && 'tokens' in r && 'files_touched' in r && 'lines_written' in r && 'shell_writes' in r && 'effort' in r && 'turns' in r && 'prompt_chars' in r)
       ) {
         continue;
       }
@@ -679,6 +893,8 @@ async function attachAgentDetail(projectDir, dispatches) {
          * run wrote, not its diff: an edit made twice counts twice, and a file a shell command changed not at all.
          */
         lines: new Map(),
+        /** Its shell commands that wrote a file outside a temporary directory, which no count of lines reaches. */
+        shellWrites: 0,
         /** The tool calls the round made, by id: over its turns, how many calls each turn sent at once. */
         calls: new Set(),
         /** How long the prompt that opened the round was, in characters; never the prompt. */
@@ -726,6 +942,15 @@ async function attachAgentDetail(projectDir, dispatches) {
             // A torn line loses one edit, not the run's.
           }
         }
+        if (line.includes('"name":"Bash"')) {
+          try {
+            for (const block of JSON.parse(line)?.message?.content ?? []) {
+              if (block?.type === 'tool_use' && block.name === 'Bash' && writesThroughShell(block.input?.command)) round.shellWrites += 1;
+            }
+          } catch {
+            // A torn line loses one command, not the run's.
+          }
+        }
         if (line.includes('"usage"')) {
           try {
             const row = JSON.parse(line);
@@ -808,6 +1033,7 @@ async function attachAgentDetail(projectDir, dispatches) {
           record.effort = spent.effort;
           record.files_touched = round.written.size;
           record.lines_written = [...round.lines.values()].reduce((a, b) => a + b, 0);
+          record.shell_writes = round.shellWrites;
           record.skills = [...round.skills];
           record.lessons_read = round.lessonsRead.size;
           record.lessons_listed = round.lessonsListed;