savant-code 0.0.16 → 0.0.19

package/common/src/util/zod-schema.ts

@@ -0,0 +1,80 @@
+import z from 'zod/v4'
+
+import type { JSONValue } from '../types/json'
+import type { JSONSchema as JSONSchemaNamespace } from 'zod/v4/core'
+
+type JSONSchema = JSONSchemaNamespace.JSONSchema
+
+/**
+ * Convert a Zod4 schema to JSON string representation.
+ */
+export function schemaToJsonStr(
+  schema: z.ZodTypeAny | undefined | Record<string, JSONValue>,
+  options?: Parameters<typeof z.toJSONSchema>[1],
+): string {
+  if (!schema) return 'None'
+
+  try {
+    // Handle Zod schemas
+    if (schema instanceof z.ZodType) {
+      const jsonSchema = z.toJSONSchema(schema, options)
+      delete jsonSchema['$schema']
+      return JSON.stringify(jsonSchema, null, 2)
+    }
+
+    // Otherwise, pass on plain object
+    return JSON.stringify(schema, null, 2)
+  } catch (error) {
+    return 'None'
+  }
+}
+
+/**
+ * FID-2026-0803-003 CMN-1: zod v4's `z.preprocess` (used by `coerceToArray` /
+ * `coerceToObject`) wraps a property in a pipe whose *input* type is `unknown`,
+ * so `z.toJSONSchema` drops the property from the emitted `required` array —
+ * the model is told the field is optional even though the runtime schema
+ * requires it. This wrapper re-derives `required` from the zod `shape` +
+ * `.isOptional()` (which reports pipes as non-optional), so emitted tool
+ * schemas match their plain counterparts.
+ */
+export function toToolInputJSONSchema(schema: z.ZodType): JSONSchema {
+  const jsonSchema = z.toJSONSchema(schema, { io: 'input' })
+  restoreRequired(schema, jsonSchema as Record<string, JSONValue>)
+  return jsonSchema
+}
+
+function restoreRequired(
+  schema: z.ZodType,
+  jsonSchema: Record<string, JSONValue>,
+): void {
+  if (jsonSchema['type'] !== 'object') return
+
+  const shape = (schema as { shape?: Record<string, z.ZodType> }).shape
+  if (!shape) return
+
+  const required = Object.entries(shape)
+    .filter(([, prop]) => !prop.isOptional())
+    .map(([key]) => key)
+  if (required.length > 0) {
+    jsonSchema['required'] = required
+  } else {
+    delete jsonSchema['required']
+  }
+
+  const properties = jsonSchema['properties']
+  if (
+    properties &&
+    typeof properties === 'object' &&
+    !Array.isArray(properties)
+  ) {
+    const propertySchemas = properties as Record<
+      string,
+      Record<string, JSONValue>
+    >
+    for (const [key, propSchema] of Object.entries(shape)) {
+      const propJson = propertySchemas[key]
+      if (propJson) restoreRequired(propSchema, propJson)
+    }
+  }
+}

package/common/src/util/zoned-time.ts

