From 453e332a39df8e1303ab5effbd4726991edf4bff Mon Sep 17 00:00:00 2001
From: anandgupta42 <anand@altimate.ai>
Date: Mon, 23 Mar 2026 22:07:14 -0700
Subject: [PATCH 1/9] skill(data-viz): add lazy init, data-code separation,
 color contrast, icon semantics, field validation, pre-delivery checklist
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Six improvements derived from session learnings — all general, none task-specific:

- component-guide: lazy chart initialization pattern for multi-tab dashboards
  (Chart.js/Recharts/Nivo all render blank in display:none containers)
- component-guide: data-code separation for programmatic HTML generation
  (f-string + JS curly braces cause silent parse failures)
- SKILL.md Design Principles: dynamic color safety rule for external/brand colors
- SKILL.md Design Principles: icon semantics check
- SKILL.md Anti-Patterns: warn against filtering on unvalidated data fields
- SKILL.md: pre-delivery checklist (tabs, fields, contrast, icons, tooltips, mobile)
---
 .opencode/skills/data-viz/SKILL.md            | 15 +++++
 .../data-viz/references/component-guide.md    | 67 +++++++++++++++++++
 2 files changed, 82 insertions(+)

diff --git a/.opencode/skills/data-viz/SKILL.md b/.opencode/skills/data-viz/SKILL.md
index ad6a02169..44f85fedc 100644
--- a/.opencode/skills/data-viz/SKILL.md
+++ b/.opencode/skills/data-viz/SKILL.md
@@ -100,6 +100,8 @@ A single insight might just be one chart with a headline and annotation. Scale c
 - **Responsive**: `min-h-[VALUE]` on all charts. Grid stacks on mobile
 - **Animation**: Entry transitions only, `duration-300` to `duration-500`. Never continuous
 - **Accessibility**: `aria-label` on charts, WCAG AA contrast, don't rely on color alone
+- **Dynamic color safety**: When colors come from external sources (brand palettes, category maps, API data, user config), never apply them directly as text color without a contrast check. Dark colors are invisible on dark card backgrounds. Safe pattern: use the external color only for non-text elements (left border, dot, underline); always use the standard text color (white / `var(--text)`) for the label itself. If color-coded text is required, apply a minimum lightness floor: `color: hsl(from brandColor h s max(l, 60%))`
+- **Icon semantics**: Verify every icon matches its label's actual meaning, not just its visual shape. Common traps: using a rising-trend icon (📈) for metrics where lower is better (latency, error rate, cost); using achievement icons (🏆) for plain counts. When in doubt, use a neutral descriptive icon over a thematic one that could mislead
 
 ### Step 5: Interactivity & Annotations
 
@@ -133,3 +135,16 @@ A single insight might just be one chart with a headline and annotation. Scale c
 - Pie charts > 5 slices — use horizontal bar
 - Unlabeled dual y-axes — use two separate charts
 - Truncated bar axes — always start at zero
