@dzhechkov/harness-core 0.7.4 → 0.7.6

package/src/tg-post.ts

@@ -0,0 +1,192 @@
+import { createHash } from 'node:crypto';
+/**
+ * `dz tg-post` — the pure half: validate an approved draft against what Telegram will accept and
+ * what the channel's own accepted design demands.
+ *
+ * The design is NOT this module's to invent. features/genai-tweets-channel/ carries four ACCEPTED
+ * ADRs (2026-08-04): HTML mode, never MarkdownV2 (18 escapes against 3, one miss is a 400); the
+ * cadence rule "no posts 00:00-06:00 MSK"; link previews off by default because x.com previews in
+ * Telegram have been broken since 2022; and ADR-004's standing order — publishing stays MANUAL, and
+ * autonomous publishing means REVISING the ADR, not flipping a quiet flag. This module only makes
+ * those decisions checkable.
+ *
+ * PURE: no filesystem, no network, no clock — the timestamp arrives as a parameter, or the MSK
+ * night-window rule could not be tested at all.
+ */
+
+/** Tags Bot API accepts in HTML mode (verified against the live docs, Bot API 10.2). */
+export const TG_ALLOWED_TAGS: readonly string[] = [
+  'b', 'strong', 'i', 'em', 'u', 'ins', 's', 'strike', 'del', 'tg-spoiler',
+  'a', 'tg-emoji', 'code', 'pre', 'blockquote',
+];
+
+/** Hard ceiling for `sendMessage.text`, characters after entity parsing. */
+export const TG_TEXT_LIMIT = 4096;
+
+export interface TgHtmlIssue {
+  readonly kind: 'unknown-tag' | 'unclosed-tag' | 'stray-close' | 'bare-ampersand' | 'bare-angle' | 'over-limit' | 'empty';
+  readonly detail: string;
+}
+
+/**
+ * The character count Telegram limits: text WITHOUT the markup. An approximation is stated as one —
+ * entities like tg-emoji count differently — but a draft within this bound by a margin is safe, and
+ * the render prints the number so the author sees the headroom, not a verdict.
+ */
+export function tgVisibleLength(html: string): number {
+  return html.replace(/<[^>]*>/g, '').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&amp;/g, '&').length;
+}
+
+/**
+ * Everything wrong with a draft, or an empty list. One pass, every finding named — a validator that
+ * stops at the first fault sends the author around the loop once per mistake.
+ */
+export function tgPostHtmlIssues(html: string): TgHtmlIssue[] {
+  const issues: TgHtmlIssue[] = [];
+  const text = html.trim();
+  if (text === '') return [{ kind: 'empty', detail: 'the draft is empty — nothing to send' }];
+
+  // Tag balance over the allowed set. Telegram closes nothing for you: an unclosed <b> is a 400.
+  const stack: string[] = [];
+  const tagRe = /<(\/?)([a-zA-Z-]+)((?:\s+[a-zA-Z-]+(?:="[^"]*")?)*)\s*(\/?)>/g;
+  let covered = 0;
+  for (let m = tagRe.exec(text); m !== null; m = tagRe.exec(text)) {
+    covered += 1;
+    const closing = m[1] === '/';
+    const name = (m[2] as string).toLowerCase();
+    const expandable = name === 'blockquote';   // `<blockquote expandable>` is the ADR-003 body form
+    if (!TG_ALLOWED_TAGS.includes(name) && !expandable) {
+      issues.push({ kind: 'unknown-tag', detail: `<${name}> is not a Bot API HTML tag — Telegram answers 400 to tags it does not know` });
+      continue;
+    }
+    if (closing) {
+      if (stack.length === 0 || stack[stack.length - 1] !== name) {
+        issues.push({ kind: 'stray-close', detail: `</${name}> closes nothing that is open — tags must nest, not interleave` });
+      } else {
+        stack.pop();
+      }
+    } else if (m[4] !== '/') {
+      stack.push(name);
+    }
+  }
+  for (const open of stack) {
+    issues.push({ kind: 'unclosed-tag', detail: `<${open}> is never closed — Telegram closes nothing for you, this is a 400` });
+  }
+
+  // Bare & and < outside tags: HTML mode requires entity-escaping exactly these.
+  const outside = text.replace(/<[^>]*>/g, '');
+  if (/&(?!(lt|gt|amp|quot|#\d+|#x[0-9a-fA-F]+);)/.test(outside)) {
+    issues.push({ kind: 'bare-ampersand', detail: 'a bare & outside an entity — HTML mode needs &amp;' });
+  }
+  if (/</.test(outside.replace(/&lt;/g, ''))) {
+    issues.push({ kind: 'bare-angle', detail: 'a bare < that is not a known tag — Telegram reads it as markup and answers 400' });
+  }
+
+  const visible = tgVisibleLength(text);
+  if (visible > TG_TEXT_LIMIT) {
+    issues.push({ kind: 'over-limit', detail: `${visible} visible characters against the ${TG_TEXT_LIMIT} hard limit — cut ${visible - TG_TEXT_LIMIT}` });
+  }
+  void covered;
+  return issues;
+}
+
+export interface TgSendDecision {
+  readonly action: 'send' | 'refuse';
+  readonly reason: string;
+}
+
+/**
+ * May this draft go out NOW?
+ *
+ * The night window is ADR-003's cadence rule, encoded as a refusal with an explicit override rather
+ * than as advice: 00:00-06:00 MSK is when the channel's audience is asleep and its author is too —
+ * a send landing then is far more often a timezone mistake than an intention. `--night` states the
+ * intention; without it the refusal names the local MSK time it computed, so the operator can check
+ * the arithmetic instead of trusting it.
+ */
+/**
+ * The dedup key for a post: sha256 of its VISIBLE text (markup stripped). Two drafts that render
+ * identically in Telegram are the same post even if their HTML differs by a whitespace — the key
+ * must be about what the reader sees, not the bytes (G5, ADR-005).
+ */
+export function tgVisibleSha256(html: string): string {
+  const visible = html.replace(/<[^>]*>/g, '').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&amp;/g, '&');
+  return createHash('sha256').update(visible.trim(), 'utf-8').digest('hex');
+}
+
+/** One recorded send. sha256 is the visible-text key; ts is ISO. */
+/** One journal line. status: 'pending' written BEFORE the send (crash-window guard), 'sent' after
+ *  Telegram accepts. A legacy line with no status is treated as 'sent'. */
+export interface TgSentRecord { readonly sha256: string; readonly ts: string; readonly status?: 'pending' | 'sent' }
+
+export function decideTgSend(input: {
+  readonly issues: readonly TgHtmlIssue[];
+  readonly provenanceOutcome: 'allowed' | 'blocked' | 'not-established' | 'skipped';
+  readonly confirmed: boolean;
+  readonly nowUtcIso: string;
+  readonly nightOverride: boolean;
+  /** G6 stop-cord: a `.dz/tg-post/HALT` file exists. Checked FIRST, before anything else. */
+  readonly halted?: boolean;
+  /** sha256 of THIS post's visible text (tgVisibleSha256) — the G5 dedup key. */
+  readonly sha256?: string;
+  /** The send journal as FACTS (the pure half never reads a file). Undefined ⇒ log unreadable. */
+  readonly sentLog?: readonly TgSentRecord[] | undefined;
+  /** G4 ceiling; default 10 (ADR-003). Sends in the trailing 24h are counted against it. */
+  readonly maxPostsPerDay?: number;
+}): TgSendDecision {
+  // G6 (ADR-001 fail-closed-guard-order): the stop-cord is ABSOLUTE and FIRST — it halts even a
+  // perfect post, before any cheaper check, so no bug in a later gate can route around it.
+  if (input.halted === true) {
+    return { action: 'refuse', reason: 'STOP-CORD engaged (.dz/tg-post/HALT exists) — nothing is published while it is present; remove the file to resume' };
+  }
+  if (input.issues.length > 0) {
+    return { action: 'refuse', reason: `${input.issues.length} formatting issue(s) — Telegram would refuse or mangle this draft` };
+  }
+  // The provenance gate is not optional and "skipped" is not a pass: ADR-002 of the provenance
+  // feature — nothing leaves this machine citing a source that may not.
+  if (input.provenanceOutcome !== 'allowed') {
+    return {
+      action: 'refuse',
+      reason: input.provenanceOutcome === 'skipped'
+        ? 'no provenance manifest was checked — an unchecked draft is not an approved draft'
+        : `the provenance gate said ${input.provenanceOutcome} — nothing goes out citing a source that may not leave this machine`,
+    };
+  }
+  if (!input.confirmed) {
+    return { action: 'refuse', reason: 'publishing is MANUAL by the channel\'s own ADR-004 — pass --send --yes to state the decision out loud' };
+  }
+  const utc = Date.parse(input.nowUtcIso);
+  if (Number.isFinite(utc)) {
+    const mskHour = new Date(utc + 3 * 3600_000).getUTCHours();
+    if (mskHour < 6 && !input.nightOverride) {
+      return { action: 'refuse', reason: `it is ${String(mskHour).padStart(2, '0')}:xx MSK — the channel posts nothing between 00:00 and 06:00 MSK (ADR-003). Pass --night if this is deliberate` };
+    }
+  }
+  // G4/G5 need the journal. An UNREADABLE journal (sentLog undefined) is fail-closed: an unreadable
+  // limit counter does not prove the limit is unreached (Step-0 recall — never invert fail-closed on
+  // an absent/degraded input).
+  if (input.sentLog === undefined) {
+    return { action: 'refuse', reason: 'the send journal could not be read — an unreadable limit/dedup counter cannot show the ceiling is unreached; refusing (fail-closed)' };
+  }
+  // G5 dedup: this exact visible-text post already went out.
+  // G5 dedup covers BOTH a completed send AND an in-flight PENDING record of the same visible text
+  // (Codex A- two-phase): a pending row means a prior attempt reached the send path — do not
+  // double-publish. A stuck pending is surfaced (the CLI warns) and cleared by removing its line.
+  if (input.sha256 !== undefined && input.sentLog.some((r) => r.sha256 === input.sha256)) {
+    const prior = input.sentLog.find((r) => r.sha256 === input.sha256);
+    return { action: 'refuse', reason: (prior && prior.status === 'pending')
+      ? 'a PENDING send of this exact post exists (a prior attempt reached the send path) — refusing to double-publish; if that attempt truly failed, remove its line from .dz/tg-post/sent-log.jsonl and retry'
+      : 'this exact post (by visible text) has already been sent — refusing a duplicate' };
+  }
+  // G4 daily limit: sends in the trailing 24h against the ceiling.
+  const nowMs = Date.parse(input.nowUtcIso);
+  const cutoff = Number.isFinite(nowMs) ? nowMs - 24 * 3600_000 : -Infinity;
+  // Only ACCEPTED sends count against the daily limit — a pending row may never have landed, so it
+  // must not eat the ceiling (mirror of 'record after'): status 'pending' is excluded, 'sent'/legacy counted.
+  const inWindow = input.sentLog.filter((r) => { const t = Date.parse(r.ts); return Number.isFinite(t) && t >= cutoff && r.status !== 'pending'; }).length;
+  const ceiling = typeof input.maxPostsPerDay === 'number' && input.maxPostsPerDay > 0 ? Math.floor(input.maxPostsPerDay) : 10;
+  if (inWindow >= ceiling) {
+    return { action: 'refuse', reason: `daily limit reached: ${inWindow} post(s) sent in the last 24h, ceiling ${ceiling} (ADR-003) — the channel does not exceed its own tempo` };
+  }
+  return { action: 'send', reason: 'stop-cord clear, formatted, provenance-cleared, confirmed, inside hours, not a duplicate, under the daily limit' };
+}

package/src/usage.ts

@@ -146,6 +146,11 @@ export interface UsageLimits {
   readonly sessionBlockHours?: number;
   readonly calibratedAt?: string;
   readonly source?: string;
+  /** Routing must not read the estimated pcts (ADR-001 usage-honesty, FR-3). Legacy
+   *  `_disabledReason` free-text also reads as true — the note WAS the switch, now it is data. */
+  readonly routingDisabled?: boolean;
+  /** Account identity captured at calibration time (FR-4); a login change stales the calibration. */
+  readonly calibrationAccount?: string | null;
 }
 
 export interface UsageModelEstimate {
@@ -178,6 +183,21 @@ export interface UsageEstimate {
   /** Traceability for tests and calibration diagnostics. */
   readonly sessionStartedAt: string | null;
   readonly weeklyStartedAt: string | null;
+  /**
+   * Why the routed pcts are null (ADR-001 usage-honesty): empty ⇔ the numbers are established.
+   * `scan-empty` — recent transcripts exist yet the scan extracted nothing (instrument failure);
+   * `window-miss:*` — samples exist but the configured window filtered them all (misaligned
+   * anchor); `routing-disabled` — config says the estimates must not steer; `calibration-stale` —
+   * the account changed since calibration. A zero pct is legitimate ONLY on a machine with no
+   * recent transcripts at all.
+   */
+  readonly notEstablished: readonly UsageNotEstablishedReason[];
+  /**
+   * The raw estimates when the routed pcts are nulled by `routing-disabled`/`calibration-stale` —
+   * for HUMAN eyes (recalled lesson: an estimated pct must never drive routing until its window is
+   * verified against the provider). Absent when the top-level pcts already carry the numbers.
+   */
+  readonly estimatesNotForRouting?: { readonly sessionPct: number | null; readonly weeklyPct: number | null };
 }
 
 export interface UsageCalibrationInput {
@@ -211,6 +231,8 @@ interface MutableUsageLimits {
   sessionBlockHours?: number;
   calibratedAt?: string;
   source?: string;
+  routingDisabled?: boolean;
+  calibrationAccount?: string | null;
 }
 
 const WEEKDAY_TO_DAY: Record<string, number> = {
@@ -337,10 +359,59 @@ export function normalizeClaudeUsageModelKey(raw: unknown): ClaudeUsageModel | n
   return (CLAUDE_USAGE_MODELS as readonly string[]).includes(key) ? (key as ClaudeUsageModel) : null;
 }
 
+/** Recursive .jsonl collector under a subagents tree — bounded depth, lstat-guarded. */
+function walkTranscriptTree(dir: string, depthLeft: number, out: Array<{ path: string; mtimeMs: number }>): void {
+  if (depthLeft <= 0) return;
+  let entries: string[];
+  try {
+    if (!lstatSync(dir).isDirectory()) return; // symlinked dir ⇒ not walked
+    entries = readdirSync(dir);
+  } catch {
+    return;
+  }
+  for (const e of entries) {
+    const p = join(dir, e);
+    if (e.endsWith('.jsonl')) {
+      const m = regularFileMtime(p);
+      if (m !== null) out.push({ path: p, mtimeMs: m });
+    } else {
+      walkTranscriptTree(p, depthLeft - 1, out);
+    }
+  }
+}
+
 /**
  * The `~/.claude/projects` root (the account-wide transcript store). Overridable via
  * `DZ_CLAUDE_PROJECTS_ROOT` — used by tests to point at a temp tree. Never throws.
  */
+/**
+ * The logged-in account identity, from `~/.claude.json` (oauthAccount email or uuid). Honest null
+ * when unreadable/absent — and null==null is NOT an account change (machines that never expose it
+ * keep the pre-FR-4 behavior). Never throws.
+ */
+export function readClaudeAccountId(): string | null {
+  try {
+    const raw = JSON.parse(readFileSync(join(homedir(), '.claude.json'), 'utf-8')) as {
+      oauthAccount?: { emailAddress?: unknown; accountUuid?: unknown };
+    };
+    const email = raw.oauthAccount?.emailAddress;
+    if (typeof email === 'string' && email !== '') return email;
+    const uuid = raw.oauthAccount?.accountUuid;
+    if (typeof uuid === 'string' && uuid !== '') return uuid;
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/** Closed set of not-established reasons (ADR-001). */
+export type UsageNotEstablishedReason =
+  | 'scan-empty'
+  | 'window-miss:weekly'
+  | 'routing-disabled'
+  | 'calibration-stale:account-changed'
+  | 'calibration-stale:account-unverifiable';
+
 export function claudeProjectsRoot(): string {
   const override = process.env['DZ_CLAUDE_PROJECTS_ROOT'];
   if (typeof override === 'string' && override.length > 0) return override;
@@ -387,6 +458,12 @@ export function readUsageLimits(projectRoot: string): UsageLimits {
 
     if (typeof u['calibratedAt'] === 'string') out.calibratedAt = u['calibratedAt'];
     if (typeof u['source'] === 'string') out.source = u['source'];
+    // routingDisabled: the boolean is authoritative; the legacy free-text note counts as true so
+    // the fleet's existing config disables TODAY, without an edit.
+    if (u['routingDisabled'] === true || typeof u['_disabledReason'] === 'string') out.routingDisabled = true;
+    if (typeof u['calibrationAccount'] === 'string' || u['calibrationAccount'] === null) {
+      out.calibrationAccount = u['calibrationAccount'] as string | null;
+    }
     return out;
   } catch {
     return {};
@@ -440,22 +517,15 @@ function listTranscriptFiles(root: string): Array<{ path: string; mtimeMs: numbe
       continue;
     }
     for (const f of files) {
-      // A session's SUBAGENT transcripts live one level deeper — `<session>/subagents/*.jsonl` — and
-      // carry real, non-duplicated usage that was silently excluded (MEASURED: 27 such files on this
-      // machine). Their tokens are spent exactly like the main loop's.
+      // A session's SUBAGENT transcripts live under `<session>/subagents/` and carry real,
+      // non-duplicated usage that was silently excluded (MEASURED: 27 such files in the first
+      // round). The walk is RECURSIVE with a depth cap: workflow agents write to
+      // `subagents/workflows/wf_*/agent-*.jsonl` — one level deeper than the first fix reached —
+      // and that blind spot alone hid 283.62M weighted tokens across 551 files (MEASURED
+      // 2026-08-24, 7-day window, this machine). Depth 4 covers today's deepest layout plus one
+      // future level; lstat at EVERY step keeps symlinked directories unwalked.
       if (!f.endsWith('.jsonl')) {
-        const nested = join(projDir, f, 'subagents');
-        try {
-          if (!lstatSync(nested).isDirectory()) continue; // no symlinked session/subagent dirs
-          for (const sf of readdirSync(nested)) {
-            if (!sf.endsWith('.jsonl')) continue;
-            const sp = join(nested, sf);
-            const m = regularFileMtime(sp);
-            if (m !== null) out.push({ path: sp, mtimeMs: m });
-          }
-        } catch {
-          /* not a session dir — skip */
-        }
+        walkTranscriptTree(join(projDir, f, 'subagents'), 4, out);
         continue;
       }
       const p = join(projDir, f);
@@ -618,11 +688,13 @@ export function computeUsage(projectRoot: string, now?: number): UsageEstimate {
 
   const samples: Sample[] = [];
   const seen = new Set<string>();
+  let scanFileCount = 0;
   try {
     const files = listTranscriptFiles(claudeProjectsRoot());
     for (const f of files) {
       // mtime prefilter: a file last written before every relevant cutoff cannot contribute.
       if (f.mtimeMs < scanCutoff) continue;
+      scanFileCount += 1;
       extractSamples(f.path, scanCutoff, samples, seen);
     }
   } catch {
@@ -660,11 +732,46 @@ export function computeUsage(projectRoot: string, now?: number): UsageEstimate {
     }
   }
 
+  // ── Establishment gate (ADR-001): a number may only flow to the routed pct fields when the
+  // scan actually established it. Fail-closed in exactly four named ways; the raw estimates stay
+  // visible to humans under estimatesNotForRouting when policy (not measurement) nulls them.
+  const reasons: UsageNotEstablishedReason[] = [];
+  const recentFiles = scanFileCount > 0;
+  if (recentFiles && samples.length === 0) reasons.push('scan-empty');
+  // An IDLE session inside a busy week (block 0, weekly > 0) is a MEASURED zero, not a miss — the
+  // first cut of this gate flagged it and four standing tests rightly reddened. Second narrowing
+  // (cross-family review): a week that JUST reset over an idle machine still scans pre-reset
+  // samples (the session cutoff reaches 10h back), and weekly 0 is then a healthy fresh week. The
+  // true miss signature needs a sample AT or PAST the window start that the window still refuses —
+  // future-stamped (clock skew) or beyond-reset (stale anchor) — exactly d3639bf0's shape.
+  if (
+    weeklyWindow !== null &&
+    weeklyTokens <= 0 &&
+    samples.some((smp) => smp.ts >= weeklyWindow.startedAtMs)
+  ) {
+    reasons.push('window-miss:weekly');
+  }
+  if (limits.routingDisabled === true) reasons.push('routing-disabled');
+  const account = readClaudeAccountId();
+  if (limits.calibrationAccount !== undefined && limits.calibrationAccount !== null) {
+    // A stored identity DEMANDS verification (cross-family review: null-current was fail-open —
+    // an unreadable ~/.claude.json silently reused another account's calibration). A stored null
+    // stays exempt: those machines never claimed an identity to verify.
+    if (account === null) reasons.push('calibration-stale:account-unverifiable');
+    else if (account !== limits.calibrationAccount) reasons.push('calibration-stale:account-changed');
+  }
+  const rawSessionPct = pct(block.tokens, limits.sessionTokenLimit);
+  const rawWeeklyPct = weeklyPct;
+  const measurementBroken = reasons.some((r) => r === 'scan-empty' || r.startsWith('window-miss'));
+  const policyNulled = reasons.some((r) => r === 'routing-disabled' || r.startsWith('calibration-stale'));
+  const gatedSessionPct = measurementBroken || policyNulled ? null : rawSessionPct;
+  const gatedWeeklyPct = measurementBroken || policyNulled ? null : rawWeeklyPct;
+
   return {
     sessionTokens: block.tokens,
     weeklyTokens,
-    sessionPct: pct(block.tokens, limits.sessionTokenLimit),
-    weeklyPct,
+    sessionPct: gatedSessionPct,
+    weeklyPct: gatedWeeklyPct,
     sessionResetsAt: block.resetsAtMs === null ? null : new Date(block.resetsAtMs).toISOString(),
     weeklyResetsAt: weeklyWindow === null ? null : new Date(weeklyWindow.resetsAtMs).toISOString(),
     estimated: true,
@@ -673,6 +780,10 @@ export function computeUsage(projectRoot: string, now?: number): UsageEstimate {
     ...(weeklyBindingModel !== undefined ? { weeklyBindingModel } : {}),
     sessionStartedAt: block.startedAtMs === null ? null : new Date(block.startedAtMs).toISOString(),
     weeklyStartedAt: weeklyWindow === null ? null : new Date(weeklyWindow.startedAtMs).toISOString(),
+    notEstablished: reasons,
+    ...(policyNulled && !measurementBroken
+      ? { estimatesNotForRouting: { sessionPct: rawSessionPct, weeklyPct: rawWeeklyPct } }
+      : {}),
   };
 }
 
@@ -782,6 +893,10 @@ export function deriveUsageCalibration(
   if (changes.length > 0) {
     after.calibratedAt = input.calibratedAt;
     after.source = input.source;
+    // FR-4: a calibration is a claim about ONE account's limits. Stamp whose — a later login under
+    // a different identity then stales it by itself (the 2026-08-24 re-login is the reproducer:
+    // the old anchor kept printing 55% on the new account).
+    after.calibrationAccount = readClaudeAccountId();
   }
 
   return { before, after, changes, skipped };

package/src/writer-quiescence.ts

@@ -0,0 +1,95 @@
+/**
+ * Writer-quiescence probe for Step 8 — feature qe-writer-quiescence (backlog 700b46a4).
+ *
+ * MEASURED (crossrt-1, 2026-08-18): Step-8 graded a MOVING tree — a background worker wrote at
+ * 19:25, 19:32 and 19:46, AFTER the verdict, its last write clobbering a file the same round had
+ * just written. The reviewer hand-waited six consecutive 30-second zero-write windows and
+ * re-measured everything. This module is that wait, as a machine: the same idea the publish gate
+ * already enforces («не публикуй, пока рой жив»), applied to grading.
+ *
+ * A BELT, not the root: mutual exclusion of writers (worktree isolation) is item 9520e506. The
+ * probe therefore NEVER blocks a run — a moving tree downgrades the verdict's standing loudly
+ * instead of stopping the pipeline.
+ *
+ * PURE: the shell script is GENERATED here and executed by a workflow agent (the workflow sandbox
+ * has no child_process — the agent is the shell, same as the landing barrier); the answer is
+ * PARSED here, parse-never-synthesize: an empty or malformed probe is 'inconclusive', never
+ * 'quiet'.
+ */
+
+export interface WriterQuiescenceDecision {
+  readonly verdict: 'quiet' | 'moving' | 'inconclusive';
+  /** Per-window changed counts actually parsed, in order. */
+  readonly windows: readonly number[];
+  readonly note: string;
+}
+
+export const WQ_WINDOW_SECONDS = 20;
+export const WQ_MAX_WINDOWS = 9;
+export const WQ_REQUIRED_QUIET = 3;
+
+/**
+ * The probe script a workflow agent runs verbatim. Polls the declared targets PLUS the feature
+ * dir (FR-4: the feature's own artifacts are exactly the surface crossrt-1 saw clobbered) in
+ * fixed windows; prints one `WQ-WINDOW <n> changed=<count>` line per window and exits early after
+ * `requiredQuiet` consecutive zeros. `find -newermt '-<w+5> seconds'` widens the lookback slightly
+ * past the sleep so a write on the window boundary cannot fall between two polls.
+ */
+export function quiescenceProbeScript(
+  paths: readonly string[],
+  opts?: { windowSeconds?: number; maxWindows?: number; requiredQuiet?: number },
+): string {
+  const w = opts?.windowSeconds ?? WQ_WINDOW_SECONDS;
+  const max = opts?.maxWindows ?? WQ_MAX_WINDOWS;
+  const need = opts?.requiredQuiet ?? WQ_REQUIRED_QUIET;
+  const targets = paths
+    .map((p) => String(p).trim())
+    .filter((p) => p !== '' && !p.startsWith('-') && !p.includes("'"))
+    .map((p) => `'${p.replace(/'/g, '')}'`)
+    .join(' ');
+  const lookback = w + 5;
+  // Cross-family review (round 1, D): find errors — a missing/typo'd target, a permission failure —
+  // used to feed ZERO to `wc -l`, so a probe that could not look reported quiet. Errors now print
+  // `changed=ERR` and the parser refuses to let an ERR window feed a quiet streak.
+  return (
+    `quiet=0; n=0; while [ $n -lt ${max} ]; do n=$((n+1)); sleep ${w}; ` +
+    `out=$(find ${targets} -type f -newermt '-${lookback} seconds' 2>&1 >/tmp/wq-list.$$); st=$?; ` +
+    `if [ $st -ne 0 ] || [ -n "$out" ]; then c=ERR; else c=$(wc -l < /tmp/wq-list.$$); fi; rm -f /tmp/wq-list.$$; ` +
+    `echo "WQ-WINDOW $n changed=$c"; ` +
+    `if [ "$c" = "0" ]; then quiet=$((quiet+1)); if [ $quiet -ge ${need} ]; then echo "WQ-DONE quiet"; exit 0; fi; else quiet=0; fi; ` +
+    `done; echo "WQ-DONE budget"`
+  );
+}
+
+/** Parse the probe transcript into a verdict. Empty/malformed ⇒ inconclusive, never quiet. */
+export function decideWriterQuiescence(probeText: unknown, requiredQuiet = WQ_REQUIRED_QUIET): WriterQuiescenceDecision {
+  const text = probeText === null || probeText === undefined ? '' : String(probeText);
+  // -1 encodes an ERR window (find could not look): it can never join a quiet streak, and its
+  // presence degrades a no-streak outcome to 'inconclusive' — an instrument that failed to observe
+  // must not testify to movement either.
+  const windows: number[] = [];
+  for (const line of text.split(/\r?\n/)) {
+    const m = /WQ-WINDOW\s+\d+\s+changed=(\d+|ERR)/.exec(line);
+    if (m) windows.push(m[1] === 'ERR' ? -1 : Number(m[1]));
+  }
+  if (windows.length === 0) {
+    return { verdict: 'inconclusive', windows, note: 'quiescence probe returned no windows — grading standing NOT established (probe failure is never quiet)' };
+  }
+  let streak = 0;
+  for (const c of windows) {
+    streak = c === 0 ? streak + 1 : 0;
+    if (streak >= requiredQuiet) {
+      // The claim is exactly what was measured (cross-family review): mtime evidence of no recent
+      // writes — never a writer-lifecycle guarantee. The root guarantee is worktree isolation.
+      return { verdict: 'quiet', windows, note: `no observed writes in ${requiredQuiet} consecutive windows (mtime evidence only — not a writer-lifecycle guarantee)` };
+    }
+  }
+  if (windows.some((c) => c < 0)) {
+    return { verdict: 'inconclusive', windows, note: 'quiescence probe could not observe every window (find errored) — grading standing NOT established' };
+  }
+  return {
+    verdict: 'moving',
+    windows,
+    note: `tree is MOVING: no ${requiredQuiet} consecutive quiet windows within budget (per-window changed counts: ${windows.join(',')}) — the verdict below was graded on a moving tree and must say so`,
+  };
+}