@@ -0,0 +1,136 @@
+export interface ZonedDateParts {
+  year: number
+  month: number
+  day: number
+  hour: number
+  minute: number
+}
+
+export function getZonedParts(date: Date, timeZone: string): ZonedDateParts {
+  const parts = new Intl.DateTimeFormat('en-US', {
+    timeZone,
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+    hour: '2-digit',
+    minute: '2-digit',
+    hourCycle: 'h23',
+  }).formatToParts(date)
+
+  const get = (type: string) => {
+    const value = parts.find((part) => part.type === type)?.value
+    if (!value) throw new Error(`Missing ${type} in ${timeZone} date parts`)
+    return Number(value)
+  }
+
+  return {
+    year: get('year'),
+    month: get('month'),
+    day: get('day'),
+    hour: get('hour'),
+    minute: get('minute'),
+  }
+}
+
+export function addDaysToYmd(
+  year: number,
+  month: number,
+  day: number,
+  days: number,
+): Pick<ZonedDateParts, 'year' | 'month' | 'day'> {
+  const next = new Date(Date.UTC(year, month - 1, day))
+  next.setUTCDate(next.getUTCDate() + days)
+  return {
+    year: next.getUTCFullYear(),
+    month: next.getUTCMonth() + 1,
+    day: next.getUTCDate(),
+  }
+}
+
+export function getUtcForZonedTime(
+  parts: Pick<ZonedDateParts, 'year' | 'month' | 'day'>,
+  timeZone: string,
+  hour: number,
+  minute: number,
+): Date {
+  let guess = new Date(
+    Date.UTC(parts.year, parts.month - 1, parts.day, hour, minute),
+  )
+
+  for (let i = 0; i < 3; i++) {
+    const actual = getZonedParts(guess, timeZone)
+    const desiredUtc = Date.UTC(
+      parts.year,
+      parts.month - 1,
+      parts.day,
+      hour,
+      minute,
+    )
+    const actualUtc = Date.UTC(
+      actual.year,
+      actual.month - 1,
+      actual.day,
+      actual.hour,
+      actual.minute,
+    )
+    guess = new Date(guess.getTime() + (desiredUtc - actualUtc))
+  }
+
+  return guess
+}
+
+export function getZonedDayBounds(
+  now: Date,
+  timeZone: string,
+): { startsAt: Date; resetsAt: Date } {
+  const nowParts = getZonedParts(now, timeZone)
+  const today = {
+    year: nowParts.year,
+    month: nowParts.month,
+    day: nowParts.day,
+  }
+  const tomorrow = addDaysToYmd(today.year, today.month, today.day, 1)
+
+  return {
+    startsAt: getUtcForZonedTime(today, timeZone, 0, 0),
+    resetsAt: getUtcForZonedTime(tomorrow, timeZone, 0, 0),
+  }
+}
+
+/**
+ * Bounds of the calendar week containing `now` in `timeZone`. `startsAt` is
+ * midnight at the start of the week, `resetsAt` is midnight 7 days later (the
+ * next reset). `weekStartsOn` is 0=Sunday … 6=Saturday; defaults to Monday (1).
+ * Pure calendar math via `addDaysToYmd`, so it handles DST and month/year
+ * boundaries the same way `getZonedDayBounds` does.
+ */
+export function getZonedWeekBounds(
+  now: Date,
+  timeZone: string,
+  weekStartsOn: number = 1,
+): { startsAt: Date; resetsAt: Date } {
+  const nowParts = getZonedParts(now, timeZone)
+  // Day-of-week of the zoned calendar date (0=Sunday). Built from a UTC date so
+  // the weekday is read off the y/m/d only, independent of the actual offset.
+  const dow = new Date(
+    Date.UTC(nowParts.year, nowParts.month - 1, nowParts.day),
+  ).getUTCDay()
+  const daysSinceWeekStart = (dow - weekStartsOn + 7) % 7
+  const weekStart = addDaysToYmd(
+    nowParts.year,
+    nowParts.month,
+    nowParts.day,
+    -daysSinceWeekStart,
+  )
+  const nextWeekStart = addDaysToYmd(
+    weekStart.year,
+    weekStart.month,
+    weekStart.day,
+    7,
+  )
+
+  return {
+    startsAt: getUtcForZonedTime(weekStart, timeZone, 0, 0),
+    resetsAt: getUtcForZonedTime(nextWeekStart, timeZone, 0, 0),
+  }
+}

package/common/src/utils/ask-user-bridge.ts

@@ -0,0 +1,47 @@
+import type {
+  AskUserQuestion,
+  AskUserResponse,
+} from '../tools/params/tool/ask-user'
+
+export type AskUserRequest = {
+  toolCallId: string
+  questions: AskUserQuestion[]
+  resolve: (response: AskUserResponse) => void
+}
+
+type Listener = (request: AskUserRequest | null) => void
+
+let pendingRequest: AskUserRequest | null = null
+const listeners: Listener[] = []
+
+export const AskUserBridge = {
+  request: (toolCallId: string, questions: AskUserQuestion[]) => {
+    return new Promise((resolve) => {
+      pendingRequest = { toolCallId, questions, resolve }
+      notifyListeners()
+    })
+  },
+
+  submit: (response: AskUserResponse) => {
+    if (pendingRequest) {
+      pendingRequest.resolve(response)
+      pendingRequest = null
+      notifyListeners()
+    }
+  },
+
+  getPendingRequest: () => pendingRequest,
+
+  subscribe: (listener: Listener) => {
+    listeners.push(listener)
+    listener(pendingRequest)
+    return () => {
+      const idx = listeners.indexOf(listener)
+      if (idx !== -1) listeners.splice(idx, 1)
+    }
+  },
+}
+
+function notifyListeners() {
+  listeners.forEach((l) => l(pendingRequest))
+}