+- Filtering or mapping over a field not confirmed to exist in the data export — an undefined field in `.filter()` or `.map()` produces empty arrays or NaN silently, not an error; always validate the exported schema matches what the chart code consumes
+
+## Pre-Delivery Checklist
+
+Before marking a dashboard complete:
+
+- [ ] Every tab / view activated — all charts render (no blank canvases, no unexpected 0–1 axes)
+- [ ] Every field referenced in chart/filter code confirmed present in the data export
+- [ ] All text readable on its background — check explicitly when colors come from external data
+- [ ] All icons match their label's meaning
+- [ ] Tooltips appear on hover for every chart
+- [ ] No chart silently receives an empty dataset — add a visible empty state or console warning
+- [ ] Mobile: grid stacks correctly, no body-level horizontal overflow
diff --git a/.opencode/skills/data-viz/references/component-guide.md b/.opencode/skills/data-viz/references/component-guide.md
index 8f792da07..28a6ce46d 100644
--- a/.opencode/skills/data-viz/references/component-guide.md
+++ b/.opencode/skills/data-viz/references/component-guide.md
@@ -392,3 +392,70 @@ const CalloutLabel = ({ viewBox, label, color = "#1e293b" }: { viewBox?: { x: nu
 ```
 
 **Rules:** Never overlap data. Use `position: "insideTopRight"/"insideTopLeft"` on labels. Pair annotations with tooltips — annotation names the event, tooltip shows the value.
+
+---
+
+## Multi-Tab Dashboard — Lazy Chart Initialization
+
+Charts initialized inside a hidden container (`display:none`) render blank. Chart.js, Recharts, and Nivo all read container dimensions at mount time — a hidden container measures as `0×0`.
+
+**Rule: never initialize a chart until its container is visible.**
+
+```js
+// Vanilla JS pattern
+var _inited = {};
+
+function activateTab(name) {
+  // 1. make the tab visible first
+  document.querySelectorAll('.tab').forEach(el => el.classList.remove('active'));
+  document.getElementById('tab-' + name).classList.add('active');
+  // 2. then initialize charts — only on first visit
+  if (!_inited[name]) {
+    _inited[name] = true;
+    initChartsFor(name);
+  }
+}
+
+activateTab('overview'); // init the default visible tab on page load
+```
+
+Library-specific notes:
+- **Chart.js**: canvas reads as `0×0` inside `display:none` — bars/lines never appear
+- **Recharts `ResponsiveContainer`**: reads `clientWidth = 0` — chart collapses to nothing
+- **Nivo `Responsive*`**: uses `ResizeObserver` — fires once at `0×0`, never re-fires on show
+- **React conditional rendering**: prefer `visibility:hidden` + `position:absolute` over toggling `display:none` if you want charts to stay mounted and pre-rendered
+
+---
+
+## Programmatic Dashboard Generation — Data-Code Separation
+
+When generating a standalone HTML dashboard from a script (Python, shell, etc.), never embed JSON data inside a template string that also contains JavaScript. Curly-brace collisions in f-strings / template literals cause silent JS parse failures that are hard to debug.
+
+**Wrong** — data and JS logic share one f-string, every `{` in JS must be escaped as `{{`:
+
+```python
+html = f"""
+<script>
+  const data = {json.dumps(data)};          // fine
+  const fn = () => {{ return x; }}           // must escape — easy to miss
+  const obj = {{ key: getValue() }};         // one missed escape = blank page
+</script>
+"""
+```
+
+**Right** — separate data from logic entirely:
+
+```python
+# Step 1: write data to its own file — no template string needed
+with open('data.js', 'w') as f:
+    f.write('const DATA = ' + json.dumps(data) + ';')
+
+# Step 2: HTML loads both files; app.js is static and never needs escaping
+```
+
+```html
+<script src="data.js"></script>   <!-- generated, data only -->
+<script src="app.js"></script>    <!-- static, logic only   -->
+```
+
+Benefits: `app.js` is static and independently testable; `data.js` is regenerated without touching logic; no escaping required in either file.

From e664d78769a032371784a239fd48aa6cb4c854fa Mon Sep 17 00:00:00 2001
From: anandgupta42 <anand@altimate.ai>
Date: Tue, 24 Mar 2026 11:22:03 -0700
Subject: [PATCH 2/9] fix: new user detection race condition + telemetry gaps
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

UI Fixes:
- Guard `isFirstTimeUser` on sync status — don't show beginner UI
  while sessions are loading (prevents flash on every startup)
- Make Tips component reactive — tip pool now updates when
  `isFirstTime` changes (was locked at render time)

Telemetry Fixes (privacy-safe):
- Add `first_launch` event — fires once after install, contains only
  version string and is_upgrade boolean. No PII. Opt-out-able.
- Use machine_id as ai.user.id fallback — IMPROVES privacy by
  giving each anonymous user a distinct random UUID instead of
  grouping all non-logged-in users under empty string ""

Documentation:
- telemetry.md: added `first_launch` to event table, new "New User
  Identification" section, "Data Retention" section
- security-faq.md: added "How does Altimate Code identify users?"
  and "What happens on first launch?" sections

All telemetry changes respect existing ALTIMATE_TELEMETRY_DISABLED
opt-out. No PII is ever sent — machine_id is crypto.randomUUID(),
email is SHA-256 hashed.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 docs/docs/reference/security-faq.md             | 17 +++++++++++++++++
 docs/docs/reference/telemetry.md                | 14 ++++++++++++++
 .../opencode/src/altimate/telemetry/index.ts    | 17 ++++++++++++++++-
 .../opencode/src/cli/cmd/tui/component/tips.tsx | 12 +++++++-----
 .../opencode/src/cli/cmd/tui/routes/home.tsx    |  8 +++++++-
 packages/opencode/src/cli/welcome.ts            | 13 +++++++++++++
 6 files changed, 74 insertions(+), 7 deletions(-)

diff --git a/docs/docs/reference/security-faq.md b/docs/docs/reference/security-faq.md
index ce5c8ff4e..71fb87231 100644
--- a/docs/docs/reference/security-faq.md
+++ b/docs/docs/reference/security-faq.md
@@ -126,6 +126,23 @@ Or via environment variable:
 export ALTIMATE_TELEMETRY_DISABLED=true
 ```
 
+### How does Altimate Code identify users for analytics?
+
+- **Logged-in users:** Your email is SHA-256 hashed before sending. We never see your raw email.
+- **Anonymous users:** A random UUID (`crypto.randomUUID()`) is generated on first run and stored at `~/.altimate/machine-id`. This is NOT tied to your hardware, OS, or identity — it's purely random.
+- **Both identifiers** are only sent when telemetry is enabled. Disable with `ALTIMATE_TELEMETRY_DISABLED=true`.
+- **No fingerprinting:** We do not use browser fingerprinting, hardware IDs, MAC addresses, or IP-based tracking.
+
+### What happens on first launch?
+
+A single `first_launch` event is sent containing only:
+
+- The installed version (e.g., "0.5.9")
+- Whether this is a fresh install or upgrade (boolean)
+- Your anonymous machine ID (random UUID)
+
+No code, queries, file paths, or personal information is included. This event helps us understand adoption and is fully opt-out-able.
+
 ## What happens when I authenticate via a well-known URL?
 
 When you run `altimate auth login <url>`, the CLI fetches `<url>/.well-known/altimate-code` to discover the server's auth command. Before executing anything:
diff --git a/docs/docs/reference/telemetry.md b/docs/docs/reference/telemetry.md
index 4535ae72b..e5e8a146e 100644
--- a/docs/docs/reference/telemetry.md
+++ b/docs/docs/reference/telemetry.md
@@ -36,6 +36,7 @@ We collect the following categories of events:
 | `skill_used` | A skill is loaded (skill name and source — `builtin`, `global`, or `project` — no skill content) |
 | `sql_execute_failure` | A SQL execution fails (warehouse type, query type, error message, PII-masked SQL — no raw values) |
 | `core_failure` | An internal tool error occurs (tool name, category, error class, truncated error message, PII-safe input signature, and optionally masked arguments — no raw values or credentials) |
+| `first_launch` | Fired once on first CLI run after installation. Contains version and is_upgrade flag. No PII. |
 
 Each event includes a timestamp, anonymous session ID, CLI version, and an anonymous machine ID (a random UUID stored in `~/.altimate/machine-id`, generated once and never tied to any personal information).
 
@@ -88,6 +89,19 @@ We take your privacy seriously. Altimate Code telemetry **never** collects:
 
 Error messages are truncated to 500 characters and scrubbed of file paths before sending.
 
+### New User Identification
+
+Altimate Code uses two types of anonymous identifiers for analytics, depending on whether you are logged in:
+
+- **Anonymous users (not logged in):** A random UUID is generated using `crypto.randomUUID()` on first run and stored at `~/.altimate/machine-id`. This ID is not tied to your hardware, operating system, or identity — it is purely random and serves only to distinguish one machine from another in aggregate analytics.
+- **Logged-in users (OAuth):** Your email address is SHA-256 hashed before sending. The raw email is never transmitted.
+
+Both identifiers are only sent when telemetry is enabled. Disable telemetry entirely with `ALTIMATE_TELEMETRY_DISABLED=true` or the config option above.
+
+### Data Retention
+
+Telemetry data is sent to Azure Application Insights and retained according to [Microsoft's data retention policies](https://learn.microsoft.com/en-us/azure/azure-monitor/logs/data-retention-configure). We do not maintain a separate data store. To request deletion of your telemetry data, contact privacy@altimate.ai.
+
 ## Network
 
 Telemetry data is sent to Azure Application Insights:
diff --git a/packages/opencode/src/altimate/telemetry/index.ts b/packages/opencode/src/altimate/telemetry/index.ts
index 25ae60415..659cf70d8 100644
--- a/packages/opencode/src/altimate/telemetry/index.ts
+++ b/packages/opencode/src/altimate/telemetry/index.ts
@@ -350,6 +350,15 @@ export namespace Telemetry {
         skill_source: "builtin" | "global" | "project"
         duration_ms: number
       }
+    // altimate_change start — first_launch event for new user counting (privacy-safe: only version + machine_id)
+    | {
+        type: "first_launch"
+        timestamp: number
+        session_id: string
+        version: string
+        is_upgrade: boolean
+      }
+    // altimate_change end
     // altimate_change start — telemetry for skill management operations
     | {
         type: "skill_created"
@@ -618,7 +627,13 @@ export namespace Telemetry {
         iKey: cfg.iKey,
         tags: {
           "ai.session.id": sid || "startup",
-          "ai.user.id": userEmail,
+          // altimate_change start — use machine_id as fallback for anonymous user identification
+          // This IMPROVES privacy: previously all anonymous users shared ai.user.id=""
+          // which made them appear as one mega-user in analytics. Using the random UUID
+          // (already sent as a custom property) gives each machine a distinct identity
+          // without any PII. machine_id is a crypto.randomUUID() stored locally.
+          "ai.user.id": userEmail || machineId || "",
+          // altimate_change end
           "ai.cloud.role": "altimate",
           "ai.application.ver": Installation.VERSION,
         },
diff --git a/packages/opencode/src/cli/cmd/tui/component/tips.tsx b/packages/opencode/src/cli/cmd/tui/component/tips.tsx
index d3b9d9cc0..c2df1e251 100644
--- a/packages/opencode/src/cli/cmd/tui/component/tips.tsx
+++ b/packages/opencode/src/cli/cmd/tui/component/tips.tsx
@@ -47,12 +47,13 @@ const BEGINNER_TIPS = [
 ]
 // altimate_change end
 
-// altimate_change start — first-time user beginner tips
+// altimate_change start — first-time user beginner tips with reactive pool
 export function Tips(props: { isFirstTime?: boolean }) {
   const theme = useTheme().theme
-  const pool = props.isFirstTime ? BEGINNER_TIPS : TIPS
-  const parts = parse(pool[Math.floor(Math.random() * pool.length)])
-  // altimate_change end
+  const tip = createMemo(() => {
+    const pool = props.isFirstTime ? BEGINNER_TIPS : TIPS
+    return parse(pool[Math.floor(Math.random() * pool.length)])
+  })
 
   return (
     <box flexDirection="row" maxWidth="100%">
@@ -60,13 +61,14 @@ export function Tips(props: { isFirstTime?: boolean }) {
         ● Tip{" "}
       </text>
       <text flexShrink={1}>
-        <For each={parts}>
+        <For each={tip()}>
           {(part) => <span style={{ fg: part.highlight ? theme.text : theme.textMuted }}>{part.text}</span>}
         </For>
       </text>
     </box>
   )
 }
+// altimate_change end
 
 const TIPS = [
   "Type {highlight}@{/highlight} followed by a filename to fuzzy search and attach files",
diff --git a/packages/opencode/src/cli/cmd/tui/routes/home.tsx b/packages/opencode/src/cli/cmd/tui/routes/home.tsx
index d16bc5d15..fbbb8cc7c 100644
--- a/packages/opencode/src/cli/cmd/tui/routes/home.tsx
+++ b/packages/opencode/src/cli/cmd/tui/routes/home.tsx
@@ -38,7 +38,13 @@ export function Home() {
     return Object.values(sync.data.mcp).filter((x) => x.status === "connected").length
   })
 
-  const isFirstTimeUser = createMemo(() => sync.data.session.length === 0)
+  // altimate_change start — fix race condition: don't show beginner UI until sessions loaded
+  const isFirstTimeUser = createMemo(() => {
+    // Don't evaluate until sessions have actually loaded (avoid flash of beginner UI)
+    if (sync.status === "loading" || sync.status === "partial") return false
+    return sync.data.session.length === 0
+  })
+  // altimate_change end
   const tipsHidden = createMemo(() => kv.get("tips_hidden", false))
   const showTips = createMemo(() => {
     // Always show tips — first-time users need guidance the most
diff --git a/packages/opencode/src/cli/welcome.ts b/packages/opencode/src/cli/welcome.ts
index f01e7b975..dd77c8b77 100644
--- a/packages/opencode/src/cli/welcome.ts
+++ b/packages/opencode/src/cli/welcome.ts
@@ -3,6 +3,9 @@ import path from "path"
 import os from "os"
 import { Installation } from "../installation"
 import { EOL } from "os"
+// altimate_change start — import Telemetry for first_launch event
+import { Telemetry } from "../altimate/telemetry"
+// altimate_change end
 
 const APP_NAME = "altimate-code"
 const MARKER_FILE = ".installed-version"
@@ -41,6 +44,16 @@ export function showWelcomeBannerIfNeeded(): void {
     // altimate_change end
     const isUpgrade = installedVersion === currentVersion && installedVersion !== "local"
 
+    // altimate_change start — track first launch for new user counting (privacy-safe: only version + machine_id)
+    Telemetry.track({
+      type: "first_launch",
+      timestamp: Date.now(),
+      session_id: "",
+      version: installedVersion,
+      is_upgrade: isUpgrade,
+    })
+    // altimate_change end
+
     if (!isUpgrade) return
 
     const tty = process.stderr.isTTY

From 80b5734e7fd49c0433363f2423ad26bb68b2bf86 Mon Sep 17 00:00:00 2001
From: anandgupta42 <anand@altimate.ai>
Date: Tue, 24 Mar 2026 12:34:23 -0700
Subject: [PATCH 3/9] fix: address code review feedback on new user detection
 and telemetry

- use `~/.altimate/machine-id` existence for robust `is_upgrade` flag
- fix 3-state logic in `isFirstTimeUser` memo to prevent suppressed beginner UI
- prevent tip re-randomization on prop change in `tips.tsx`
- add missing `first_launch` event to telemetry tests
- remove unused import
---
 .../src/cli/cmd/tui/component/tips.tsx        |  7 +-
 .../opencode/src/cli/cmd/tui/routes/home.tsx  |  7 +-
 packages/opencode/src/cli/welcome.ts          | 11 +--
 .../opencode/test/telemetry/telemetry.test.ts | 71 ++++++++++---------
 4 files changed, 54 insertions(+), 42 deletions(-)

diff --git a/packages/opencode/src/cli/cmd/tui/component/tips.tsx b/packages/opencode/src/cli/cmd/tui/component/tips.tsx
index c2df1e251..818edfed0 100644
--- a/packages/opencode/src/cli/cmd/tui/component/tips.tsx
+++ b/packages/opencode/src/cli/cmd/tui/component/tips.tsx
@@ -1,4 +1,4 @@
-import { createMemo, createSignal, For } from "solid-js"
+import { createMemo, For } from "solid-js"
 import { DEFAULT_THEMES, useTheme } from "@tui/context/theme"
 
 const themeCount = Object.keys(DEFAULT_THEMES).length
@@ -50,9 +50,12 @@ const BEGINNER_TIPS = [
 // altimate_change start — first-time user beginner tips with reactive pool
 export function Tips(props: { isFirstTime?: boolean }) {
   const theme = useTheme().theme
+  // Pick random tip index once on mount instead of recalculating randomly when props change
+  // Use useMemo without dependencies so it only evaluates once
+  const tipIndex = Math.random()
   const tip = createMemo(() => {
     const pool = props.isFirstTime ? BEGINNER_TIPS : TIPS
-    return parse(pool[Math.floor(Math.random() * pool.length)])
+    return parse(pool[Math.floor(tipIndex * pool.length)])
   })
 
   return (
diff --git a/packages/opencode/src/cli/cmd/tui/routes/home.tsx b/packages/opencode/src/cli/cmd/tui/routes/home.tsx
index fbbb8cc7c..a702e3af2 100644
--- a/packages/opencode/src/cli/cmd/tui/routes/home.tsx
+++ b/packages/opencode/src/cli/cmd/tui/routes/home.tsx
@@ -41,7 +41,8 @@ export function Home() {
   // altimate_change start — fix race condition: don't show beginner UI until sessions loaded
   const isFirstTimeUser = createMemo(() => {
     // Don't evaluate until sessions have actually loaded (avoid flash of beginner UI)
-    if (sync.status === "loading" || sync.status === "partial") return false
+    // Return undefined to represent "loading" state
+    if (sync.status === "loading" || sync.status === "partial") return undefined
     return sync.data.session.length === 0
   })
   // altimate_change end
@@ -133,7 +134,7 @@ export function Home() {
           />
         </box>
         {/* altimate_change start — first-time onboarding hint */}
-        <Show when={isFirstTimeUser()}>
+        <Show when={isFirstTimeUser() === true}>
           <box width="100%" maxWidth={75} paddingTop={1} flexShrink={0}>
             <text>
               <span style={{ fg: theme.textMuted }}>Get started: </span>
@@ -152,7 +153,7 @@ export function Home() {
         <box height={4} minHeight={0} width="100%" maxWidth={75} alignItems="center" paddingTop={3} flexShrink={1}>
           <Show when={showTips()}>
             {/* altimate_change start — pass first-time flag for beginner tips */}
-            <Tips isFirstTime={isFirstTimeUser()} />
+            <Tips isFirstTime={isFirstTimeUser() === true} />
             {/* altimate_change end */}
           </Show>
         </box>
diff --git a/packages/opencode/src/cli/welcome.ts b/packages/opencode/src/cli/welcome.ts
index dd77c8b77..7e650a062 100644
--- a/packages/opencode/src/cli/welcome.ts
+++ b/packages/opencode/src/cli/welcome.ts
@@ -39,10 +39,13 @@ export function showWelcomeBannerIfNeeded(): void {
     // Remove marker first to avoid showing twice even if display fails
     fs.unlinkSync(markerPath)
 
-    // altimate_change start — VERSION is already normalized (no "v" prefix)
-    const currentVersion = Installation.VERSION
+    // altimate_change start — use ~/.altimate/machine-id existence as a proxy for upgrade vs fresh install
+    // Since postinstall.mjs always writes the current version to the marker file, we can't reliably
+    // use installedVersion !== currentVersion for release builds. Instead, if machine-id exists,
+    // they've run the CLI before.
+    const machineIdPath = path.join(os.homedir(), ".altimate", "machine-id")
+    const isUpgrade = fs.existsSync(machineIdPath)
     // altimate_change end
-    const isUpgrade = installedVersion === currentVersion && installedVersion !== "local"
 
     // altimate_change start — track first launch for new user counting (privacy-safe: only version + machine_id)
     Telemetry.track({
@@ -64,7 +67,7 @@ export function showWelcomeBannerIfNeeded(): void {
     const reset = "\x1b[0m"
     const bold = "\x1b[1m"
 
-    const v = `altimate-code v${currentVersion} installed`
+    const v = `altimate-code v${installedVersion} installed`
     const lines = [
       "",
       "  Get started:",
diff --git a/packages/opencode/test/telemetry/telemetry.test.ts b/packages/opencode/test/telemetry/telemetry.test.ts
index b8f4b1fb1..f1b7990eb 100644
--- a/packages/opencode/test/telemetry/telemetry.test.ts
+++ b/packages/opencode/test/telemetry/telemetry.test.ts
@@ -231,8 +231,12 @@ describe("telemetry.event-types", () => {
       "warehouse_discovery",
       "warehouse_census",
       "core_failure",
+      "first_launch",
+      "skill_created",
+      "skill_installed",
+      "skill_removed",
     ]
-    expect(eventTypes.length).toBe(33)
+    expect(eventTypes.length).toBe(37)
   })
 })
 
@@ -352,6 +356,10 @@ describe("telemetry.naming-convention", () => {
       "warehouse_discovery",
       "warehouse_census",
       "core_failure",
+      "first_launch",
+      "skill_created",
+      "skill_installed",
+      "skill_removed",
     ]
     for (const t of types) {
       expect(t).toMatch(/^[a-z][a-z0-9_]*$/)
@@ -418,8 +426,7 @@ describe("telemetry.parseConnectionString (indirect)", () => {
 
     try {
       delete process.env.ALTIMATE_TELEMETRY_DISABLED
-      process.env.APPLICATIONINSIGHTS_CONNECTION_STRING =
-        "IngestionEndpoint=https://example.com"
+      process.env.APPLICATIONINSIGHTS_CONNECTION_STRING = "IngestionEndpoint=https://example.com"
       await Telemetry.init()
 
       Telemetry.track({
@@ -734,8 +741,7 @@ describe("telemetry.flush", () => {
 
     try {
       delete process.env.ALTIMATE_TELEMETRY_DISABLED
-      process.env.APPLICATIONINSIGHTS_CONNECTION_STRING =
-        "InstrumentationKey=k;IngestionEndpoint=https://e.com"
+      process.env.APPLICATIONINSIGHTS_CONNECTION_STRING = "InstrumentationKey=k;IngestionEndpoint=https://e.com"
       await Telemetry.init()
 
       Telemetry.track({
@@ -770,8 +776,7 @@ describe("telemetry.flush", () => {
 
     try {
       delete process.env.ALTIMATE_TELEMETRY_DISABLED
-      process.env.APPLICATIONINSIGHTS_CONNECTION_STRING =
-        "InstrumentationKey=k;IngestionEndpoint=https://e.com"
+      process.env.APPLICATIONINSIGHTS_CONNECTION_STRING = "InstrumentationKey=k;IngestionEndpoint=https://e.com"
       await Telemetry.init()
 
       Telemetry.track({
@@ -810,8 +815,7 @@ describe("telemetry.flush", () => {
 
     try {
       delete process.env.ALTIMATE_TELEMETRY_DISABLED
-      process.env.APPLICATIONINSIGHTS_CONNECTION_STRING =
-        "InstrumentationKey=k;IngestionEndpoint=https://e.com"
+      process.env.APPLICATIONINSIGHTS_CONNECTION_STRING = "InstrumentationKey=k;IngestionEndpoint=https://e.com"
       await Telemetry.init()
 
       Telemetry.track({
@@ -858,8 +862,7 @@ describe("telemetry.flush", () => {
 
     try {
       delete process.env.ALTIMATE_TELEMETRY_DISABLED
-      process.env.APPLICATIONINSIGHTS_CONNECTION_STRING =
-        "InstrumentationKey=k;IngestionEndpoint=https://e.com"
+      process.env.APPLICATIONINSIGHTS_CONNECTION_STRING = "InstrumentationKey=k;IngestionEndpoint=https://e.com"
       await Telemetry.init()
 
       Telemetry.track({
@@ -894,8 +897,7 @@ describe("telemetry.flush", () => {
 
     try {
       delete process.env.ALTIMATE_TELEMETRY_DISABLED
-      process.env.APPLICATIONINSIGHTS_CONNECTION_STRING =
-        "InstrumentationKey=k;IngestionEndpoint=https://e.com"
+      process.env.APPLICATIONINSIGHTS_CONNECTION_STRING = "InstrumentationKey=k;IngestionEndpoint=https://e.com"
       await Telemetry.init()
 
       // Fill buffer beyond MAX_BUFFER_SIZE (200) to trigger drops
@@ -917,8 +919,8 @@ describe("telemetry.flush", () => {
       const envelopes = JSON.parse(fetchBodies[0])
       // Should include a TelemetryBufferOverflow error event
       const overflowEvent = envelopes.find(
-        (e: any) => e.data?.baseData?.name === "error" &&
-          e.data?.baseData?.properties?.error_name === "TelemetryBufferOverflow",
+        (e: any) =>
+          e.data?.baseData?.name === "error" && e.data?.baseData?.properties?.error_name === "TelemetryBufferOverflow",
       )
       expect(overflowEvent).toBeDefined()
       expect(overflowEvent.data.baseData.properties.error_message).toContain("10 events dropped")
@@ -970,8 +972,7 @@ describe("telemetry.shutdown", () => {
 
     try {
       delete process.env.ALTIMATE_TELEMETRY_DISABLED
-      process.env.APPLICATIONINSIGHTS_CONNECTION_STRING =
-        "InstrumentationKey=k;IngestionEndpoint=https://e.com"
+      process.env.APPLICATIONINSIGHTS_CONNECTION_STRING = "InstrumentationKey=k;IngestionEndpoint=https://e.com"
       await Telemetry.init()
 
       Telemetry.track({
@@ -1005,8 +1006,7 @@ describe("telemetry.shutdown", () => {
 
     try {
       delete process.env.ALTIMATE_TELEMETRY_DISABLED
-      process.env.APPLICATIONINSIGHTS_CONNECTION_STRING =
-        "InstrumentationKey=k;IngestionEndpoint=https://e.com"
+      process.env.APPLICATIONINSIGHTS_CONNECTION_STRING = "InstrumentationKey=k;IngestionEndpoint=https://e.com"
       await Telemetry.init()
 
       Telemetry.setContext({ sessionId: "sess-1", projectId: "proj-1" })
@@ -1060,8 +1060,7 @@ describe("telemetry.shutdown", () => {
 
     try {
       delete process.env.ALTIMATE_TELEMETRY_DISABLED
-      process.env.APPLICATIONINSIGHTS_CONNECTION_STRING =
-        "InstrumentationKey=k;IngestionEndpoint=https://e.com"
+      process.env.APPLICATIONINSIGHTS_CONNECTION_STRING = "InstrumentationKey=k;IngestionEndpoint=https://e.com"
       await Telemetry.init()
       await Telemetry.shutdown()
 
@@ -1101,8 +1100,7 @@ describe("telemetry.buffer overflow", () => {
 
     try {
       delete process.env.ALTIMATE_TELEMETRY_DISABLED
-      process.env.APPLICATIONINSIGHTS_CONNECTION_STRING =
-        "InstrumentationKey=k;IngestionEndpoint=https://e.com"
+      process.env.APPLICATIONINSIGHTS_CONNECTION_STRING = "InstrumentationKey=k;IngestionEndpoint=https://e.com"
       await Telemetry.init()
 
       // Track 250 events — first 50 should be dropped
@@ -1158,8 +1156,7 @@ describe("telemetry.buffer overflow", () => {
 
     try {
       delete process.env.ALTIMATE_TELEMETRY_DISABLED
-      process.env.APPLICATIONINSIGHTS_CONNECTION_STRING =
-        "InstrumentationKey=k;IngestionEndpoint=https://e.com"
+      process.env.APPLICATIONINSIGHTS_CONNECTION_STRING = "InstrumentationKey=k;IngestionEndpoint=https://e.com"
       await Telemetry.init()
 
       // Exactly 205 events — 5 should be dropped
@@ -1211,8 +1208,7 @@ describe("telemetry.init with enabled telemetry", () => {
 
     try {
       delete process.env.ALTIMATE_TELEMETRY_DISABLED
-      process.env.APPLICATIONINSIGHTS_CONNECTION_STRING =
-        "InstrumentationKey=k;IngestionEndpoint=https://e.com"
+      process.env.APPLICATIONINSIGHTS_CONNECTION_STRING = "InstrumentationKey=k;IngestionEndpoint=https://e.com"
       await Telemetry.init()
 
       // If flush timer is set up, tracking + waiting should eventually trigger flush
@@ -1316,8 +1312,7 @@ describe("telemetry.init with enabled telemetry", () => {
 
     try {
       delete process.env.ALTIMATE_TELEMETRY_DISABLED
-      process.env.APPLICATIONINSIGHTS_CONNECTION_STRING =
-        "InstrumentationKey=k;IngestionEndpoint=https://e.com"
+      process.env.APPLICATIONINSIGHTS_CONNECTION_STRING = "InstrumentationKey=k;IngestionEndpoint=https://e.com"
 
       const p1 = Telemetry.init()
       const p2 = Telemetry.init()
@@ -1450,6 +1445,18 @@ describe("telemetry.memory", () => {
       })
     }).not.toThrow()
   })
+
+  test("track accepts first_launch event without throwing", () => {
+    expect(() => {
+      Telemetry.track({
+        type: "first_launch",
+        timestamp: Date.now(),
+        session_id: "",
+        version: "0.5.9",
+        is_upgrade: false,
+      })
+    }).not.toThrow()
+  })
 })
 
 // ---------------------------------------------------------------------------
@@ -1483,8 +1490,7 @@ describe("Telemetry.isEnabled()", () => {
     spyOn(global, "fetch").mockImplementation(async () => new Response("", { status: 200 }))
     try {
       delete process.env.ALTIMATE_TELEMETRY_DISABLED
-      process.env.APPLICATIONINSIGHTS_CONNECTION_STRING =
-        "InstrumentationKey=k;IngestionEndpoint=https://e.com"
+      process.env.APPLICATIONINSIGHTS_CONNECTION_STRING = "InstrumentationKey=k;IngestionEndpoint=https://e.com"
       await Telemetry.init()
       expect(Telemetry.isEnabled()).toBe(true)
     } finally {
@@ -1501,8 +1507,7 @@ describe("Telemetry.isEnabled()", () => {
     spyOn(global, "fetch").mockImplementation(async () => new Response("", { status: 200 }))
     try {
       delete process.env.ALTIMATE_TELEMETRY_DISABLED
-      process.env.APPLICATIONINSIGHTS_CONNECTION_STRING =
-        "InstrumentationKey=k;IngestionEndpoint=https://e.com"
+      process.env.APPLICATIONINSIGHTS_CONNECTION_STRING = "InstrumentationKey=k;IngestionEndpoint=https://e.com"
       await Telemetry.init()
       expect(Telemetry.isEnabled()).toBe(true)
       await Telemetry.shutdown()

From 2e784ddf7123d0df11b3834049582c89c37d23af Mon Sep 17 00:00:00 2001
From: anandgupta42 <anand@altimate.ai>
Date: Tue, 24 Mar 2026 13:45:20 -0700
Subject: [PATCH 4/9] =?UTF-8?q?fix:=20address=20CodeRabbit=20review=20?=
 =?UTF-8?q?=E2=80=94=20Nivo=20description=20+=20marker=20guard?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Correct Nivo `Responsive*` behavior: `ResizeObserver` does re-fire
  when container becomes visible, not "never re-fires on show"
- Add `altimate_change` marker around `installedVersion` banner line

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .opencode/skills/data-viz/references/component-guide.md | 2 +-
 packages/opencode/src/cli/welcome.ts                    | 2 ++
 2 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/.opencode/skills/data-viz/references/component-guide.md b/.opencode/skills/data-viz/references/component-guide.md
index 28a6ce46d..4e2716838 100644
--- a/.opencode/skills/data-viz/references/component-guide.md
+++ b/.opencode/skills/data-viz/references/component-guide.md
@@ -422,7 +422,7 @@ activateTab('overview'); // init the default visible tab on page load
 Library-specific notes:
 - **Chart.js**: canvas reads as `0×0` inside `display:none` — bars/lines never appear
 - **Recharts `ResponsiveContainer`**: reads `clientWidth = 0` — chart collapses to nothing
-- **Nivo `Responsive*`**: uses `ResizeObserver` — fires once at `0×0`, never re-fires on show
+- **Nivo `Responsive*`**: uses `ResizeObserver` via `useMeasure`/`useDimensions` in `@nivo/core` — initially measures `0×0` when hidden and skips rendering; re-measures and re-renders correctly when container becomes visible, but the initial blank frame can cause a flash
 - **React conditional rendering**: prefer `visibility:hidden` + `position:absolute` over toggling `display:none` if you want charts to stay mounted and pre-rendered
 
 ---
diff --git a/packages/opencode/src/cli/welcome.ts b/packages/opencode/src/cli/welcome.ts
index 7e650a062..2b08a79b3 100644
--- a/packages/opencode/src/cli/welcome.ts
+++ b/packages/opencode/src/cli/welcome.ts
@@ -67,7 +67,9 @@ export function showWelcomeBannerIfNeeded(): void {
     const reset = "\x1b[0m"
     const bold = "\x1b[1m"
 
+    // altimate_change start — use installedVersion (from marker) instead of currentVersion for accurate banner
     const v = `altimate-code v${installedVersion} installed`
+    // altimate_change end
     const lines = [
       "",
       "  Get started:",

From 946ec9fc7709835f72d07211414fa34a04656a98 Mon Sep 17 00:00:00 2001
From: anandgupta42 <anand@altimate.ai>
Date: Tue, 24 Mar 2026 16:37:23 -0700
Subject: [PATCH 5/9] fix: [AI-450] auto-refresh stale files in `edit` and
 `write` tools instead of failing

When a file is modified externally (by a formatter, linter, or file watcher) between
a read and edit/write, the tools now auto-refresh the read timestamp and re-read the
file contents instead of throwing "modified since it was last read".

This prevents the agent from entering retry loops of hundreds of consecutive failures
when external processes modify files during editing sessions.

Changes:
- Add `FileTime.assertOrRefresh()` that returns `{ stale: boolean }` instead of throwing
- Update `EditTool` and `WriteTool` to use `assertOrRefresh()` and re-read file contents
- Update test to verify auto-refresh behavior
- Original `FileTime.assert()` preserved for backward compatibility

Closes #450

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 packages/opencode/src/file/time.ts       | 32 ++++++++++++++++++++++++
 packages/opencode/src/tool/edit.ts       |  4 ++-
 packages/opencode/src/tool/write.ts      |  4 ++-
 packages/opencode/test/tool/edit.test.ts | 27 +++++++++++---------
 4 files changed, 53 insertions(+), 14 deletions(-)

diff --git a/packages/opencode/src/file/time.ts b/packages/opencode/src/file/time.ts
index efb1c4376..9b2888cf6 100644
--- a/packages/opencode/src/file/time.ts
+++ b/packages/opencode/src/file/time.ts
@@ -68,4 +68,36 @@ export namespace FileTime {
       )
     }
   }
+
+  /**
+   * Check if a file has been modified since last read. Instead of throwing,
+   * returns whether the file was stale and auto-refreshes the read timestamp
+   * so the caller can re-read contents and proceed.
+   *
+   * Returns:
+   * - { stale: false } if file is up-to-date
+   * - { stale: true } if file was modified externally (timestamp refreshed)
+   *
+   * Still throws if the file was never read in this session.
+   */
+  // altimate_change start — auto-refresh stale files instead of throwing (#450)
+  export async function assertOrRefresh(
+    sessionID: string,
+    filepath: string,
+  ): Promise<{ stale: boolean }> {
+    if (Flag.OPENCODE_DISABLE_FILETIME_CHECK === true) {
+      return { stale: false }
+    }
+
+    const time = get(sessionID, filepath)
+    if (!time) throw new Error(`You must read file ${filepath} before overwriting it. Use the Read tool first`)
+    const mtime = Filesystem.stat(filepath)?.mtime
+    if (mtime && mtime.getTime() > time.getTime() + 50) {
+      log.info("stale file detected, auto-refreshing", { sessionID, filepath })
+      read(sessionID, filepath)
+      return { stale: true }
+    }
+    return { stale: false }
+  }
+  // altimate_change end
 }
diff --git a/packages/opencode/src/tool/edit.ts b/packages/opencode/src/tool/edit.ts
index 005e0941c..5d0c6e644 100644
--- a/packages/opencode/src/tool/edit.ts
+++ b/packages/opencode/src/tool/edit.ts
@@ -86,7 +86,9 @@ export const EditTool = Tool.define("edit", {
       const stats = Filesystem.stat(filePath)
       if (!stats) throw new Error(`File ${filePath} not found`)
       if (stats.isDirectory()) throw new Error(`Path is a directory, not a file: ${filePath}`)
-      await FileTime.assert(ctx.sessionID, filePath)
+      // altimate_change start — auto-refresh stale files instead of failing (#450)
+      const { stale } = await FileTime.assertOrRefresh(ctx.sessionID, filePath)
+      // altimate_change end
       contentOld = await Filesystem.readText(filePath)
 
       const ending = detectLineEnding(contentOld)
diff --git a/packages/opencode/src/tool/write.ts b/packages/opencode/src/tool/write.ts
index a91164f3e..f5cfc0df7 100644
--- a/packages/opencode/src/tool/write.ts
+++ b/packages/opencode/src/tool/write.ts
@@ -28,8 +28,10 @@ export const WriteTool = Tool.define("write", {
     await assertSensitiveWrite(ctx, filepath)
 
     const exists = await Filesystem.exists(filepath)
+    // altimate_change start — auto-refresh stale files instead of failing (#450)
+    if (exists) await FileTime.assertOrRefresh(ctx.sessionID, filepath)
+    // altimate_change end
     const contentOld = exists ? await Filesystem.readText(filepath) : ""
-    if (exists) await FileTime.assert(ctx.sessionID, filepath)
 
     const diff = trimDiff(createTwoFilesPatch(filepath, filepath, contentOld, params.content))
     await ctx.ask({
diff --git a/packages/opencode/test/tool/edit.test.ts b/packages/opencode/test/tool/edit.test.ts
index b0ee95ff6..bb7fabec9 100644
--- a/packages/opencode/test/tool/edit.test.ts
+++ b/packages/opencode/test/tool/edit.test.ts
@@ -226,7 +226,8 @@ describe("tool.edit", () => {
       })
     })
 
-    test("throws error when file has been modified since read", async () => {
+    // altimate_change start — edit now auto-refreshes stale files instead of throwing (#450)
+    test("succeeds when file has been modified since read by auto-refreshing", async () => {
       await using tmp = await tmpdir()
       const filepath = path.join(tmp.path, "file.txt")
       await fs.writeFile(filepath, "original content", "utf-8")
@@ -243,21 +244,23 @@ describe("tool.edit", () => {
           // Simulate external modification
           await fs.writeFile(filepath, "modified externally", "utf-8")
 
-          // Try to edit with the new content
+          // Edit should succeed — auto-refreshes the stale read timestamp
           const edit = await EditTool.init()
-          await expect(
-            edit.execute(
-              {
-                filePath: filepath,
-                oldString: "modified externally",
-                newString: "edited",
-              },
-              ctx,
-            ),
-          ).rejects.toThrow("modified since it was last read")
+          const result = await edit.execute(
+            {
+              filePath: filepath,
+              oldString: "modified externally",
+              newString: "edited",
+            },
+            ctx,
+          )
+          expect(result.output).toContain("Edit applied successfully")
+          const content = await fs.readFile(filepath, "utf-8")
+          expect(content).toBe("edited")
         },
       })
     })
+    // altimate_change end
 
     test("replaces all occurrences with replaceAll option", async () => {
       await using tmp = await tmpdir()

From 6688a43d9cf0b0690952f17d7dcb686da0a7d23d Mon Sep 17 00:00:00 2001
From: anandgupta42 <anand@altimate.ai>
Date: Tue, 24 Mar 2026 16:43:27 -0700
Subject: [PATCH 6/9] Revert "fix: [AI-450] auto-refresh stale files in `edit`
 and `write` tools instead of failing"

This reverts commit 946ec9fc7709835f72d07211414fa34a04656a98.
---
 packages/opencode/src/file/time.ts       | 32 ------------------------
 packages/opencode/src/tool/edit.ts       |  4 +--
 packages/opencode/src/tool/write.ts      |  4 +--
 packages/opencode/test/tool/edit.test.ts | 27 +++++++++-----------
 4 files changed, 14 insertions(+), 53 deletions(-)

diff --git a/packages/opencode/src/file/time.ts b/packages/opencode/src/file/time.ts
index 9b2888cf6..efb1c4376 100644
--- a/packages/opencode/src/file/time.ts
+++ b/packages/opencode/src/file/time.ts
@@ -68,36 +68,4 @@ export namespace FileTime {
       )
     }
   }
-
-  /**
-   * Check if a file has been modified since last read. Instead of throwing,
-   * returns whether the file was stale and auto-refreshes the read timestamp
-   * so the caller can re-read contents and proceed.
-   *
-   * Returns:
-   * - { stale: false } if file is up-to-date
-   * - { stale: true } if file was modified externally (timestamp refreshed)
-   *
-   * Still throws if the file was never read in this session.
-   */
-  // altimate_change start — auto-refresh stale files instead of throwing (#450)
-  export async function assertOrRefresh(
-    sessionID: string,
-    filepath: string,
-  ): Promise<{ stale: boolean }> {
-    if (Flag.OPENCODE_DISABLE_FILETIME_CHECK === true) {
-      return { stale: false }
-    }
-
-    const time = get(sessionID, filepath)
-    if (!time) throw new Error(`You must read file ${filepath} before overwriting it. Use the Read tool first`)
-    const mtime = Filesystem.stat(filepath)?.mtime
-    if (mtime && mtime.getTime() > time.getTime() + 50) {
-      log.info("stale file detected, auto-refreshing", { sessionID, filepath })
-      read(sessionID, filepath)
-      return { stale: true }
-    }
-    return { stale: false }
-  }
-  // altimate_change end
 }
diff --git a/packages/opencode/src/tool/edit.ts b/packages/opencode/src/tool/edit.ts
index 5d0c6e644..005e0941c 100644
--- a/packages/opencode/src/tool/edit.ts
+++ b/packages/opencode/src/tool/edit.ts
@@ -86,9 +86,7 @@ export const EditTool = Tool.define("edit", {
       const stats = Filesystem.stat(filePath)
       if (!stats) throw new Error(`File ${filePath} not found`)
       if (stats.isDirectory()) throw new Error(`Path is a directory, not a file: ${filePath}`)
-      // altimate_change start — auto-refresh stale files instead of failing (#450)
-      const { stale } = await FileTime.assertOrRefresh(ctx.sessionID, filePath)
-      // altimate_change end
+      await FileTime.assert(ctx.sessionID, filePath)
       contentOld = await Filesystem.readText(filePath)
 
       const ending = detectLineEnding(contentOld)
diff --git a/packages/opencode/src/tool/write.ts b/packages/opencode/src/tool/write.ts
index f5cfc0df7..a91164f3e 100644
--- a/packages/opencode/src/tool/write.ts
+++ b/packages/opencode/src/tool/write.ts
@@ -28,10 +28,8 @@ export const WriteTool = Tool.define("write", {
     await assertSensitiveWrite(ctx, filepath)
 
     const exists = await Filesystem.exists(filepath)
-    // altimate_change start — auto-refresh stale files instead of failing (#450)
-    if (exists) await FileTime.assertOrRefresh(ctx.sessionID, filepath)
-    // altimate_change end
     const contentOld = exists ? await Filesystem.readText(filepath) : ""
+    if (exists) await FileTime.assert(ctx.sessionID, filepath)
 
     const diff = trimDiff(createTwoFilesPatch(filepath, filepath, contentOld, params.content))
     await ctx.ask({
diff --git a/packages/opencode/test/tool/edit.test.ts b/packages/opencode/test/tool/edit.test.ts
index bb7fabec9..b0ee95ff6 100644
--- a/packages/opencode/test/tool/edit.test.ts
+++ b/packages/opencode/test/tool/edit.test.ts
@@ -226,8 +226,7 @@ describe("tool.edit", () => {
       })
     })
 
-    // altimate_change start — edit now auto-refreshes stale files instead of throwing (#450)
-    test("succeeds when file has been modified since read by auto-refreshing", async () => {
+    test("throws error when file has been modified since read", async () => {
       await using tmp = await tmpdir()
       const filepath = path.join(tmp.path, "file.txt")
       await fs.writeFile(filepath, "original content", "utf-8")
@@ -244,23 +243,21 @@ describe("tool.edit", () => {
           // Simulate external modification
           await fs.writeFile(filepath, "modified externally", "utf-8")
 
-          // Edit should succeed — auto-refreshes the stale read timestamp
+          // Try to edit with the new content
           const edit = await EditTool.init()
-          const result = await edit.execute(
-            {
-              filePath: filepath,
-              oldString: "modified externally",
-              newString: "edited",
-            },
-            ctx,
-          )
-          expect(result.output).toContain("Edit applied successfully")
-          const content = await fs.readFile(filepath, "utf-8")
-          expect(content).toBe("edited")
+          await expect(
+            edit.execute(
+              {
+                filePath: filepath,
+                oldString: "modified externally",
+                newString: "edited",
+              },
+              ctx,
+            ),
+          ).rejects.toThrow("modified since it was last read")
         },
       })
     })
-    // altimate_change end
 
     test("replaces all occurrences with replaceAll option", async () => {
       await using tmp = await tmpdir()

From 78d2d71ff2b0a094d0c9e62c8b4d044e390d5d7a Mon Sep 17 00:00:00 2001
From: anandgupta42 <anand@altimate.ai>
Date: Tue, 24 Mar 2026 16:46:25 -0700
Subject: [PATCH 7/9] fix: [AI-450] auto-re-read stale files in agent loop so
 model sees current content

When `edit` or `write` tools fail with "modified since it was last read", the
agent loop now auto-re-reads the file and includes its current content in the
error response. This gives the model the fresh file state so it can adjust its
next edit accordingly, preventing infinite retry loops.

This approach preserves the original safety check in `FileTime.assert()` (the
tool still throws on stale files) but recovers at the agent level by:
1. Detecting stale file errors via regex match on the error message
2. Re-reading the file and updating `FileTime` read timestamp
3. Appending fresh file content to the error so the model sees current state

Also handles "must read file before overwriting" errors the same way.

Closes #450

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 packages/opencode/src/session/processor.ts | 23 +++++++++++++++++++++-
 1 file changed, 22 insertions(+), 1 deletion(-)

diff --git a/packages/opencode/src/session/processor.ts b/packages/opencode/src/session/processor.ts
index 2cf5c663a..42f193a55 100644
--- a/packages/opencode/src/session/processor.ts
+++ b/packages/opencode/src/session/processor.ts
@@ -19,6 +19,10 @@ import type { SessionID, MessageID } from "./schema"
 // altimate_change start — import Telemetry for per-generation token tracking
 import { Telemetry } from "@/altimate/telemetry"
 // altimate_change end
+// altimate_change start — import FileTime and Filesystem for stale file recovery (#450)
+import { FileTime } from "@/file/time"
+import { Filesystem } from "@/util/filesystem"
+// altimate_change end
 
 export namespace SessionProcessor {
   const DOOM_LOOP_THRESHOLD = 3
@@ -211,12 +215,29 @@ export namespace SessionProcessor {
                 case "tool-error": {
                   const match = toolcalls[value.toolCallId]
                   if (match && match.state.status === "running") {
+                    // altimate_change start — auto-read stale files so model sees current content (#450)
+                    let errorStr = (value.error as any).toString()
+                    const staleFileMatch =
+                      errorStr.match(/File (.+) has been modified since it was last read/) ??
+                      errorStr.match(/You must read file (.+) before overwriting it/)
+                    if (staleFileMatch) {
+                      const staleFilePath = staleFileMatch[1].trim()
+                      try {
+                        const freshContent = await Filesystem.readText(staleFilePath)
+                        FileTime.read(input.sessionID, staleFilePath)
+                        errorStr += `\n\nThe file has been auto-re-read. Here is the current content:\n<file path="${staleFilePath}">\n${freshContent}\n</file>`
+                        log.info("stale file auto-re-read", { file: staleFilePath, sessionID: input.sessionID })
+                      } catch (readErr) {
+                        log.warn("failed to auto-re-read stale file", { file: staleFilePath, error: readErr })
+                      }
+                    }
+                    // altimate_change end
                     await Session.updatePart({
                       ...match,
                       state: {
                         status: "error",
                         input: value.input ?? match.state.input,
-                        error: (value.error as any).toString(),
+                        error: errorStr,
                         time: {
                           start: match.state.time.start,
                           end: Date.now(),

From b5674949d12bf284065b9d7e1de21d8555a63c8b Mon Sep 17 00:00:00 2001
From: anandgupta42 <anand@altimate.ai>
Date: Tue, 24 Mar 2026 17:01:06 -0700
Subject: [PATCH 8/9] =?UTF-8?q?fix:=20[AI-450]=20address=20code=20review?=
 =?UTF-8?q?=20=E2=80=94=20typed=20`StaleFileError`,=20bounded=20reads,=20s?=
 =?UTF-8?q?afe=20stringification?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Addresses all findings from multi-model code review:

- CRITICAL: Replace regex-based error detection with typed `StaleFileError` class
  that extends `Error` with a `filePath` property. Use `instanceof` check in
  processor instead of brittle string parsing.

- MAJOR: Add 50KB size limit before auto-reading stale files to prevent OOM and
  token explosion. Files over limit get a message to use the Read tool instead.

- MAJOR: Handle missing files (deleted between error and re-read) gracefully.

- MINOR: Use `String(value.error ?? "Unknown error")` for null-safe stringification.

- MINOR: Use markdown code fences instead of `<file>` XML tags to prevent
  prompt injection via unescaped content.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 packages/opencode/src/file/time.ts         | 16 +++++++++++-
 packages/opencode/src/session/processor.ts | 30 ++++++++++++++--------
 2 files changed, 34 insertions(+), 12 deletions(-)

diff --git a/packages/opencode/src/file/time.ts b/packages/opencode/src/file/time.ts
index efb1c4376..d55cc14cc 100644
--- a/packages/opencode/src/file/time.ts
+++ b/packages/opencode/src/file/time.ts
@@ -3,6 +3,17 @@ import { Log } from "../util/log"
 import { Flag } from "../flag/flag"
 import { Filesystem } from "../util/filesystem"
 
+// altimate_change start — typed error for stale file detection (#450)
+export class StaleFileError extends Error {
+  public readonly filePath: string
+  constructor(filePath: string, message: string) {
+    super(message)
+    this.name = "StaleFileError"
+    this.filePath = filePath
+  }
+}
+// altimate_change end
+
 export namespace FileTime {
   const log = Log.create({ service: "file.time" })
   // Per-session read times plus per-file write locks.
@@ -63,9 +74,12 @@ export namespace FileTime {
     const mtime = Filesystem.stat(filepath)?.mtime
     // Allow a 50ms tolerance for Windows NTFS timestamp fuzziness / async flushing
     if (mtime && mtime.getTime() > time.getTime() + 50) {
-      throw new Error(
+      // altimate_change start — use typed StaleFileError (#450)
+      throw new StaleFileError(
+        filepath,
         `File ${filepath} has been modified since it was last read.\nLast modification: ${mtime.toISOString()}\nLast read: ${time.toISOString()}\n\nPlease read the file again before modifying it.`,
       )
+      // altimate_change end
     }
   }
 }
diff --git a/packages/opencode/src/session/processor.ts b/packages/opencode/src/session/processor.ts
index 42f193a55..a60a5b752 100644
--- a/packages/opencode/src/session/processor.ts
+++ b/packages/opencode/src/session/processor.ts
@@ -19,7 +19,8 @@ import type { SessionID, MessageID } from "./schema"
 // altimate_change start — import Telemetry for per-generation token tracking
 import { Telemetry } from "@/altimate/telemetry"
 // altimate_change end
-// altimate_change start — import FileTime and Filesystem for stale file recovery (#450)
+// altimate_change start — import StaleFileError and Filesystem for stale file recovery (#450)
+import { StaleFileError } from "@/file/time"
 import { FileTime } from "@/file/time"
 import { Filesystem } from "@/util/filesystem"
 // altimate_change end
@@ -216,17 +217,24 @@ export namespace SessionProcessor {
                   const match = toolcalls[value.toolCallId]
                   if (match && match.state.status === "running") {
                     // altimate_change start — auto-read stale files so model sees current content (#450)
-                    let errorStr = (value.error as any).toString()
-                    const staleFileMatch =
-                      errorStr.match(/File (.+) has been modified since it was last read/) ??
-                      errorStr.match(/You must read file (.+) before overwriting it/)
-                    if (staleFileMatch) {
-                      const staleFilePath = staleFileMatch[1].trim()
+                    let errorStr = String(value.error ?? "Unknown error")
+                    if (value.error instanceof StaleFileError) {
+                      const staleFilePath = value.error.filePath
                       try {
-                        const freshContent = await Filesystem.readText(staleFilePath)
-                        FileTime.read(input.sessionID, staleFilePath)
-                        errorStr += `\n\nThe file has been auto-re-read. Here is the current content:\n<file path="${staleFilePath}">\n${freshContent}\n</file>`
-                        log.info("stale file auto-re-read", { file: staleFilePath, sessionID: input.sessionID })
+                        const stat = Filesystem.stat(staleFilePath)
+                        const MAX_AUTO_READ_BYTES = 50 * 1024
+                        if (!stat) {
+                          errorStr += "\n\nNote: The file no longer exists on disk."
+                        } else if (Number(stat.size) > MAX_AUTO_READ_BYTES) {
+                          FileTime.read(input.sessionID, staleFilePath)
+                          errorStr += `\n\nThe file has been modified (${Math.round(Number(stat.size) / 1024)}KB). It is too large to include here — please use the Read tool to view it.`
+                        } else {
+                          const freshContent = await Filesystem.readText(staleFilePath)
+                          FileTime.read(input.sessionID, staleFilePath)
+                          const fence = "````"
+                          errorStr += `\n\nThe file has been auto-re-read. Here is the current content:\n\n${fence}\n${freshContent}\n${fence}`
+                          log.info("stale file auto-re-read", { file: staleFilePath, sessionID: input.sessionID })
+                        }
                       } catch (readErr) {
                         log.warn("failed to auto-re-read stale file", { file: staleFilePath, error: readErr })
                       }

From f2d5e8d9f57cae06ffd11e4aa5df9583d0254e13 Mon Sep 17 00:00:00 2001
From: anandgupta42 <anand@altimate.ai>
Date: Tue, 24 Mar 2026 17:12:19 -0700
Subject: [PATCH 9/9] test: [AI-450] add tests for stale file recovery + append
 failure context to error

- Add comprehensive test suite for `StaleFileError` class and recovery logic:
  - `instanceof` checks (typed error vs regular Error)
  - Small file auto-re-read with content in response
  - Large file rejection with size message
  - Missing file graceful handling
  - Null/undefined error safety
  - Regex-like error text on regular Error does NOT trigger recovery
  - Backtick fencing handles files containing markdown code blocks
  - FilePath preserved for paths with spaces/special chars

- Append read failure context to error message when auto-re-read fails,
  so the model knows why re-reading didn't work

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 packages/opencode/src/session/processor.ts    |   1 +
 .../test/file/stale-file-recovery.test.ts     | 222 ++++++++++++++++++
 2 files changed, 223 insertions(+)
 create mode 100644 packages/opencode/test/file/stale-file-recovery.test.ts

diff --git a/packages/opencode/src/session/processor.ts b/packages/opencode/src/session/processor.ts
index a60a5b752..1df75e6ac 100644
--- a/packages/opencode/src/session/processor.ts
+++ b/packages/opencode/src/session/processor.ts
@@ -237,6 +237,7 @@ export namespace SessionProcessor {
                         }
                       } catch (readErr) {
                         log.warn("failed to auto-re-read stale file", { file: staleFilePath, error: readErr })
+                        errorStr += `\n\nAttempted to auto-re-read the file but failed: ${String(readErr)}`
                       }
                     }
                     // altimate_change end
diff --git a/packages/opencode/test/file/stale-file-recovery.test.ts b/packages/opencode/test/file/stale-file-recovery.test.ts
new file mode 100644
index 000000000..1a1413ead
--- /dev/null
+++ b/packages/opencode/test/file/stale-file-recovery.test.ts
@@ -0,0 +1,222 @@
+// altimate_change start — tests for stale file auto-re-read recovery (#450)
+import { describe, test, expect } from "bun:test"
+import * as fs from "fs/promises"
+import * as path from "path"
+import { StaleFileError } from "../../src/file/time"
+import { FileTime } from "../../src/file/time"
+import { Filesystem } from "../../src/util/filesystem"
+import { Instance } from "../../src/project/instance"
+
+async function tmpdir() {
+  const dir = await fs.mkdtemp(path.join(import.meta.dir, ".tmp-"))
+  return {
+    path: dir,
+    [Symbol.asyncDispose]: async () => {
+      await fs.rm(dir, { recursive: true, force: true })
+    },
+  }
+}
+
+describe("StaleFileError", () => {
+  test("extends Error", () => {
+    const err = new StaleFileError("/path/to/file.ts", "File was modified")
+    expect(err).toBeInstanceOf(Error)
+    expect(err).toBeInstanceOf(StaleFileError)
+    expect(err.name).toBe("StaleFileError")
+  })
+
+  test("carries filePath property", () => {
+    const err = new StaleFileError("/some/path/file.sql", "modified since last read")
+    expect(err.filePath).toBe("/some/path/file.sql")
+    expect(err.message).toBe("modified since last read")
+  })
+
+  test("works with instanceof check", () => {
+    const err: Error = new StaleFileError("/test", "msg")
+    if (err instanceof StaleFileError) {
+      expect(err.filePath).toBe("/test")
+    } else {
+      throw new Error("instanceof check failed")
+    }
+  })
+
+  test("preserves stack trace", () => {
+    const err = new StaleFileError("/file", "error")
+    expect(err.stack).toBeDefined()
+    expect(err.stack).toContain("StaleFileError")
+  })
+})
+
+describe("FileTime.assert throws StaleFileError", () => {
+  test("throws StaleFileError when file modified since read", async () => {
+    await using tmp = await tmpdir()
+    const filepath = path.join(tmp.path, "test.txt")
+    await fs.writeFile(filepath, "original", "utf-8")
+
+    await Instance.provide({
+      directory: tmp.path,
+      fn: async () => {
+        FileTime.read("test-session", filepath)
+
+        // Wait and modify externally
+        await new Promise((r) => setTimeout(r, 100))
+        await fs.writeFile(filepath, "modified", "utf-8")
+
+        try {
+          await FileTime.assert("test-session", filepath)
+          throw new Error("should have thrown")
+        } catch (e) {
+          expect(e).toBeInstanceOf(StaleFileError)
+          expect((e as StaleFileError).filePath).toBe(filepath)
+          expect((e as StaleFileError).message).toContain("modified since it was last read")
+        }
+      },
+    })
+  })
+
+  test("does not throw StaleFileError for unread files", async () => {
+    await using tmp = await tmpdir()
+    const filepath = path.join(tmp.path, "test.txt")
+    await fs.writeFile(filepath, "content", "utf-8")
+
+    await Instance.provide({
+      directory: tmp.path,
+      fn: async () => {
+        try {
+          await FileTime.assert("test-session-2", filepath)
+          throw new Error("should have thrown")
+        } catch (e) {
+          // This should be a regular Error, NOT StaleFileError
+          expect(e).toBeInstanceOf(Error)
+          expect(e).not.toBeInstanceOf(StaleFileError)
+          expect((e as Error).message).toContain("You must read file")
+        }
+      },
+    })
+  })
+})
+
+describe("stale file recovery logic", () => {
+  // These tests replicate the recovery logic from processor.ts in isolation,
+  // following the same pattern as processor.test.ts for telemetry tests.
+
+  const MAX_AUTO_READ_BYTES = 50 * 1024
+
+  async function simulateRecovery(opts: {
+    error: unknown
+    sessionID: string
+    filePath?: string
+    fileContent?: string
+    fileSize?: number
+    fileExists?: boolean
+  }) {
+    let errorStr = String(opts.error ?? "Unknown error")
+
+    if (opts.error instanceof StaleFileError) {
+      const staleFilePath = opts.error.filePath
+      try {
+        if (opts.fileExists === false) {
+          throw new Error("ENOENT: no such file or directory")
+        }
+        const size = opts.fileSize ?? Buffer.byteLength(opts.fileContent ?? "", "utf-8")
+        if (size > MAX_AUTO_READ_BYTES) {
+          errorStr += `\n\nThe file has been modified (${Math.round(size / 1024)}KB). It is too large to include here — please use the Read tool to view it.`
+        } else {
+          const freshContent = opts.fileContent ?? ""
+          const fence = "````"
+          errorStr += `\n\nThe file has been auto-re-read. Here is the current content:\n\n${fence}\n${freshContent}\n${fence}`
+        }
+      } catch (readErr) {
+        errorStr += `\n\nAttempted to auto-re-read the file but failed: ${String(readErr)}`
+      }
+    }
+
+    return errorStr
+  }
+
+  test("only triggers for StaleFileError, not regular errors", async () => {
+    const regularError = new Error("some other tool error")
+    const result = await simulateRecovery({
+      error: regularError,
+      sessionID: "s1",
+    })
+    expect(result).toBe("Error: some other tool error")
+    expect(result).not.toContain("auto-re-read")
+  })
+
+  test("appends file content for small files", async () => {
+    const err = new StaleFileError("/test/file.sql", "modified since last read")
+    const result = await simulateRecovery({
+      error: err,
+      sessionID: "s1",
+      fileContent: "SELECT * FROM orders;",
+    })
+    expect(result).toContain("auto-re-read")
+    expect(result).toContain("SELECT * FROM orders;")
+    expect(result).toContain("````")
+  })
+
+  test("rejects large files with size message", async () => {
+    const err = new StaleFileError("/test/big.sql", "modified")
+    const result = await simulateRecovery({
+      error: err,
+      sessionID: "s1",
+      fileSize: 100 * 1024, // 100KB
+    })
+    expect(result).toContain("too large to include here")
+    expect(result).toContain("please use the Read tool")
+    expect(result).not.toContain("auto-re-read")
+  })
+
+  test("handles missing file gracefully", async () => {
+    const err = new StaleFileError("/test/deleted.sql", "modified")
+    const result = await simulateRecovery({
+      error: err,
+      sessionID: "s1",
+      fileExists: false,
+    })
+    expect(result).toContain("Attempted to auto-re-read the file but failed")
+    expect(result).toContain("ENOENT")
+  })
+
+  test("handles null/undefined errors safely", async () => {
+    // Both null and undefined should produce "Unknown error" via ?? coalescing
+    const result1 = await simulateRecovery({ error: null, sessionID: "s1" })
+    expect(result1).toBe("Unknown error")
+
+    const result2 = await simulateRecovery({ error: undefined, sessionID: "s1" })
+    expect(result2).toBe("Unknown error")
+  })
+
+  test("does not trigger for errors with similar text", async () => {
+    // A regular Error with stale-file-like text should NOT trigger recovery
+    const trickyError = new Error("File /etc/passwd has been modified since it was last read")
+    const result = await simulateRecovery({
+      error: trickyError,
+      sessionID: "s1",
+    })
+    expect(result).not.toContain("auto-re-read")
+    expect(result).not.toContain("too large")
+  })
+
+  test("file content with backticks does not break fencing", async () => {
+    const err = new StaleFileError("/test/file.md", "modified")
+    const content = "```python\nprint('hello')\n```"
+    const result = await simulateRecovery({
+      error: err,
+      sessionID: "s1",
+      fileContent: content,
+    })
+    // Uses ```` (4 backticks) so inner ``` (3 backticks) don't break it
+    expect(result).toContain("````")
+    expect(result).toContain(content)
+  })
+
+  test("filePath is extracted from StaleFileError, not parsed from message", async () => {
+    // Path with spaces and special chars
+    const weirdPath = "/Users/test user/my project/models/stg orders.sql"
+    const err = new StaleFileError(weirdPath, "some error message without the path")
+    expect(err.filePath).toBe(weirdPath)
+  })
+})
+// altimate_change end