package/common/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../tsconfig.base.json",
+  "compilerOptions": {
+    "types": ["bun", "node"]
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules"]
+}

package/dev/LEARNINGS.md

@@ -0,0 +1,309 @@
+# LEARNINGS
+
+## Session 2026-08-03: Release-Readiness Audit (FID-2026-0803-012)
+
+**Key Learnings:**
+
+- **"Deleted" files that are still tracked in git are restorable, and their loss is
+  silent.** The 12 eval fixture JSONs were `D` in `git status` (worktree-deleted,
+  unstaged) — the benchmark runner referenced them and failed at startup, but nothing
+  flagged the missing fixtures until the eval was actually run. `git ls-files` +
+  `git cat-file -e HEAD:<path>` confirm restorability. Lesson: before declaring a
+  surface broken, check `git status` for unstaged deletions — the fix may be
+  `git restore`, not new code.
+- **An eval harness that has never been run end-to-end hides real bugs.** Baseline
+  (golden-patch) mode passed 3/3 before this session and looked healthy, but the
+  first evaluate run exposed three genuine defects in sequence: (1) no
+  `agentDefinitions` passed → empty SDK registry → `Invalid agent ID`; (2) cyclic
+  provider error objects crashed `JSON.stringify` in the report writer; (3) a stale
+  golden-patch pre-image failed task application. All three were invisible until a
+  real (or keyed) run exercised the full path. Lesson: baseline-only validation is
+  not validation of the evaluate path.
+- **Environmental credential limits are a legitimate eval outcome — record them,
+  don't paper over them.** The evaluate run failed 0/4 not from harness bugs (those
+  were fixed and proven by tool-call traces) but from free-tier provider rate limits
+  (HTTP 429) and BYOK key rejection. The report tracks baseline 4/4 PASS + evaluate
+  environmental causes + the exact re-run command, so the next operator with a valid
+  Savant backend key can close the gap without re-debugging.
+- **CJK text breaks markdownlint MD060 "aligned" table style** — full-width
+  parentheses/chars compute different display widths. The repo's own convention
+  (Repo Map table) wraps wide tables in `markdownlint-disable MD060`; the zh-CN
+  translation uses the same escape. Don't fight the width math by hand.
+
+**Files touched:** evals/benchmark (fixtures restored + 2 entrypoints), evals/v2
+(harness wiring + report writer + 2 regression tests), evals/v2/tasks/add-fix
+(golden patch), README.zh-CN.md (full regeneration), docs/reports/ (eval run
+tracking doc).
+
+## Session 2026-08-03: Build Artifact Hygiene (FID-2026-0803-011)
+
+**Key Learnings:**
+
+- **Filesystem grep is not git state.** The 0803-010 follow-up note claimed
+  "committed .exe binaries" because a filesystem grep found them — but grep
+  does not respect `.gitignore`. "Is this tracked/committed?" claims must use
+  `git ls-files` / `git check-ignore`, not `grep -r`. The RED pass of this FID
+  caught and corrected the note before any code changed.
+- **Validate build flags against actual outputs.** `build-binary.ts` passes
+  `--sourcemap=none`, yet bun 1.3.11 emits a 21 MB `index.js.map` on every
+  compile. A flag's intent is not its effect — verify the output dir after a
+  real build (which is exactly how the orphan hypothesis was disproven: the
+  map is regenerated, timestamped fresh, and unshipped).
+- **Gitignored + regenerable = safe to purge.** Deleting ~360 MB of stale
+  build artifacts was zero-risk because `git ls-files` confirmed nothing was
+  tracked and the existing build commands (`build:binary`, `savant-free/cli/
+  build.ts`, root `ci`) regenerate everything. Check both halves before
+  deleting: nothing tracked AND a working regeneration path.
+- **A follow-up note is still evidence.** The note that spawned this FID was
+  written hastily after a sweep; it became the FID's RED premise and had to be
+  corrected mid-flight. Notes that will feed FIDs deserve the same evidence
+  rigor as FID findings — it is cheaper to verify once than to correct twice.
+
+## Session 2026-08-03: Database + LLM-Providers LOW Fixes (FID-2026-0803-010)
+
+**Key Learnings:**
+
+- **"Zero consumers" evidence is only as good as the search tool you use.** The RED pass for DB-B reported
+  `agent_configs` had zero consumers — the check silently used `rg`, which isn't on PATH in this repo's bash,
+  so it returned nothing (exit 1) and looked clean. The table actually had one consumer: a test-teardown
+  `DELETE FROM agent_configs;`. Lesson: when a "no references" claim matters, use a tool you can see (grep)
+  and verify the command exists before trusting its empty output.
+- **TransformStream tests must drain concurrently.** A TransformStream's readable side has a high-water mark of
+  1. Writing chunks and only then reading stalls on backpressure forever — the real consumer (`pipeThrough`)
+  pulls continuously. Test helpers should start the read loop before writing, or writes never resolve.
+- **Line-range surgery scripts pay off.** Extracting a 385-line inline transform via a bun script with unique
+  anchors (each asserted exactly-once) turned a risky edit into a deterministic one; the single failure mode
+  (an orphaned closing brace) was caught by typecheck in seconds. Anchor on syntax boundaries (closing braces),
+  not content lines.
+- **The stream-transform simulation was real drift.** `stream-transform.test.ts` tested its own copy of the
+  transform — it could not catch regressions in the most-FID'd code in the repo (0801-007/008/010/011).
+  Extraction into a shared module made the tests exercise the real logic, and the backpressure bug was found
+  immediately. A simulation that can't fail on real changes is worse than no test.
+
+## Session 2026-08-03: ECHO Enforcement Layer Audit (FID-2026-0803-009)
+
+**Key Learnings:**
+
+- **Enforcement docs rot faster than the code they describe.** The runtime FSM gating (tool-executor.ts), SoD
+  (Forge no bash, Detective no writes, Verifier zero-tool), and all 13 Orchestrator tools were verified correct —
+  the only debt was `ECHO.md`'s roster table: the Researcher row predated `researcher-docs` (read_docs), the Forge
+  "restricted" cell listed a bash the agent never had, and the "9 specialized agents" intro silently omitted the 4
+  infra spawnables. Bootstrap docs drift when the roster changes; audits must diff the docs against the
+  *definitions*, not against each other.
+- **A "Restricted Tools" column that lists tools the agent never had is worse than an omission** — it teaches a
+  reader the wrong model. After the fix, ECHO.md's restricted cells name only tools the agent actually has
+  elsewhere or genuinely lacks by design.
+- **`commands.build` can be a partial build and still be the right value** — `bun run ci` (SDK + Savant-Free) is
+  the release pipeline entrypoint; the 9-workspace compile gate is `type_check`. The defect was the comment, not
+  the command. Verify whether config fields are read by code before "fixing" them (grep first — this one was a
+  pure doc surface).
+- **markdownlint catches table column drift** (MD055/MD056) — a fast, reliable check that doc-table edits keep
+  their pipe counts; used it as the runtime half of the double audit.
+
+**Files:** ECHO.md (roster rows + footnote), protocol.config.yaml (build comment), CHANGELOG.md.
+
+## Session 2026-08-03: Evals Benchmark Runner Audit (FID-2026-0803-007)
+
+**Key Learnings:**
+
+- **A "fix" that never compiled is worse than the bug it claimed to fix.** Two findings this session were
+  themselves botched repairs from a prior audit (FID-0802-006): a cast that referenced a nonexistent property
+  (`ReturnType<(typeof pino)['destination']>`) and a "concrete cast instead of any" that still failed tsc
+  (`as unknown as { agentFeedback: unknown[] }` against a 4-field declared type). Both had DEBT comments
+  claiming they were the fix. Lesson: after any type-surgery, run the package typecheck — and note that
+  packages outside the 4-way CI hard gate (sdk/common/agent-runtime/cli) rot silently. The evals package had
+  been failing `tsc` since v0.0.15 with nobody noticing.
+- **`withTimeout` races; it does not abort.** The evals harness wrapped 20-60 minute LLM runs in
+  `withTimeout` — when the timer fired, the promise rejected but the underlying `client.run` kept executing,
+  burning API dollars and holding the event loop. The SDK already supports `signal?: AbortSignal`
+  (run.ts:181/294/546), so the fix was `signal: AbortSignal.timeout(ms)` — abort, don't race.
+- **A zod schema defined but never used is a promise of validation that isn't there.** `JudgingResultSchema`
+  was exported in judge.ts while the code did `output.value as JudgingResult` — malformed model output could
+  produce NaN averages or a TypeError in the formatter. The schema existed precisely for this; wire it up.
+- **Expected-failure probes are not silent-swallow bugs.** `git show <sha>:<path>` failing inside a
+  file-existence check is the ANSWER, not an error — logging a warn per missing file would spam. When an
+  audit flags a bare `catch {`, distinguish "diagnostic swallowed" from "probe outcome" before adding noise.
+- **Median-of-2 with `floor(n/2)` always picks the higher scorer** — a systematic bias in ensemble analysis
+  text when judges disagree. `floor((n-1)/2)` is the true lower median.
+
+## Session 2026-08-03: Code-Map Package Audit (FID-2026-0803-006)
+
+**Key Learnings:**
+
+- **Always-false guard expressions are no guard at all.** `call in {}` only caught the inherited
+  `__proto__`; `toString`/`valueOf`/`hasOwnProperty` collisions crashed the code map (TypeError on
+  `.includes` of an inherited function). When skipping Object.prototype keys, write
+  `call in Object.prototype` explicitly — and add a regression test with a real collision token.
+- **A module-level singleton that caches a rejected init promise turns a transient failure into
+  permanent silent disablement.** A shared in-flight promise with clear-on-rejection plus a one-time
+  warn converts it into a retryable, diagnosable condition.
+- **Removing a defensive cast isn't always "drop the guard too".** `tree.delete?.()` keeps
+  mock/runtime compatibility (structurally-compatible mocks lack `delete`) while dropping the Law-6
+  cast. Cast surgery can accidentally delete the call itself — re-read the final block after editing.
+
+## Session 2026-08-03: Quality Scan Hygiene Fixes (FID-2026-0803-005)
+
+**Key Learnings:**
+
+- **Empty catches in safety nets are silent misclassification, not best-effort.** `captureSnapshot`'s
+  `catch {}` treated every read failure as "file didn't exist" — a rewind would have DELETED an existing
+  file it merely failed to read (EACCES/EISDIR/EMFILE). Distinguish `ENOENT` from everything else even
+  when the fallback looks safe; errno narrowing follows the `paths.ts` idiom (`'code' in err && typeof
+  err.code === 'string'`).
+- **Perf findings deserve a 0-EOF read before severity is assigned.** The same lines that looked like a
+  hot-path sync-IO problem held the actual correctness bug: the sync choice was correct by design
+  (capture-before-write ordering + per-path dedup bounds cost), while the real defect was in the
+  error-handling path.
+- **An unsafe `!` can hide a real undefined path.** `generator!` masked an eval'd handleSteps function
+  returning undefined at runtime; an explicit definite-assignment guard is more robust than the
+  assertion and produces a diagnosable error instead of a misleading generic failure.
+
+## Session 2026-08-03: Quality Sweep + Checkpoint & Rewind (FID-2026-0803-004)
+
+**Key Learnings:**
+
+- **Audit before building: an unwired in-tree primitive beats greenfield.** The checkpoint feature's capture/
+  restore primitive already existed as `file-snapshot-store.ts` with **zero callers** — promoting it into a
+  persistent store was a fraction of the work of building fresh. Always grep for dead-but-purpose-built code
+  before starting a feature.
+- **Session restore ≠ rewind.** Restore resumes the same state; rewind returns the workspace (and optionally the
+  conversation) to an earlier turn. Keep the distinction explicit — conflating them derails scoping.
+- **Sort ties are a test flake source.** Two turns opened back-to-back share a `Date.now()` millisecond, making
+  `b.sort((a, b) => b.startedAt - a.startedAt)` order-dependent and only *sometimes* failing. Always add a
+  deterministic tiebreaker (e.g. `|| b.turnId.localeCompare(a.turnId)`) when the sort key has ms granularity.
+- **Dedup before the expensive op on hot paths.** `captureSnapshot` must check `buffer.files.has(path)` *before*
+  `fs.readFileSync`, so repeated writes to one file read it once, not N times.
+- **Sanitize host-provided ids used in filenames.** The CLI's aiMessageId becomes a checkpoint filename — a
+  `path.basename()` guard is one line and prevents path-like ids from escaping the checkpoint dir.
+- **Checkpoint capture belongs in the write-gate, not the handlers.** Capturing in `executeToolCall` before
+  `write_file`/`str_replace`/`apply_patch` dispatch covers main-agent and subagent writes uniformly (subagents
+  inherit the turn via spawn context) and keeps terminal side effects untracked.
+- **Gate discipline under pressure:** run `eslint --fix` and `prettier --write` *after* the last edit, then
+  re-run the full suites — a late fix (like a same-ms sort flake) only surfaces in full-suite runs, not in the
+  isolated file run.
+
+## Session 2026-07-25-1200: Context Compaction System (FID-085)
+
+**Key Learnings:**
+
+- Context compaction MUST be a runtime service, not a spawned agent. The context-pruner agent inherits the bloated
+  context it's trying to compress — a chicken-and-egg problem. A runtime service operates on the message array directly
+  without needing its own LLM context.
+- Four-layer progressive compaction is the correct architecture: Layer 1 (SNIPE: user-initiated), Layer 2 (MICRO:
+  zero-cost tool result clearing), Layer 3 (AUTO: LLM summarization on threshold), Layer 4 (REACTIVE: emergency
+  truncation on prompt-too-long).
+- Token limits must be wired through the full stack. The UI resolved the correct context window but the runtime never
+  received it — 4 disconnected paths all using different hardcoded values (128k, 200k, 250k, 400k). The resolved value
+  from OpenRouter must flow: CLI → createRunConfig → SDK → loopAgentSteps → ContextCompactor → handleSteps.
+- Allowlist → denylist is almost always the right architectural choice. The `run_readonly_command` allowlist broke on
+  valid Windows commands (findstr, 2>nul). A denylist blocks known-dangerous commands while allowing all others — more
+  maintainable and doesn't break on new/OS-specific commands.
+- Template literals with backticks are dangerous in TypeScript. Rewrote `ECHO_PROTOCOL_INSTRUCTIONS` as array-join to
+  avoid template literal escaping issues. This pattern should be used whenever a large string constant contains
+  backticks.
+- Error messages must include agent context. The "not currently available" error was impossible to debug without knowing
+  which agent hit it. Adding `[agent: ${agentTemplate.id}]` prefix made failures traceable.
+- Reference repos are invaluable for design patterns. hermes-agent (trajectory_compressor.py), openclaw
+  (context-engine), and openclaude (autoCompact/compact/microCompact) provided proven patterns for progressive
+  compaction.
+
+**Agent Behavior / Process:**
+
+- Scope expands when you investigate. Starting from "context fills with no compaction" led to discovering 12 bugs across
+  10 files — never pass over an issue during testing.
+- The Verifier correctly identified 8 issues in the initial design that the Orchestrator overlooked (hostile-attacker
+  safeguards, rollback safety, fallback UX). Independent review is essential.
+- Design reviews must include security analysis from the start. The Verifier caught the missing hostile-attacker
+  safeguard (Q3) that the initial design overlooked.
+
+**Technical Insights:**
+
+- `ContextCompactor` class provides: microCompact (zero cost), shouldAutoCompact (threshold + circuit breaker),
+  reactiveCompact (emergency truncation), static isPromptTooLongError (error detection).
+- Circuit breaker states: healthy → degraded → open → half-open → healthy. Max 3 failures → 5min cooldown.
+- Micro-compact safety: only clear tool results where the paired tool_use has been processed (tool_result exists).
+  Prevents orphaned references.
+- Reactive compact algorithm: preserve first message + last 20% of messages, discard everything else, retry API call once.
+- `maxContextLength` added to `AgentState` type to wire resolved context window from CLI through to handleSteps in savant.ts.
+
+## Session 2026-07-25-1600: Layer 4 Reactive Compact + FID-085 Closure
+
+**Key Learnings:**
+
+- Layer 4 reactive compact catches prompt-too-long errors, aggressively truncates (keep first + last 20%), and retries
+  once. This is the last-resort safety net.
+- `isPromptTooLongError` must match patterns from multiple providers (Anthropic, OpenRouter, etc.) — "prompt is too
+  long", "context_length_exceeded", "maximum context length", "token limit", "too many tokens", "input too long",
+  "request too large".
+- Type casting syntax errors (`as unknown typeof` vs `as unknown as typeof`) are easy to introduce and hard to spot.
+  Always verify with typecheck after edits.
+- FID archival requires: (1) status → closed, (2) file moved to dev/fids/archive/, (3) CHANGELOG entry appended. Missing
+  any step creates orphaned files.
+
+**Agent Behavior / Process:**
+
+- FID-085 took 4 hours to complete across multiple sessions. Breaking complex FIDs into phases (Layer 2, Layer 3, Layer
+  4) made the work manageable.
+- The Recorder agent failed to write FID files (3 attempts) — possible context window or tool availability issue. The
+  Orchestrator wrote FID files directly, which is a Separation of Duties violation but was necessary to make progress.
+
+**Technical Insights:**
+
+- `ContextCompactor.reactiveCompact()` preserves: first message (system/instructions), last 20% of messages (minimum 2),
+  any messages with images (multimodal context).
+- `ContextCompactor.isPromptTooLongError()` is a static method — can be called without instantiation.
+- The catch block in `loopAgentSteps` intercepts prompt-too-long errors before the standard error handling, giving
+  reactive compact a chance to recover.
+
+## Session 2026-07-25-1700: Dev Folder Audit + FID Hygiene
+
+**Key Learnings:**
+
+- Dev folder audit found 32 issues: 1 critical (duplicate FID-085), 17 medium (stale FIDs, naming, docs), 6 low.
+- FID archive hygiene is poor — many FIDs were archived without reaching "closed" status. 17 FIDs had statuses like
+  "created", "analyzed", "fixed", "deferred" despite being in the archive directory.
+- FID naming convention (FID-YYYY-MMDD-NNN-kebab-case) was not consistently followed — 4 FIDs had no date prefix.
+- LEARNINGS.md was missing entries for recent sessions — should be updated as part of session closeout.
+- Duplicate files in dev/fids/ and dev/fids/archive/ create confusion — FID-085 existed in both directories.
+
+**Agent Behavior / Process:**
+
+- Dev folder audits should be run periodically to maintain hygiene.
+- When archiving FIDs, always: (1) set status to "closed", (2) move to archive, (3) append CHANGELOG entry.
+- Bulk operations (sed for status updates, mv for renames) are efficient for fixing multiple files at once.
+
+**Technical Insights:**
+
+- `sed -i 's/^\*\*Status:\*\* .*/\*\*Status:\*\* closed/'` is the correct pattern for bulk-updating FID status in
+  archived files.
+- FID filename format: `FID-YYYY-MMDD-NNN-kebab-case-title.md` — must include date prefix.
+- Non-FID files (_sanity_*.txt) should not be in dev/fids/archive/.
+
+## Session 2026-07-25-2000: FID Ground-Truth Verification (FID-086)
+
+**Key Learnings:**
+
+- FID status metadata can drift from reality. When the Orchestrator reviewed open FIDs, it trusted FID-082's `Status:
+  analyzed` metadata without verifying against the codebase — the code was fully implemented but the FID was never
+  updated. Always verify FID claims against actual code before reporting status.
+- Law 1 (Read 0-EOF Before Touch) applies to status reporting, not just code edits. Reading the FID markdown without
+  reading the codebase is a Law 1 violation.
+- The Cross-Agent Claim Rule covers inter-agent attribution, but FID-vs-codebase verification is a different dimension.
+  FID status drift is a document-reality gap, not an agent-claim gap.
+- FID close-out is part of implementation. When code is written, the FID status MUST be updated in the same session.
+  Leaving FIDs in `analyzed` after implementation creates false negatives for future status reviews.
+- The FID template now requires a "Code Verification Evidence" section and a "Missed Questions" section. These
+  structural additions prevent the two root causes: unchecked metadata and incomplete analysis.
+
+**Agent Behavior / Process:**
+
+- The "run the perfection loop" trigger requires the Thinker to ask "What questions should I have asked when this FID
+  was created, but failed to?" for EVERY open FID. This caught 12 missed questions across 3 FIDs.
+- FIDs should note dependencies on other FIDs. FID-082's commands are non-functional without FID-083's runtime
+  integration — this dependency was never documented.
+- Process fixes (ECHO.md, FID template, LEARNINGS.md) are as important as code fixes. The ground-truth verification gap
+  would recur indefinitely without a process rule.
+
+---
+
+<!-- Add new entries above this line -->