From 94507a118669dcf2b73b6bbea04ad96f92ef5a54 Mon Sep 17 00:00:00 2001
From: Raghav Chari <raghavchari2021@gmail.com>
Date: Mon, 15 Jun 2026 11:58:44 -0400
Subject: [PATCH 1/9] feat(extension): rewrite AGENTS.md for D9/D10 script
 authoring; relocate to package root

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 AGENTS.md                                 | 71 -----------------------
 packages/extension/AGENTS.md              | 56 ++++++++++++++++++
 packages/extension/test/agents_md.test.ts | 23 ++++++++
 3 files changed, 79 insertions(+), 71 deletions(-)
 delete mode 100644 AGENTS.md
 create mode 100644 packages/extension/AGENTS.md
 create mode 100644 packages/extension/test/agents_md.test.ts

diff --git a/AGENTS.md b/AGENTS.md
deleted file mode 100644
index 1a1bc40a4..000000000
--- a/AGENTS.md
+++ /dev/null
@@ -1,71 +0,0 @@
-# Amicode project context
-
-This is the Amicode VS Code extension's per-session opencode project. You're
-running here so a developer can iterate on quantum-optimal-control pulses
-without leaving their editor.
-
-## Your tools (use bash, not MCP)
-
-There is **no MCP server** in this project. The single domain-specific tool
-is a CLI binary you invoke via the `bash` tool:
-
-### `amico-run`
-
-Solves for an optimal control pulse using Piccolo / Piccolissimo (Julia).
-Writes per-iteration PNGs + a final result.toml to disk; the VS Code Run
-Inspector panel auto-refreshes as the solve runs.
-
-**Invoke via:**
-
-```bash
-amico-run --system <qubit|transmon> \
-          --gate <X|Y|Z|H|S|T|CNOT|CZ|SWAP|iSWAP> \
-          --pulse <zero-order|linear-spline> \
-          [--T-ns <float>] [--omega-cap <float>] [--max-iter <int>]
-```
-
-`amico-run --help` prints full usage.
-
-**Arg guidance** (pick sensible defaults if the user doesn't specify):
-
-- `--system`: `qubit` for textbook Pauli (X/Y/Z drift); `transmon` for the
-  physical 4-level Duffing model. Default `transmon` if the user mentions
-  "qubit hardware," "transmon," "leakage," or any GHz frequency. Default
-  `qubit` if they say "toy example" or "Pauli."
-- `--gate`: literally what they asked for. `X`/`Y`/`Z`/`H`/`S`/`T` are 1q;
-  `CNOT`/`CZ`/`SWAP`/`iSWAP` are 2q. (`CNOT` and `CX` are aliases.)
-- `--pulse`: `zero-order` (piecewise-constant) is the safe default and runs
-  faster. `linear-spline` for smoother controls when the user asks about
-  bandwidth, smoothness, or DRAG-style shaping.
-- `--T-ns`: default 10 ns for `qubit`, 24 ns for `transmon` 1q gates,
-  ~150-300 ns for 2q gates. Don't pass if the user didn't specify.
-- `--omega-cap`: transmon-only; default 0.05 (50 MHz). Above 0.15 GHz the
-  RWA / weak-anharmonic approximation degrades.
-- `--max-iter`: leave off unless the user explicitly limits or extends.
-
-**Hazard checks** (call these out to the user *before* invoking the tool):
-
-- transmon + 1q + T < 20 ns → likely F ≲ 0.95; suggest T ~30-40 ns or higher ω cap.
-- transmon + 2q + T < 150 ns → likely won't converge; suggest 150-300 ns.
-- transmon + omega_cap > 0.15 GHz → expect leakage to |2⟩; rollout vs solver F will diverge.
-
-**Output**:
-
-Each run lands in `/tmp/amicode-runs/<runId>/` and the symlink
-`/tmp/amicode-runs/latest` points at it. The user sees the live iter PNGs
-in the VS Code Run Inspector panel — you don't have to display them.
-
-When `amico-run` finishes, it prints a one-line `DONE` summary with the
-fidelity. Quote that back to the user. If F ≥ 0.99, the extension will
-automatically prompt them to promote the pulse to the catalog — you don't
-need to ask.
-
-## Style
-
-- Be terse. The user is a quantum-control researcher; don't explain quantum
-  mechanics unless asked.
-- Run `amico-run --help` first if you're unsure of an arg.
-- If a run fails, read `/tmp/amicode-runs/latest/run.log` for the actual
-  julia traceback before guessing.
-- Don't suggest installing new Julia packages. The dev environment is
-  pinned at `/tmp/amicode-spike-julia` and the user maintains it.
diff --git a/packages/extension/AGENTS.md b/packages/extension/AGENTS.md
new file mode 100644
index 000000000..e2584f13c
--- /dev/null
+++ b/packages/extension/AGENTS.md
@@ -0,0 +1,56 @@
+# Amicode project context
+
+You help a quantum-control researcher synthesize optimal-control pulses with
+Piccolo (Julia) without leaving VS Code. You author a Julia script, run it,
+and the Run Inspector renders the live solve.
+
+## Workflow (this is the whole job)
+
+1. Read the bundled template `solve_template.jl` in this project dir.
+2. Copy it to a working file (e.g. `solve.jl`) and fill in the `# FILL IN`
+   parameter block from the user's request: transmon frequency `ω` (GHz),
+   anharmonicity `δ` (GHz), `levels`, the target gate, gate time `T` (ns),
+   timesteps `N`, `max_iter`. **Parameters live in the script — never in this
+   file.** If the user gives a `lab.toml` path, read it in the script.
+3. Run it via the `bash` tool:  `amico-run --project <JULIA_PROJECT> solve.jl`
+   (use the project path provided below). `amico-run` takes only a script path
+   and runner flags — it parses **no** physics options; all the physics lives
+   in the script you wrote.
+4. When it finishes, quote the final `DONE fidelity=…` line. If F ≥ 0.99 the
+   extension prompts promotion automatically — don't ask.
+
+There is **no MCP server**. The only tool is `amico-run` via bash.
+`amico-run --help` prints usage.
+
+## The run-dir contract your script MUST emit
+
+`amico-run` writes `manifest.toml` (first) and `FINISHED` (last) itself. Your
+script, running with cwd = the run dir, must emit:
+
+- `AMICODE_ITER iter=<n> f=<obj> inf_pr=<…> inf_du=<…>` to stdout, flushed,
+  once per Ipopt iteration (drives the live stats row).
+- `iter_<N>.png` every few iterations (the live plot the Inspector shows).
+- `result.toml`, written **atomically** (write `result.toml.tmp`, then `mv`),
+  with at least `fidelity` (float) and `iterations` (int).
+- `pulse.jld2` (the solved pulse) via `JLD2.save`.
+- a final `DONE fidelity=<…>` line.
+
+The template already does all of this — you only fill in numbers.
+
+## Warm-start idiom
+
+To seed from a previous solve: `traj = load_traj("path/to/pulse.jld2")` and
+pass it as the initial guess to the problem constructor. `load_traj` is the
+correct loader in this Piccolo.
+
+## Julia project
+
+<!-- AMICO_JULIA_PROJECT --> The Julia project to pass as `--project` is:
+**{{JULIA_PROJECT}}**. Always pass it. If it reads `UNSET`, omit `--project`
+and tell the user `amicode.juliaProject` is not configured.
+
+## Style
+
+Terse — the user is a quantum-control researcher. On failure, read the run's
+`run.log` for the Julia traceback before guessing. Don't suggest installing
+Julia packages; the environment is provisioned.
diff --git a/packages/extension/test/agents_md.test.ts b/packages/extension/test/agents_md.test.ts
new file mode 100644
index 000000000..56fa288e7
--- /dev/null
+++ b/packages/extension/test/agents_md.test.ts
@@ -0,0 +1,23 @@
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const AGENTS = readFileSync(join(__dirname, '..', 'AGENTS.md'), 'utf8')
+
+describe('AGENTS.md teaches the D9/D10 script-authoring workflow', () => {
+  it('points at the bundled template and the amico-run <script> invocation', () => {
+    expect(AGENTS).toMatch(/solve_template\.jl/)
+    expect(AGENTS).toMatch(/amico-run .*solve\.jl/)   // the actual invocation it teaches
+  })
+  it('documents the run-dir contract the script must emit', () => {
+    expect(AGENTS).toMatch(/AMICODE_ITER/)
+    expect(AGENTS).toMatch(/iter_.*\.png/)
+    expect(AGENTS).toMatch(/result\.toml/)
+    expect(AGENTS).toMatch(/load_traj/)            // corrected warm-start idiom (not load_pulse)
+  })
+  it('does NOT teach the deleted pre-D9 flag CLI', () => {
+    expect(AGENTS).not.toMatch(/--gate\b/)
+    expect(AGENTS).not.toMatch(/--system\b/)
+    expect(AGENTS).not.toMatch(/load_pulse/)
+  })
+})

From 6821e19deb497865abb9bc842ecf1a6470c307e1 Mon Sep 17 00:00:00 2001
From: Raghav Chari <raghavchari2021@gmail.com>
Date: Mon, 15 Jun 2026 14:09:47 -0400
Subject: [PATCH 2/9] feat(extension): vetted transmon solve_template.jl +
 per-iter control plot; slow-tier AC vet (F=0.99999998 through amico-run)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 packages/extension/package.json               | 59 ++++++++----
 .../extension/templates/solve_template.jl     | 89 +++++++++++++++++++
 packages/extension/test/slow/template.test.ts | 26 ++++++
 pnpm-lock.yaml                                |  3 +
 4 files changed, 162 insertions(+), 15 deletions(-)
 create mode 100644 packages/extension/templates/solve_template.jl
 create mode 100644 packages/extension/test/slow/template.test.ts

diff --git a/packages/extension/package.json b/packages/extension/package.json
index 790645810..51fb92d67 100644
--- a/packages/extension/package.json
+++ b/packages/extension/package.json
@@ -9,7 +9,9 @@
   "engines": {
     "vscode": "^1.95.0"
   },
-  "categories": ["Other"],
+  "categories": [
+    "Other"
+  ],
   "activationEvents": [
     "onCommand:amicode.openChat",
     "onCommand:amicode.openInspector",
@@ -37,18 +39,43 @@
     },
     "views": {
       "amicode": [
-        { "id": "amicode.vault",    "name": "Vault",    "type": "tree" },
-        { "id": "amicode.catalog",  "name": "Catalog",  "type": "tree" },
-        { "id": "amicode.armonia",  "name": "Armonia",  "type": "tree" }
+        {
+          "id": "amicode.vault",
+          "name": "Vault",
+          "type": "tree"
+        },
+        {
+          "id": "amicode.catalog",
+          "name": "Catalog",
+          "type": "tree"
+        },
+        {
+          "id": "amicode.armonia",
+          "name": "Armonia",
+          "type": "tree"
+        }
       ],
       "amicode-panel": [
-        { "id": "amicode.runInspector", "name": "Run Inspector", "type": "webview" }
+        {
+          "id": "amicode.runInspector",
+          "name": "Run Inspector",
+          "type": "webview"
+        }
       ]
     },
     "commands": [
-      { "command": "amicode.openChat",      "title": "Amicode: Open Chat" },
-      { "command": "amicode.openInspector", "title": "Amicode: Open Run Inspector" },
-      { "command": "amicode.restartServer", "title": "Amicode: Restart opencode server" }
+      {
+        "command": "amicode.openChat",
+        "title": "Amicode: Open Chat"
+      },
+      {
+        "command": "amicode.openInspector",
+        "title": "Amicode: Open Run Inspector"
+      },
+      {
+        "command": "amicode.restartServer",
+        "title": "Amicode: Restart opencode server"
+      }
     ],
     "configuration": {
       "title": "Amicode",
@@ -72,19 +99,21 @@
     }
   },
   "scripts": {
-    "build":     "node esbuild.config.mjs",
-    "watch":     "node esbuild.config.mjs --watch",
+    "build": "node esbuild.config.mjs",
+    "watch": "node esbuild.config.mjs --watch",
     "typecheck": "tsc --noEmit",
-    "test":      "vitest run --passWithNoTests",
+    "test": "vitest run --passWithNoTests --exclude '**/slow/**'",
+    "test:slow": "vitest run test/slow",
     "test:smoke": "node test/boot_smoke.mjs",
     "fetch:opencode": "node scripts/fetch_opencode.mjs"
   },
   "devDependencies": {
     "@amicode/amico-run": "workspace:*",
-    "@types/node":   "^22.0.0",
+    "@types/node": "^22.0.0",
     "@types/vscode": "^1.95.0",
-    "esbuild":       "^0.24.0",
-    "typescript":    "^5.6.0",
-    "vitest":        "^2.1.0"
+    "esbuild": "^0.24.0",
+    "smol-toml": "^1.3.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
   }
 }
diff --git a/packages/extension/templates/solve_template.jl b/packages/extension/templates/solve_template.jl
new file mode 100644
index 000000000..87d97f738
--- /dev/null
+++ b/packages/extension/templates/solve_template.jl
@@ -0,0 +1,89 @@
+#!/usr/bin/env julia
+# Amicode solve template — fill in the `# FILL IN` block, then:
+#   amico-run --project <julia-project> solve.jl
+# Emits the run-dir contract (AMICODE_ITER, iter_<N>.png, result.toml, pulse.jld2, DONE).
+# Vetted against Piccolo 0.11 (QuantumCollocation/DirectTrajOpt 0.8): a single-qubit
+# X gate on a 3-level transmon converges to subspace fidelity ~1.0 in ~1 min.
+using Piccolo
+using CairoMakie
+using JLD2
+using TOML
+using Printf
+
+# ── FILL IN ──────────────────────────────────────────────────────────────
+δ          = 0.2        # anharmonicity (GHz, positive convention)
+levels     = 3          # transmon levels modeled (3 = qubit + 1 leakage; bump to 4–5 for more leakage realism)
+gate       = GATES[:X]
+T          = 10.0       # gate time (ns)
+N          = 50         # timesteps
+drive_max  = 0.2        # per-quadrature drive bound (GHz)
+max_iter   = 60
+# ─────────────────────────────────────────────────────────────────────────
+
+sys = TransmonSystem(; δ = δ, levels = levels, drive_bounds = fill(drive_max, 2))
+op  = size(gate, 1) == sys.levels ? gate : EmbeddedOperator(gate, sys)
+
+times   = collect(range(0.0, T, length = N))
+initial = 0.1 * randn(sys.n_drives, N)
+qtraj = UnitaryTrajectory(sys, ZeroOrderPulse(initial, times), op)
+qcp = SmoothPulseProblem(qtraj, N;
+    piccolo_options = PiccoloOptions(timesteps_all_equal = true),
+    Q = 100.0, R = 1e-2)
+dto_prob = hasproperty(qcp, :prob) ? qcp.prob : qcp
+
+# Per-iter callback machinery lives in DirectTrajOpt's internal IpoptSolverExt
+# (not re-exported); reach it through the solve! method table (β.1 pattern).
+const Callbacks = first(filter(
+    m -> string(m.module) == "DirectTrajOpt.IpoptSolverExt",
+    collect(methods(solve!)))).module.Callbacks
+
+const PLOT_EVERY = 10
+iters = Ref(0)
+cb_update = Callbacks.callback_update_trajectory_factory(dto_prob)
+function cb_log(optimizer, st; kwargs...)
+    k = Int(st.iter_count); iters[] = k
+    @printf("AMICODE_ITER iter=%d f=%.6e inf_pr=%.3e inf_du=%.3e\n", k, st.obj_value, st.inf_pr, st.inf_du)
+    flush(stdout)
+    if k % PLOT_EVERY == 0
+        save_control_plot(k)
+    end
+    return true
+end
+
+# Cheap per-iter plot: control amplitudes vs time (no rollout — keeps the
+# live solve fast). `cb_update` has refreshed dto_prob.trajectory by now.
+function save_control_plot(k::Int)
+    try
+        u = dto_prob.trajectory[:u]            # (n_drives × N) control amplitudes
+        fig = Figure(size = (640, 360))
+        ax = Axis(fig[1, 1], xlabel = "timestep", ylabel = "drive amplitude (GHz)",
+                  title = @sprintf("iter %d", k))
+        for d in 1:size(u, 1)
+            lines!(ax, 1:size(u, 2), vec(u[d, :]), label = "u$(d)")
+        end
+        axislegend(ax; position = :rt)
+        CairoMakie.save(@sprintf("iter_%04d.png", k), fig)
+    catch e
+        @warn "iter plot failed" exception = e   # never let plotting kill the solve
+    end
+end
+
+t0 = time()
+solve!(qcp; max_iter = max_iter, print_level = 1,
+       callback = Callbacks.callback_factory(cb_update, cb_log))
+wall = time() - t0
+
+# Fidelity over the COMPUTATIONAL subspace (full-space fidelity is misleading
+# for an embedded gate — it includes leakage levels + global phase).
+Ufin = iso_vec_to_operator(get_trajectory(qcp)[:Ũ⃗][:, end])
+fid  = unitary_fidelity(Ufin, op.operator; subspace = op.subspace)
+
+# ensure at least one PNG even if the solve stopped before PLOT_EVERY
+isfile(@sprintf("iter_%04d.png", iters[])) || save_control_plot(iters[])
+
+JLD2.save("pulse.jld2", "trajectory", dto_prob.trajectory)
+open("result.toml.tmp", "w") do io
+    TOML.print(io, Dict("fidelity" => fid, "iterations" => iters[], "wall_seconds" => wall))
+end
+mv("result.toml.tmp", "result.toml"; force = true)
+println("DONE fidelity=$(fid)"); flush(stdout)
diff --git a/packages/extension/test/slow/template.test.ts b/packages/extension/test/slow/template.test.ts
new file mode 100644
index 000000000..484421e9c
--- /dev/null
+++ b/packages/extension/test/slow/template.test.ts
@@ -0,0 +1,26 @@
+import { describe, it, expect } from 'vitest'
+import { execFileSync } from 'node:child_process'
+import { mkdtempSync, readdirSync, existsSync, readFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { parse } from 'smol-toml'
+
+const PROJECT = process.env.AMICO_TEST_JULIA_PROJECT
+const RUN = join(__dirname, '..', '..', '..', 'amico-run', 'dist', 'amico-run.js')  // β.1 bundle
+const TEMPLATE = join(__dirname, '..', '..', 'templates', 'solve_template.jl')
+
+describe.skipIf(!PROJECT)('slow: solve_template.jl through amico-run (β.3 AC)', () => {
+  it('unmodified template → FINISHED{completed} + pulse + iter PNG + AMICODE_ITER', () => {
+    const root = mkdtempSync(join(tmpdir(), 'tmpl-vet-'))
+    const stdout = execFileSync('node', [RUN, TEMPLATE, '--runs-root', join(root, 'runs'),
+      '--project', PROJECT!, '--lab', 'devlab'], { encoding: 'utf8', timeout: 600_000 })
+    expect(stdout).toMatch(/AMICODE_ITER iter=/)
+    expect(stdout).toMatch(/AMICODE_FINISHED status=completed exitCode=0 runDir=/)   // mirror β.1
+    const runDir = stdout.match(/AMICODE_FINISHED .*runDir=(.+)/)![1].trim()          // anchored capture
+    expect(parse(readFileSync(join(runDir, 'FINISHED'), 'utf8')).status).toBe('completed')
+    expect(existsSync(join(runDir, 'pulse.jld2'))).toBe(true)
+    expect(readdirSync(runDir).some(f => /^iter_\d+\.png$/.test(f))).toBe(true)
+    const r = parse(readFileSync(join(runDir, 'result.toml'), 'utf8')) as Record<string, unknown>
+    expect(r.fidelity as number).toBeGreaterThan(0.99)
+  }, 600_000)
+})
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 806c9a642..a7435c6cf 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -40,6 +40,9 @@ importers:
       esbuild:
         specifier: ^0.24.0
         version: 0.24.2
+      smol-toml:
+        specifier: ^1.3.0
+        version: 1.6.1
       typescript:
         specifier: ^5.6.0
         version: 5.9.3

From 87861906d983dbb055e4e423cf6064d5e3b2781e Mon Sep 17 00:00:00 2001
From: Raghav Chari <raghavchari2021@gmail.com>
Date: Mon, 15 Jun 2026 14:11:23 -0400
Subject: [PATCH 3/9] feat(extension): deliver template + project-substituted
 AGENTS.md into opencode session

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 packages/extension/src/extension.ts           |  8 ++-
 packages/extension/src/opencode_config.ts     | 58 +++++++++----------
 .../extension/test/opencode_config.test.ts    | 34 +++++++++++
 3 files changed, 66 insertions(+), 34 deletions(-)
 create mode 100644 packages/extension/test/opencode_config.test.ts

diff --git a/packages/extension/src/extension.ts b/packages/extension/src/extension.ts
index 25e7ce46c..fdeab6246 100644
--- a/packages/extension/src/extension.ts
+++ b/packages/extension/src/extension.ts
@@ -49,10 +49,14 @@ export async function activate(ctx: vscode.ExtensionContext): Promise<void> {
 
   // 3. opencode project bootstrap
   const binDir = path.resolve(ctx.extensionPath, "bin");
-  const agentsSrc = path.resolve(ctx.extensionPath, "AGENTS.md");
-  const opencodeProject = prepareOpencodeProject({ binDir, agentsSrc });
+  const opencodeProject = prepareOpencodeProject({
+    agentsSrc: path.resolve(ctx.extensionPath, "AGENTS.md"),
+    templateSrc: path.resolve(ctx.extensionPath, "templates", "solve_template.jl"),
+    juliaProject: vscode.workspace.getConfiguration("amicode").get<string>("juliaProject", ""),
+  });
   opencodeChannel.appendLine(`[boot] opencode project dir: ${opencodeProject.projectDir}`);
   opencodeChannel.appendLine(`[boot] AGENTS.md: ${opencodeProject.agentsPath}`);
+  opencodeChannel.appendLine(`[boot] template: ${opencodeProject.templatePath}`);
 
   // 4. Spawn opencode — the VENDORED binary by default (spec §4; S35, kills
   // Assumption 4). Config override is a dev-only escape hatch. On a missing
diff --git a/packages/extension/src/opencode_config.ts b/packages/extension/src/opencode_config.ts
index 715ce1241..40b08f90c 100644
--- a/packages/extension/src/opencode_config.ts
+++ b/packages/extension/src/opencode_config.ts
@@ -5,56 +5,50 @@ import * as os from "node:os";
 // ============================================================================
 // Prepare a per-session opencode project directory.
 //
-// Architecture: opencode invokes amico-run via its built-in `bash` tool — no
-// MCP, no callback HTTP. We just need to make sure opencode (a) has context
-// about how to use amico-run, and (b) finds it on PATH.
-//
-// Layout written:
-//   <projectDir>/AGENTS.md                  ← LLM context (auto-loaded)
-//   <projectDir>/.opencode/opencode.json    ← optional config tweaks
-//
-// PATH augmentation happens at spawn time (ServerManager env), not here.
+// opencode invokes amico-run via its built-in `bash` tool — no MCP, no
+// callback HTTP. We deliver into the session: (a) AGENTS.md (auto-loaded LLM
+// context, with the Julia project path substituted in), and (b) the vetted
+// solve_template.jl the agent copies + fills in. PATH augmentation (so
+// `amico-run` resolves) happens at spawn time in extension.ts.
 // ============================================================================
 
 export interface OpencodeConfigOptions {
-  /** Absolute path to amicode-v2/bin/ — added to PATH so `amico-run` resolves. */
-  binDir: string;
-  /** Absolute path to amicode-v2/AGENTS.md to copy into the project dir. */
+  /** Absolute path to packages/extension/AGENTS.md to copy into the project dir. */
   agentsSrc: string;
+  /** Absolute path to the vetted solve_template.jl to copy into the project dir. */
+  templateSrc: string;
+  /** Julia project (--project) the agent should use; substituted into AGENTS.md.
+   *  undefined → "UNSET" (AGENTS.md tells the agent to omit --project). */
+  juliaProject: string | undefined;
 }
 
 export interface OpencodeProject {
   projectDir: string;
   agentsPath: string;
+  templatePath: string;
 }
 
 export function prepareOpencodeProject(opts: OpencodeConfigOptions): OpencodeProject {
   const projectDir = fs.mkdtempSync(path.join(os.tmpdir(), "amicode-v2-"));
-  const opencodeDir = path.join(projectDir, ".opencode");
-  fs.mkdirSync(opencodeDir, { recursive: true });
+  fs.mkdirSync(path.join(projectDir, ".opencode"), { recursive: true });
 
-  // Copy AGENTS.md into the project dir. opencode auto-loads it as system
-  // context for any session it spawns from this dir.
+  // AGENTS.md: read → substitute {{JULIA_PROJECT}} → write (auto-loaded by opencode).
   const agentsPath = path.join(projectDir, "AGENTS.md");
-  if (fs.existsSync(opts.agentsSrc)) {
-    fs.copyFileSync(opts.agentsSrc, agentsPath);
-  } else {
-    // Fallback minimal stub so opencode has *something* to anchor on.
-    fs.writeFileSync(
-      agentsPath,
-      "# Amicode\nInvoke `amico-run --help` via bash to see the solver CLI.\n",
-      "utf8",
-    );
-  }
-
-  // Empty/minimal opencode config — we no longer need MCP or plugin entries.
-  // Leaving the file behind so opencode treats this dir as its project root.
-  const configPath = path.join(opencodeDir, "opencode.json");
+  const raw = fs.existsSync(opts.agentsSrc)
+    ? fs.readFileSync(opts.agentsSrc, "utf8")
+    : "# Amicode\nRead solve_template.jl, fill params, run `amico-run <script>`.\n";
+  fs.writeFileSync(agentsPath, raw.replaceAll("{{JULIA_PROJECT}}", opts.juliaProject ?? "UNSET"), "utf8");
+
+  // The vetted template the agent copies and fills in.
+  const templatePath = path.join(projectDir, "solve_template.jl");
+  if (fs.existsSync(opts.templateSrc)) fs.copyFileSync(opts.templateSrc, templatePath);
+
+  // Minimal opencode config so it treats this dir as a project root.
   fs.writeFileSync(
-    configPath,
+    path.join(projectDir, ".opencode", "opencode.json"),
     JSON.stringify({ $schema: "https://opencode.ai/config.json" }, null, 2),
     "utf8",
   );
 
-  return { projectDir, agentsPath };
+  return { projectDir, agentsPath, templatePath };
 }
diff --git a/packages/extension/test/opencode_config.test.ts b/packages/extension/test/opencode_config.test.ts
new file mode 100644
index 000000000..82d414ddd
--- /dev/null
+++ b/packages/extension/test/opencode_config.test.ts
@@ -0,0 +1,34 @@
+import { describe, it, expect } from 'vitest'
+import { existsSync, mkdtempSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { prepareOpencodeProject } from '../src/opencode_config'
+
+function fakeExtRoot(): string {
+  const root = mkdtempSync(join(tmpdir(), 'extroot-'))
+  writeFileSync(join(root, 'AGENTS.md'), '# A\nproject: {{JULIA_PROJECT}}\n')
+  mkdirSync(join(root, 'templates'))
+  writeFileSync(join(root, 'templates', 'solve_template.jl'), '# template\n')
+  return root
+}
+
+describe('prepareOpencodeProject', () => {
+  it('copies AGENTS.md + template into the session and substitutes the julia project', () => {
+    const ext = fakeExtRoot()
+    const p = prepareOpencodeProject({
+      agentsSrc: join(ext, 'AGENTS.md'),
+      templateSrc: join(ext, 'templates', 'solve_template.jl'),
+      juliaProject: '/opt/piccolo',
+    })
+    expect(existsSync(join(p.projectDir, 'solve_template.jl'))).toBe(true)
+    const agents = readFileSync(p.agentsPath, 'utf8')
+    expect(agents).toContain('/opt/piccolo')
+    expect(agents).not.toContain('{{JULIA_PROJECT}}')
+  })
+  it('substitutes UNSET when no project configured', () => {
+    const ext = fakeExtRoot()
+    const p = prepareOpencodeProject({ agentsSrc: join(ext, 'AGENTS.md'),
+      templateSrc: join(ext, 'templates', 'solve_template.jl'), juliaProject: undefined })
+    expect(readFileSync(p.agentsPath, 'utf8')).toContain('UNSET')
+  })
+})

From 15a2c2fd91157b4749a73b92e45eea22ec285f9f Mon Sep 17 00:00:00 2001
From: Raghav Chari <raghavchari2021@gmail.com>
Date: Mon, 15 Jun 2026 14:14:40 -0400
Subject: [PATCH 4/9] feat(extension): stage amico-run onto opencode PATH
 (esbuild); drop dead spike_solve wiring; opencode_paths helpers

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .gitignore                                    |  1 +
 packages/extension/.vscodeignore              |  1 +
 packages/extension/esbuild.config.mjs         | 16 +++++++
 packages/extension/package.json               |  8 ++--
 packages/extension/src/extension.ts           | 31 +++++--------
 packages/extension/src/opencode_paths.ts      | 29 +++++++++++++
 .../extension/test/opencode_paths.test.ts     | 43 +++++++++++++++++++
 7 files changed, 104 insertions(+), 25 deletions(-)
 create mode 100644 packages/extension/src/opencode_paths.ts
 create mode 100644 packages/extension/test/opencode_paths.test.ts

diff --git a/.gitignore b/.gitignore
index 4992a94e4..5b28ba899 100644
--- a/.gitignore
+++ b/.gitignore
@@ -4,3 +4,4 @@ dist/
 .vscode-test/
 *.log
 packages/extension/vendor/
+packages/extension/bin/
diff --git a/packages/extension/.vscodeignore b/packages/extension/.vscodeignore
index 5d5d6c657..0e0bcaffb 100644
--- a/packages/extension/.vscodeignore
+++ b/packages/extension/.vscodeignore
@@ -9,3 +9,4 @@ node_modules/**
 esbuild.config.mjs
 tsconfig.json
 **/*.map
+!bin/**
diff --git a/packages/extension/esbuild.config.mjs b/packages/extension/esbuild.config.mjs
index 949bec366..6b04467ef 100644
--- a/packages/extension/esbuild.config.mjs
+++ b/packages/extension/esbuild.config.mjs
@@ -1,7 +1,23 @@
 import { build, context } from "esbuild";
+import { cpSync, mkdirSync, existsSync, chmodSync } from "node:fs";
 
 const watch = process.argv.includes("--watch");
 
+// Stage amico-run so `bin/launcher/amico-run` finds `bin/dist/amico-run.js`
+// (the launcher execs node "$DIR/../dist/amico-run.js"). Package-time artifact;
+// the dev Extension Host uses the sibling-launcher fallback (resolveAmicoRunBinDir).
+// Runs in both build and --watch (CWD = the package dir under `pnpm run`).
+const arRoot = "../amico-run";
+if (existsSync(`${arRoot}/dist/amico-run.js`)) {
+  mkdirSync("bin/launcher", { recursive: true });
+  mkdirSync("bin/dist", { recursive: true });
+  cpSync(`${arRoot}/launcher/amico-run`, "bin/launcher/amico-run", { dereference: true });
+  cpSync(`${arRoot}/dist/amico-run.js`, "bin/dist/amico-run.js", { dereference: true });
+  chmodSync("bin/launcher/amico-run", 0o755); // guarantee +x survives pack/unpack
+} else {
+  console.warn("[esbuild] amico-run/dist not built — run `pnpm --filter @amicode/amico-run build` before packaging");
+}
+
 const targets = [
   // extension host entry point
   {
diff --git a/packages/extension/package.json b/packages/extension/package.json
index 51fb92d67..b94036320 100644
--- a/packages/extension/package.json
+++ b/packages/extension/package.json
@@ -87,13 +87,13 @@
         },
         "amicode.juliaProject": {
           "type": "string",
-          "default": "/tmp/amicode-spike-julia",
-          "description": "Julia project root (--project=...) the run_julia tool will use."
+          "default": "",
+          "description": "Julia project (--project) the agent passes to amico-run. Empty = agent omits --project."
         },
-        "amicode.juliaScript": {
+        "amicode.runsRoot": {
           "type": "string",
           "default": "",
-          "description": "Absolute path to spike_solve.jl. If empty, looks up via the extensionPath/../amicode/julia/spike_solve.jl convention."
+          "description": "Runs root the inspector watches. Empty = ~/.amico/runs/default (must match where amico-run writes)."
         }
       }
     }
diff --git a/packages/extension/src/extension.ts b/packages/extension/src/extension.ts
index fdeab6246..972c3e583 100644
--- a/packages/extension/src/extension.ts
+++ b/packages/extension/src/extension.ts
@@ -8,6 +8,7 @@ import { registerRunInspector } from "./run_inspector";
 import { registerTrees } from "./trees";
 import { StatusBarManager } from "./status_bar";
 import { prepareOpencodeProject } from "./opencode_config";
+import { resolveAmicoRunBinDir } from "./opencode_paths";
 import { OpencodeEventClient } from "./sse_client";
 import { RunsRootWatcher } from "./file_watcher";
 
@@ -48,7 +49,7 @@ export async function activate(ctx: vscode.ExtensionContext): Promise<void> {
   ctx.subscriptions.push(watcher);
 
   // 3. opencode project bootstrap
-  const binDir = path.resolve(ctx.extensionPath, "bin");
+  const amicoRunBinDir = resolveAmicoRunBinDir(ctx.extensionPath);
   const opencodeProject = prepareOpencodeProject({
     agentsSrc: path.resolve(ctx.extensionPath, "AGENTS.md"),
     templateSrc: path.resolve(ctx.extensionPath, "templates", "solve_template.jl"),
@@ -82,16 +83,17 @@ export async function activate(ctx: vscode.ExtensionContext): Promise<void> {
   }
 
   if (binary !== undefined) {
-    const juliaScript = resolveJuliaScript(ctx);
-    const juliaProject = resolveJuliaProject();
+    // amico-run is argv-only (β.1) — no AMICO_* env propagation (S37). The agent
+    // gets the Julia project from AGENTS.md (substituted at session-copy time)
+    // and passes it as `--project`. PATH just needs to resolve the launcher.
+    if (amicoRunBinDir === undefined) {
+      opencodeChannel.appendLine(`[boot] WARNING: amico-run launcher not found — chat can author but solves won't run (build amico-run or check the VSIX)`);
+    }
     serverManager = new ServerManager({
       binary,
       cwd: opencodeProject.projectDir,
       env: {
-        PATH: `${binDir}:${process.env.PATH ?? ""}`,
-        AMICO_JULIA_SCRIPT:  juliaScript,
-        AMICO_JULIA_PROJECT: juliaProject,
-        AMICO_RUNS_ROOT:     runsRoot,
+        PATH: `${amicoRunBinDir ? amicoRunBinDir + ":" : ""}${process.env.PATH ?? ""}`,
       },
       channel: opencodeChannel,
     });
@@ -138,7 +140,7 @@ export async function activate(ctx: vscode.ExtensionContext): Promise<void> {
     }),
   );
 
-  opencodeChannel.appendLine(`[boot] activated; runsRoot=${runsRoot}; binDir=${binDir}`);
+  opencodeChannel.appendLine(`[boot] activated; runsRoot=${runsRoot}; amicoRunBinDir=${amicoRunBinDir ?? "(none)"}`);
 }
 
 export function deactivate(): void {
@@ -148,16 +150,3 @@ export function deactivate(): void {
   statusBar?.dispose();
 }
 
-// ---------------------------------------------------------------------------
-
-function resolveJuliaScript(ctx: vscode.ExtensionContext): string {
-  const fromCfg = vscode.workspace.getConfiguration("amicode").get<string>("juliaScript", "");
-  if (fromCfg && fs.existsSync(fromCfg)) return fromCfg;
-  const sibling = path.resolve(ctx.extensionPath, "..", "amicode", "julia", "spike_solve.jl");
-  if (fs.existsSync(sibling)) return sibling;
-  return path.join(ctx.extensionPath, "dist", "julia", "spike_solve.jl");
-}
-
-function resolveJuliaProject(): string {
-  return vscode.workspace.getConfiguration("amicode").get<string>("juliaProject", "/tmp/amicode-spike-julia");
-}
diff --git a/packages/extension/src/opencode_paths.ts b/packages/extension/src/opencode_paths.ts
new file mode 100644
index 000000000..0dcea8af1
--- /dev/null
+++ b/packages/extension/src/opencode_paths.ts
@@ -0,0 +1,29 @@
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/** Dir to prepend to opencode's PATH so `amico-run` resolves.
+ *  Packaged: <ext>/bin/launcher (staged by esbuild). Dev: workspace sibling. */
+export function resolveAmicoRunBinDir(extensionRoot: string): string | undefined {
+  const staged = join(extensionRoot, "bin", "launcher");
+  if (existsSync(join(staged, "amico-run"))) return staged;
+  const sibling = join(extensionRoot, "..", "amico-run", "launcher");
+  if (existsSync(join(sibling, "amico-run"))) return sibling;
+  return undefined;
+}
+
+/** Runs root the inspector watches; must match where amico-run writes.
+ *  Empty config → ~/.amico/runs/default (amico-run's β.1 default lab). */
+export function resolveRunsRoot(configValue: string): string {
+  const v = (configValue ?? "").trim();
+  if (v === "") return join(homedir(), ".amico", "runs", "default");
+  if (v === "~") return homedir();
+  if (v.startsWith("~/")) return join(homedir(), v.slice(2));
+  return v;
+}
+
+/** Local resource roots the inspector webview may load images from. Includes
+ *  the runs-root so live iter_*.png under ~/.amico/runs/... are not CSP-blocked (Q69). */
+export function inspectorResourceRootDirs(extensionRoot: string, runsRoot: string): string[] {
+  return [join(extensionRoot, "dist"), join(extensionRoot, "media"), runsRoot, "/tmp"];
+}
diff --git a/packages/extension/test/opencode_paths.test.ts b/packages/extension/test/opencode_paths.test.ts
new file mode 100644
index 000000000..d86c60397
--- /dev/null
+++ b/packages/extension/test/opencode_paths.test.ts
@@ -0,0 +1,43 @@
+import { describe, it, expect } from 'vitest'
+import { mkdtempSync, mkdirSync, writeFileSync } from 'node:fs'
+import { homedir, tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { resolveAmicoRunBinDir, resolveRunsRoot, inspectorResourceRootDirs } from '../src/opencode_paths'
+
+describe('resolveAmicoRunBinDir', () => {
+  it('prefers the staged bin/launcher when present (packaged VSIX)', () => {
+    const ext = mkdtempSync(join(tmpdir(), 'ext-'))
+    mkdirSync(join(ext, 'bin', 'launcher'), { recursive: true })
+    writeFileSync(join(ext, 'bin', 'launcher', 'amico-run'), '#!/usr/bin/env bash\n')
+    expect(resolveAmicoRunBinDir(ext)).toBe(join(ext, 'bin', 'launcher'))
+  })
+  it('falls back to the workspace sibling launcher (dev Extension Host)', () => {
+    const pkgs = mkdtempSync(join(tmpdir(), 'pkgs-'))
+    const ext = join(pkgs, 'extension'); mkdirSync(ext, { recursive: true })
+    const sib = join(pkgs, 'amico-run', 'launcher'); mkdirSync(sib, { recursive: true })
+    writeFileSync(join(sib, 'amico-run'), '#!/usr/bin/env bash\n')
+    expect(resolveAmicoRunBinDir(ext)).toBe(sib)
+  })
+  it('returns undefined when neither exists', () => {
+    expect(resolveAmicoRunBinDir(mkdtempSync(join(tmpdir(), 'none-')))).toBeUndefined()
+  })
+})
+
+describe('resolveRunsRoot', () => {
+  it('defaults to ~/.amico/runs/default computed via homedir', () => {
+    expect(resolveRunsRoot('')).toBe(join(homedir(), '.amico', 'runs', 'default'))
+  })
+  it('expands a leading ~ in a configured value', () => {
+    expect(resolveRunsRoot('~/custom/runs')).toBe(join(homedir(), 'custom', 'runs'))
+  })
+  it('passes an absolute path through', () => {
+    expect(resolveRunsRoot('/var/runs')).toBe('/var/runs')
+  })
+})
+
+describe('inspectorResourceRootDirs', () => {
+  it('includes the runs-root so live PNGs are not CSP-blocked', () => {
+    expect(inspectorResourceRootDirs('/ext', '/home/u/.amico/runs/default'))
+      .toContain('/home/u/.amico/runs/default')
+  })
+})

From b2ff7364e7f84a4c196759483e8c1c451ba73886 Mon Sep 17 00:00:00 2001
From: Raghav Chari <raghavchari2021@gmail.com>
Date: Mon, 15 Jun 2026 14:15:40 -0400
Subject: [PATCH 5/9] feat(extension): reconcile runs-root to
 ~/.amico/runs/default (matches amico-run); add amicode.runsRoot config

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 packages/extension/src/extension.ts | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/packages/extension/src/extension.ts b/packages/extension/src/extension.ts
index 972c3e583..91c5c51f5 100644
--- a/packages/extension/src/extension.ts
+++ b/packages/extension/src/extension.ts
@@ -8,7 +8,7 @@ import { registerRunInspector } from "./run_inspector";
 import { registerTrees } from "./trees";
 import { StatusBarManager } from "./status_bar";
 import { prepareOpencodeProject } from "./opencode_config";
-import { resolveAmicoRunBinDir } from "./opencode_paths";
+import { resolveAmicoRunBinDir, resolveRunsRoot } from "./opencode_paths";
 import { OpencodeEventClient } from "./sse_client";
 import { RunsRootWatcher } from "./file_watcher";
 
@@ -27,7 +27,6 @@ let sseClient: OpencodeEventClient | undefined;
 let watcher: RunsRootWatcher | undefined;
 let opencodeReadyUrl: URL | undefined;
 
-const DEFAULT_RUNS_ROOT = "/tmp/amicode-runs";
 
 export async function activate(ctx: vscode.ExtensionContext): Promise<void> {
   const opencodeChannel = vscode.window.createOutputChannel("Amicode — opencode");
@@ -42,7 +41,7 @@ export async function activate(ctx: vscode.ExtensionContext): Promise<void> {
 
   // 2. Start watching the runs root immediately — solves may already exist
   // from prior dev-host sessions, and watchers are cheap.
-  const runsRoot = vscode.workspace.getConfiguration("amicode").get<string>("runsRoot", DEFAULT_RUNS_ROOT);
+  const runsRoot = resolveRunsRoot(vscode.workspace.getConfiguration("amicode").get<string>("runsRoot", ""));
   fs.mkdirSync(runsRoot, { recursive: true });
   watcher = new RunsRootWatcher({ runsRoot, channel: runsChannel, statusBar });
   watcher.start();

From c60cdb3b508eeb8950a9303b8bb21c1b1ff4be88 Mon Sep 17 00:00:00 2001
From: Raghav Chari <raghavchari2021@gmail.com>
Date: Mon, 15 Jun 2026 14:20:17 -0400
Subject: [PATCH 6/9] =?UTF-8?q?feat(extension):=20watcher=20reads=20=CE=B2?=
 =?UTF-8?q?.1=20run-dir=20contract=20(FINISHED-keyed,=20manifest=20identit?=
 =?UTF-8?q?y,=20unbounded=20iter=20digits)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Pure vscode-free ingestRunDir in run_dir_reader.ts (unit-tested); RunsRootWatcher
adds incremental fs.watch + run.log tailing over it.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 packages/extension/src/file_watcher.ts        | 260 +++++++-----------
 packages/extension/src/run_dir_reader.ts      |  73 +++++
 packages/extension/src/types.ts               |   6 +-
 .../extension/test/watcher_contract.test.ts   |  48 ++++
 4 files changed, 225 insertions(+), 162 deletions(-)
 create mode 100644 packages/extension/src/run_dir_reader.ts
 create mode 100644 packages/extension/test/watcher_contract.test.ts

diff --git a/packages/extension/src/file_watcher.ts b/packages/extension/src/file_watcher.ts
index 8c07850c4..23c2a8ff7 100644
--- a/packages/extension/src/file_watcher.ts
+++ b/packages/extension/src/file_watcher.ts
@@ -1,55 +1,93 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import * as vscode from "vscode";
+import { validateFinished, validateResult } from "@amicode/amico-run";
 import { getInspector } from "./run_inspector";
 import type { StatusBarManager } from "./status_bar";
+import type { RunStatus } from "./types";
+import {
+  AMICODE_ITER_RE, ITER_PNG_RE, ingestRunDir, readTomlSafe,
+  type IterRecord, type RunCompletion, type PromoteInfo, type RunSink,
+} from "./run_dir_reader";
 
 // ============================================================================
-// RunsRootWatcher — the heart of the v2 CLI-direct architecture.
+// RunsRootWatcher — watches the β.1 run-dir contract and drives the Inspector
+// + status bar. Follows the `latest` symlink; for the active run it reads:
+//   manifest.toml  → run identity (run_id, lab_id), written FIRST
+//   iter_<N>.png   → live plot frames (unbounded digits)
+//   run.log        → AMICODE_ITER lines → live stats row
+//   result.toml    → fidelity (display + promote gate), atomic
+//   FINISHED       → authoritative terminal signal {status, exit_code}
 //
-// Sits on /tmp/amicode-runs/ and watches for:
-//   - new run subdirs (created by amico-run via mkdir + symlink swap)
-//   - the `latest` symlink target changing
-//   - per-run files inside the active run dir:
-//        .start              → run lifecycle begin
-//        iter_NNNN.png       → push to Run Inspector
-//        formulation.md      → auto-open markdown side preview
-//        result.toml         → final fidelity → promote-to-catalog QuickPick
-//        FINISHED            → release the run dir watcher
-//
-// We follow the `latest` symlink — when amico-run swings it, we re-target.
-// This keeps the watcher logic stateless w.r.t. who told us about the run;
-// no callback HTTP, no MCP, no event propagation across process boundaries.
+// Completion keys on FINISHED (not result.toml). The contract-reading logic is
+// the pure `ingestRunDir` in run_dir_reader.ts (replay/late-join, unit-tested);
+// the live path here adds incremental fs.watch + run.log tailing.
 // ============================================================================
 
 export interface RunsRootWatcherOptions {
   runsRoot: string;
   channel: vscode.OutputChannel;
   statusBar?: StatusBarManager;
-  /** Fidelity threshold (≥) at which to prompt promotion. Default 0.99. */
   promoteThreshold?: number;
 }
 
-const AMICODE_ITER_RE = /^AMICODE_ITER\s+iter=(\d+)\s+f=(-?\d+(?:\.\d+)?(?:[eE][-+]?\d+)?)\s+inf_pr=(-?\d+(?:\.\d+)?(?:[eE][-+]?\d+)?)\s+inf_du=(-?\d+(?:\.\d+)?(?:[eE][-+]?\d+)?)\s*$/;
+/** Live sink: routes to the Inspector + status bar, carrying newest-wins and
+ *  promote-once guards so replay-then-incremental never double-fires. */
+class LiveRunSink implements RunSink {
+  private latestIter = -1;
+  private promoted = false;
+  constructor(private readonly opts: RunsRootWatcherOptions) {}
+
+  image(fsPath: string, iter: number): void {
+    if (iter <= this.latestIter) return;
+    this.latestIter = iter;
+    getInspector()?.setImageSource(fsPath, iter);
+  }
+  iter(rec: IterRecord): void {
+    getInspector()?.postIterationRecord(rec);
+  }
+  run(c: RunCompletion): void {
+    this.opts.statusBar?.setRun({
+      runId: c.runId, outputDir: c.runDir, startedAt: 0,
+      status: c.status, latestIter: this.latestIter >= 0 ? this.latestIter : undefined,
+      fidelity: c.fidelity,
+    });
+    this.opts.channel.appendLine(`[runs] ${c.runId} ${c.status}${c.fidelity !== undefined ? ` F=${c.fidelity.toFixed(6)}` : ""}`);
+    if (c.status !== "completed") {
+      this.opts.channel.appendLine(`[runs] see ${path.join(c.runDir, "run.log")}`);
+    }
+  }
+  promote(info: PromoteInfo): void {
+    if (this.promoted) return;
+    this.promoted = true;
+    void (async () => {
+      const choice = await vscode.window.showInformationMessage(
+        `Amicode: solve converged (F=${info.fidelity.toFixed(4)}). Promote pulse to catalog?`,
+        "Yes — promote", "No — keep local only",
+      );
+      if (choice === "Yes — promote") {
+        vscode.window.showInformationMessage(`Amicode: promotion stub — would catalog ${info.runId}.`);
+        await vscode.commands.executeCommand("amicode.catalog.refresh").then(undefined, () => undefined);
+      }
+    })();
+  }
+}
 
 export class RunsRootWatcher implements vscode.Disposable {
   private rootWatcher?: fs.FSWatcher;
   private activeRunDir?: string;
   private activeRunWatcher?: fs.FSWatcher;
   private logTailer?: LogTailer;
-  private latestIter = -1;
-  private formulationOpened = false;
-  private promotedForRun = false;
+  private sink?: LiveRunSink;
+  private finishedSeen = false;
 
   constructor(private readonly opts: RunsRootWatcherOptions) {}
 
   start(): void {
     fs.mkdirSync(this.opts.runsRoot, { recursive: true });
-    // Pick up an in-progress or just-completed run if `latest` already exists.
     const latest = path.join(this.opts.runsRoot, "latest");
     if (fs.existsSync(latest)) this.followLatest();
-
-    this.rootWatcher = fs.watch(this.opts.runsRoot, { persistent: false }, (_event, filename) => {
+    this.rootWatcher = fs.watch(this.opts.runsRoot, { persistent: false }, (_e, filename) => {
       if (filename === "latest") this.followLatest();
     });
     this.opts.channel.appendLine(`[runs] watching ${this.opts.runsRoot}`);
@@ -64,17 +102,10 @@ export class RunsRootWatcher implements vscode.Disposable {
     this.logTailer = undefined;
   }
 
-  // ---------------------------------------------------------------------
-
   private followLatest(): void {
-    const latest = path.join(this.opts.runsRoot, "latest");
     let target: string | undefined;
-    try {
-      target = fs.realpathSync(latest);
-    } catch (err) {
-      this.opts.channel.appendLine(`[runs] latest unresolved: ${(err as Error).message}`);
-      return;
-    }
+    try { target = fs.realpathSync(path.join(this.opts.runsRoot, "latest")); }
+    catch (err) { this.opts.channel.appendLine(`[runs] latest unresolved: ${(err as Error).message}`); return; }
     if (target === this.activeRunDir) return;
     this.opts.channel.appendLine(`[runs] active run -> ${target}`);
     this.switchToRun(target);
@@ -84,138 +115,59 @@ export class RunsRootWatcher implements vscode.Disposable {
     try { this.activeRunWatcher?.close(); } catch { /* noop */ }
     this.logTailer?.dispose();
     this.activeRunDir = runDir;
-    this.latestIter = -1;
-    this.formulationOpened = false;
-    this.promotedForRun = false;
+    this.sink = new LiveRunSink(this.opts);
 
-    // Reveal the inspector so the user sees the new run start.
     getInspector()?.reveal();
-    this.opts.statusBar?.setRun({
-      runId: path.basename(runDir),
-      outputDir: runDir,
-      startedAt: Date.now(),
-      status: "running",
-    });
 
-    // Replay any files that already exist (we may be late to the run).
-    try {
-      for (const f of fs.readdirSync(runDir)) {
-        this.handle(f, path.join(runDir, f));
-      }
-    } catch (err) {
-      this.opts.channel.appendLine(`[runs] readdir failed: ${(err as Error).message}`);
-    }
+    // Replay everything already on disk (late-join safe).
+    try { ingestRunDir(runDir, this.sink, this.opts.promoteThreshold ?? 0.99); }
+    catch (err) { this.opts.channel.appendLine(`[runs] replay failed: ${(err as Error).message}`); }
+    this.finishedSeen = fs.existsSync(path.join(runDir, "FINISHED"));
 
-    this.activeRunWatcher = fs.watch(runDir, { persistent: false }, (_event, filename) => {
+    // Incremental: new iter PNGs + FINISHED.
+    this.activeRunWatcher = fs.watch(runDir, { persistent: false }, (_e, filename) => {
       if (!filename) return;
       const fp = path.join(runDir, filename);
       if (!fs.existsSync(fp)) return;
-      this.handle(filename, fp);
+      const m = ITER_PNG_RE.exec(filename);
+      if (m) { this.sink?.image(fp, parseInt(m[1], 10)); return; }
+      if (filename === "FINISHED" && !this.finishedSeen) { this.finishedSeen = true; this.onFinished(runDir); }
     });
 
-    // Tail run.log for AMICODE_ITER records → drives the Inspector stats row.
+    // Incremental: appended AMICODE_ITER lines.
     this.logTailer = new LogTailer({
       path: path.join(runDir, "run.log"),
       channel: this.opts.channel,
-      onLine: (line) => this.onLogLine(line),
+      onLine: (line) => {
+        const m = AMICODE_ITER_RE.exec(line);
+        if (m) this.sink?.iter({ iter: +m[1], f_val: +m[2], inf_pr: +m[3], inf_du: +m[4] });
+      },
     });
     this.logTailer.start();
   }
 
-  private onLogLine(line: string): void {
-    const m = AMICODE_ITER_RE.exec(line);
-    if (!m) return;
-    getInspector()?.postIterationRecord({
-      iter:   parseInt(m[1], 10),
-      f_val:  parseFloat(m[2]),
-      inf_pr: parseFloat(m[3]),
-      inf_du: parseFloat(m[4]),
-    });
-  }
-
-  private handle(filename: string, fp: string): void {
-    const iterMatch = /^iter_(\d{4})\.png$/.exec(filename);
-    if (iterMatch) {
-      const iter = parseInt(iterMatch[1], 10);
-      if (iter <= this.latestIter) return;
-      this.latestIter = iter;
-      getInspector()?.setImageSource(fp, iter);
-      this.opts.statusBar?.setRun({
-        runId: path.basename(this.activeRunDir!),
-        outputDir: this.activeRunDir!,
-        startedAt: 0,
-        status: "running",
-        latestIter: iter,
-      });
-      return;
+  private onFinished(runDir: string): void {
+    const finished = readTomlSafe(path.join(runDir, "FINISHED"));
+    if (!finished || !validateFinished(finished).ok) return;
+    const status = finished.status as RunStatus;
+    const runId = String(readTomlSafe(path.join(runDir, "manifest.toml"))?.run_id ?? path.basename(runDir));
+    let fidelity: number | undefined;
+    if (status === "completed") {
+      const result = readTomlSafe(path.join(runDir, "result.toml"));
+      if (result && validateResult(result).ok) fidelity = result.fidelity as number;
     }
-    if (filename === "final.png") {
-      getInspector()?.setImageSource(fp, this.latestIter + 1, /*final*/ true);
-      return;
+    this.sink?.run({ runId, runDir, status, fidelity });
+    if (status === "completed" && fidelity !== undefined && fidelity >= (this.opts.promoteThreshold ?? 0.99)) {
+      this.sink?.promote({ runId, runDir, fidelity });
     }
-    if (filename === "formulation.md" && !this.formulationOpened) {
-      this.formulationOpened = true;
-      vscode.commands
-        .executeCommand("markdown.showPreviewToSide", vscode.Uri.file(fp))
-        .then(undefined, (err) => this.opts.channel.appendLine(`[runs] preview failed: ${err}`));
-      return;
-    }
-    if (filename === "result.toml") {
-      this.onResult(fp);
-      return;
-    }
-  }
-
-  private onResult(resultPath: string): void {
-    if (this.promotedForRun) return;
-    let txt = "";
-    try { txt = fs.readFileSync(resultPath, "utf8"); }
-    catch { return; }
-    const fid = parseFloat(((txt.match(/fidelity\s*=\s*([\d.eE+-]+)/) ?? [])[1] ?? ""));
-    if (!Number.isFinite(fid)) return;
-
-    this.opts.statusBar?.setRun({
-      runId: path.basename(this.activeRunDir!),
-      outputDir: this.activeRunDir!,
-      startedAt: 0,
-      status: "completed",
-      latestIter: this.latestIter,
-    });
-    this.opts.channel.appendLine(`[runs] result.toml: F=${fid.toFixed(6)}`);
-
-    const threshold = this.opts.promoteThreshold ?? 0.99;
-    if (fid < threshold) return;
-    this.promotedForRun = true;
-
-    void (async () => {
-      const choice = await vscode.window.showInformationMessage(
-        `Amicode: solve converged (F=${fid.toFixed(4)}). Promote pulse to catalog?`,
-        { modal: false },
-        "Yes — promote",
-        "No — keep local only",
-      );
-      if (choice === "Yes — promote") {
-        // Catalog write isn't wired yet — toast for now.
-        vscode.window.showInformationMessage(
-          `Amicode: promotion stub — would copy ${path.basename(this.activeRunDir!)} to catalog.`,
-        );
-        await vscode.commands.executeCommand("amicode.catalog.refresh").then(undefined, () => undefined);
-      }
-    })();
   }
 }
 
 // ===========================================================================
-// LogTailer — follows run.log as julia appends to it, emits each new line via
-// onLine. Uses fs.watch + fs.read at the persisted offset; survives the file
-// not existing yet (amico-run touches it lazily via tee).
+// LogTailer — follows run.log as julia appends, emitting each new line.
 // ===========================================================================
 
-interface LogTailerOptions {
-  path: string;
-  channel: vscode.OutputChannel;
-  onLine: (line: string) => void;
-}
+interface LogTailerOptions { path: string; channel: vscode.OutputChannel; onLine: (line: string) => void }
 
 class LogTailer implements vscode.Disposable {
   private watcher?: fs.FSWatcher;
@@ -227,15 +179,10 @@ class LogTailer implements vscode.Disposable {
   constructor(private readonly opts: LogTailerOptions) {}
 
   start(): void {
-    // The log file may not exist yet (amico-run creates it via `tee`). Poll
-    // for it briefly; once it appears, switch to fs.watch.
     const tryAttach = () => {
       if (this.disposed) return;
-      if (fs.existsSync(this.opts.path)) {
-        this.attach();
-      } else {
-        this.pollTimer = setTimeout(tryAttach, 250);
-      }
+      if (fs.existsSync(this.opts.path)) this.attach();
+      else this.pollTimer = setTimeout(tryAttach, 250);
     };
     tryAttach();
   }
@@ -249,32 +196,24 @@ class LogTailer implements vscode.Disposable {
 
   private attach(): void {
     if (this.disposed) return;
+    // Skip the body already replayed by ingestRunDir; tail only appended lines.
+    try { this.offset = fs.statSync(this.opts.path).size; } catch { this.offset = 0; }
     try {
       this.watcher = fs.watch(this.opts.path, { persistent: false }, (event) => {
         if (event === "change") this.drain();
       });
     } catch (err) {
       this.opts.channel.appendLine(`[runs] log tail attach failed: ${(err as Error).message}`);
-      return;
     }
-    // Initial read in case content already exists.
-    this.drain();
   }
 
   private drain(): void {
     if (this.disposed) return;
     let fd: number;
+    try { fd = fs.openSync(this.opts.path, "r"); } catch { return; }
     try {
-      fd = fs.openSync(this.opts.path, "r");
-    } catch { return; }
-    try {
-      const stat = fs.fstatSync(fd);
-      const size = stat.size;
-      if (size < this.offset) {
-        // File was truncated (or replaced by a newer run somehow).
-        this.offset = 0;
-        this.buf = "";
-      }
+      const size = fs.fstatSync(fd).size;
+      if (size < this.offset) { this.offset = 0; this.buf = ""; }
       if (size === this.offset) return;
       const chunk = Buffer.allocUnsafe(size - this.offset);
       const read = fs.readSync(fd, chunk, 0, chunk.length, this.offset);
@@ -284,8 +223,7 @@ class LogTailer implements vscode.Disposable {
       while ((nl = this.buf.indexOf("\n")) >= 0) {
         const line = this.buf.slice(0, nl);
         this.buf = this.buf.slice(nl + 1);
-        try { this.opts.onLine(line); }
-        catch (e) { this.opts.channel.appendLine(`[runs] onLine threw: ${String(e)}`); }
+        try { this.opts.onLine(line); } catch (e) { this.opts.channel.appendLine(`[runs] onLine threw: ${String(e)}`); }
       }
     } finally {
       try { fs.closeSync(fd); } catch { /* noop */ }
diff --git a/packages/extension/src/run_dir_reader.ts b/packages/extension/src/run_dir_reader.ts
new file mode 100644
index 000000000..472ed44ba
--- /dev/null
+++ b/packages/extension/src/run_dir_reader.ts
@@ -0,0 +1,73 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { parse } from "smol-toml";
+import { validateManifest, validateFinished, validateResult } from "@amicode/amico-run";
+import type { RunStatus } from "./types";
+
+// ============================================================================
+// Pure (vscode-free) reader for the β.1 run-dir contract. Unit-testable in
+// isolation; the vscode-coupled RunsRootWatcher (file_watcher.ts) consumes it.
+// ============================================================================
+
+export const AMICODE_ITER_RE = /^AMICODE_ITER\s+iter=(\d+)\s+f=(-?\d+(?:\.\d+)?(?:[eE][-+]?\d+)?)\s+inf_pr=(-?\d+(?:\.\d+)?(?:[eE][-+]?\d+)?)\s+inf_du=(-?\d+(?:\.\d+)?(?:[eE][-+]?\d+)?)\s*$/;
+export const ITER_PNG_RE = /^iter_(\d+)\.png$/;   // unbounded digits (β.1 contract)
+
+export interface IterRecord { iter: number; f_val: number; inf_pr: number; inf_du: number }
+export interface RunCompletion { runId: string; runDir: string; status: RunStatus; fidelity?: number }
+export interface PromoteInfo { runId: string; runDir: string; fidelity: number }
+
+/** Where ingestRunDir routes its findings. The live impl carries the
+ *  newest-wins + promote-once guards; the test impl is plain spies. */
+export interface RunSink {
+  image(fsPath: string, iter: number): void;
+  iter(rec: IterRecord): void;
+  run(c: RunCompletion): void;
+  promote(info: PromoteInfo): void;
+}
+
+export function readTomlSafe(fp: string): Record<string, unknown> | undefined {
+  try { return parse(fs.readFileSync(fp, "utf8")) as Record<string, unknown>; }
+  catch { return undefined; }
+}
+
+/** Pure, stateless replay of a run dir against the β.1 contract. Calls each
+ *  sink method at most once per relevant artifact. Safe to re-invoke (the live
+ *  sink's guards make it idempotent). */
+export function ingestRunDir(runDir: string, sink: RunSink, promoteThreshold = 0.99): void {
+  const manifest = readTomlSafe(path.join(runDir, "manifest.toml"));
+  if (!manifest || !validateManifest(manifest).ok) return;   // no valid manifest → not a run dir yet
+  const runId = String(manifest.run_id);
+
+  // newest iter PNG
+  let newest = -1; let newestPath: string | undefined;
+  for (const f of fs.readdirSync(runDir)) {
+    const m = ITER_PNG_RE.exec(f);
+    if (m) { const k = parseInt(m[1], 10); if (k > newest) { newest = k; newestPath = path.join(runDir, f); } }
+  }
+  if (newestPath) sink.image(newestPath, newest);
+
+  // run.log body → iter records (replay; the live tailer handles appended lines)
+  let logBody: string | undefined;
+  try { logBody = fs.readFileSync(path.join(runDir, "run.log"), "utf8"); } catch { /* none yet */ }
+  if (logBody) {
+    for (const line of logBody.split("\n")) {
+      const m = AMICODE_ITER_RE.exec(line);
+      if (m) sink.iter({ iter: +m[1], f_val: +m[2], inf_pr: +m[3], inf_du: +m[4] });
+    }
+  }
+
+  // FINISHED is the authoritative terminal signal
+  const finished = readTomlSafe(path.join(runDir, "FINISHED"));
+  if (!finished || !validateFinished(finished).ok) return;
+  const status = finished.status as RunStatus;
+
+  let fidelity: number | undefined;
+  if (status === "completed") {
+    const result = readTomlSafe(path.join(runDir, "result.toml"));
+    if (result && validateResult(result).ok) fidelity = result.fidelity as number;
+  }
+  sink.run({ runId, runDir, status, fidelity });
+  if (status === "completed" && fidelity !== undefined && fidelity >= promoteThreshold) {
+    sink.promote({ runId, runDir, fidelity });
+  }
+}
diff --git a/packages/extension/src/types.ts b/packages/extension/src/types.ts
index af58fe091..bd0a3089b 100644
--- a/packages/extension/src/types.ts
+++ b/packages/extension/src/types.ts
@@ -15,13 +15,17 @@ export interface QuickPickReply {
   choice: string | null;
 }
 
+/** Terminal + in-flight run statuses. */
+export type RunStatus = "starting" | "running" | "completed" | "failed" | "aborted";
+
 /** Solve run state tracked by the extension. */
 export interface RunState {
   runId: string;
   outputDir: string;
   startedAt: number;
-  status: "starting" | "running" | "completed" | "failed";
+  status: RunStatus;
   latestIter?: number;
+  fidelity?: number;
 }
 
 /** Parsed AMICODE_ITER line from spike_solve.jl stdout. */
diff --git a/packages/extension/test/watcher_contract.test.ts b/packages/extension/test/watcher_contract.test.ts
new file mode 100644
index 000000000..5a24651ab
--- /dev/null
+++ b/packages/extension/test/watcher_contract.test.ts
@@ -0,0 +1,48 @@
+import { describe, it, expect, vi } from 'vitest'
+import { mkdtempSync, mkdirSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { ingestRunDir } from '../src/run_dir_reader'   // pure β.1-contract reader (vscode-free)
+
+function stageRun(opts: { status: string; exit: number; iters: number[]; fidelity?: number }): string {
+  const root = mkdtempSync(join(tmpdir(), 'runs-'))
+  const runId = 'r20260615-000000Z-ab12'
+  const dir = join(root, runId); mkdirSync(dir, { recursive: true })
+  writeFileSync(join(dir, 'manifest.toml'),
+    `schema_version = "1"\nrun_id = "${runId}"\nscript_path = "/s.jl"\nlab = "default"\nlab_id = "default"\ncreated_at = "2026-06-15T00:00:00Z"\norchestrator_version = "0.1.0"\n[julia]\nbinary = "julia"\n`)
+  for (const k of opts.iters) writeFileSync(join(dir, `iter_${k}.png`), 'PNG')
+  writeFileSync(join(dir, 'run.log'), opts.iters.map(k => `AMICODE_ITER iter=${k} f=0.1 inf_pr=1e-8 inf_du=1e-6`).join('\n') + '\n')
+  if (opts.fidelity !== undefined) writeFileSync(join(dir, 'result.toml'), `fidelity = ${opts.fidelity}\niterations = ${Math.max(...opts.iters, 0)}\n`)
+  writeFileSync(join(dir, 'FINISHED'), `status = "${opts.status}"\nexit_code = ${opts.exit}\n`)
+  return dir
+}
+
+const fakeSink = () => ({ image: vi.fn(), iter: vi.fn(), run: vi.fn(), promote: vi.fn() })
+
+describe('ingestRunDir — β.1 contract reading (replay)', () => {
+  it('completed run: identity from manifest, unbounded iter digits, run.log→iter, FINISHED→completed, promote on F≥0.99', () => {
+    const sink = fakeSink()
+    ingestRunDir(stageRun({ status: 'completed', exit: 0, iters: [1, 7, 142], fidelity: 0.9991 }), sink)
+    expect(sink.image).toHaveBeenCalled()                          // iter_142.png accepted (3 digits)
+    expect(sink.iter).toHaveBeenCalledWith(expect.objectContaining({ iter: 142 }))  // run.log parsed on REPLAY
+    expect(sink.run).toHaveBeenCalledWith(expect.objectContaining({ status: 'completed', fidelity: 0.9991 }))
+    expect(sink.promote).toHaveBeenCalled()
+  })
+  it('failed run: FINISHED→failed, no promote', () => {
+    const sink = fakeSink()
+    ingestRunDir(stageRun({ status: 'failed', exit: 3, iters: [1], fidelity: 0.4 }), sink)
+    expect(sink.run).toHaveBeenCalledWith(expect.objectContaining({ status: 'failed' }))
+    expect(sink.promote).not.toHaveBeenCalled()
+  })
+  it('aborted run: FINISHED→aborted, no promote', () => {
+    const sink = fakeSink()
+    ingestRunDir(stageRun({ status: 'aborted', exit: 143, iters: [] }), sink)
+    expect(sink.run).toHaveBeenCalledWith(expect.objectContaining({ status: 'aborted' }))
+    expect(sink.promote).not.toHaveBeenCalled()
+  })
+  it('completed but F<0.99: no promote', () => {
+    const sink = fakeSink()
+    ingestRunDir(stageRun({ status: 'completed', exit: 0, iters: [1], fidelity: 0.5 }), sink)
+    expect(sink.promote).not.toHaveBeenCalled()
+  })
+})

From 4d01de44e86f78f6355cf3c9ef4aa53da8fa8218 Mon Sep 17 00:00:00 2001
From: Raghav Chari <raghavchari2021@gmail.com>
Date: Mon, 15 Jun 2026 14:22:07 -0400
Subject: [PATCH 7/9] feat(extension): inspector resource-root fix (Q69);
 status-bar failed/aborted + fidelity display

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 packages/extension/src/extension.ts     |  6 ++++--
 packages/extension/src/run_inspector.ts | 16 ++++++++--------
 packages/extension/src/status_bar.ts    | 13 ++++++++++++-
 3 files changed, 24 insertions(+), 11 deletions(-)

diff --git a/packages/extension/src/extension.ts b/packages/extension/src/extension.ts
index 91c5c51f5..2333ef6f3 100644
--- a/packages/extension/src/extension.ts
+++ b/packages/extension/src/extension.ts
@@ -33,15 +33,17 @@ export async function activate(ctx: vscode.ExtensionContext): Promise<void> {
   const runsChannel = vscode.window.createOutputChannel("Amicode — runs");
   ctx.subscriptions.push(opencodeChannel, runsChannel);
 
+  // Runs root (resolved early — the inspector needs it for its CSP resource roots).
+  const runsRoot = resolveRunsRoot(vscode.workspace.getConfiguration("amicode").get<string>("runsRoot", ""));
+
   // 1. UI surfaces
   registerTrees(ctx);
-  registerRunInspector(ctx);
+  registerRunInspector(ctx, runsRoot);
   statusBar = new StatusBarManager();
   ctx.subscriptions.push({ dispose: () => statusBar?.dispose() });
 
   // 2. Start watching the runs root immediately — solves may already exist
   // from prior dev-host sessions, and watchers are cheap.
-  const runsRoot = resolveRunsRoot(vscode.workspace.getConfiguration("amicode").get<string>("runsRoot", ""));
   fs.mkdirSync(runsRoot, { recursive: true });
   watcher = new RunsRootWatcher({ runsRoot, channel: runsChannel, statusBar });
   watcher.start();
diff --git a/packages/extension/src/run_inspector.ts b/packages/extension/src/run_inspector.ts
index a578ff6de..7d4634aca 100644
--- a/packages/extension/src/run_inspector.ts
+++ b/packages/extension/src/run_inspector.ts
@@ -1,5 +1,6 @@
 import * as vscode from "vscode";
 import * as path from "node:path";
+import { inspectorResourceRootDirs } from "./opencode_paths";
 
 // ============================================================================
 // Run Inspector — bottom-panel webview that shows the live pulse-plot stream
@@ -22,15 +23,14 @@ class InspectorView implements vscode.WebviewViewProvider {
   /** Set BEFORE the webview is materialized — replayed in resolveWebviewView. */
   private bufferedImage?: { fsPath: string; iter: number; isFinal: boolean };
 
-  constructor(private readonly ctx: vscode.ExtensionContext) {}
+  constructor(private readonly ctx: vscode.ExtensionContext, private readonly runsRoot: string) {}
 
   resolveWebviewView(view: vscode.WebviewView): void {
     this.view = view;
-    const resourceRoots: vscode.Uri[] = [
-      vscode.Uri.joinPath(this.ctx.extensionUri, "dist"),
-      vscode.Uri.joinPath(this.ctx.extensionUri, "media"),
-      vscode.Uri.file("/tmp"),
-    ];
+    // Q69: include the runs-root, else iter_*.png under ~/.amico/runs/... is
+    // CSP-blocked → permanently blank inspector.
+    const resourceRoots: vscode.Uri[] = inspectorResourceRootDirs(this.ctx.extensionUri.fsPath, this.runsRoot)
+      .map((d) => vscode.Uri.file(d));
     for (const f of vscode.workspace.workspaceFolders ?? []) {
       resourceRoots.push(f.uri);
     }
@@ -178,8 +178,8 @@ function newNonce(): string {
   return s;
 }
 
-export function registerRunInspector(ctx: vscode.ExtensionContext): InspectorView {
-  INSPECTOR = new InspectorView(ctx);
+export function registerRunInspector(ctx: vscode.ExtensionContext, runsRoot: string): InspectorView {
+  INSPECTOR = new InspectorView(ctx, runsRoot);
   ctx.subscriptions.push(
     vscode.window.registerWebviewViewProvider("amicode.runInspector", INSPECTOR, {
       webviewOptions: { retainContextWhenHidden: true },
diff --git a/packages/extension/src/status_bar.ts b/packages/extension/src/status_bar.ts
index c5c2c05f9..b8445df17 100644
--- a/packages/extension/src/status_bar.ts
+++ b/packages/extension/src/status_bar.ts
@@ -44,10 +44,21 @@ export class StatusBarManager {
       return;
     }
     if (this.run && this.run.status === "completed") {
-      this.item.text = "$(check) Amicode · last F=" + (this.run.latestIter ?? "—");
+      const f = this.run.fidelity;
+      this.item.text = `$(check) Amicode · F=${f !== undefined ? f.toFixed(4) : "—"}`;
       this.item.tooltip = `Last solve completed in ${this.run.outputDir}`;
       return;
     }
+    if (this.run && this.run.status === "failed") {
+      this.item.text = "$(error) Amicode · solve failed";
+      this.item.tooltip = `Solve failed in ${this.run.outputDir} — see run.log`;
+      return;
+    }
+    if (this.run && this.run.status === "aborted") {
+      this.item.text = "$(circle-slash) Amicode · aborted";
+      this.item.tooltip = `Solve aborted in ${this.run.outputDir}`;
+      return;
+    }
     this.item.text = "$(comment-discussion) Amicode";
     this.item.tooltip = "Open Amicode chat";
   }

From 259cdf69fd5b02748f7e57d4ecac8f1c58d91c77 Mon Sep 17 00:00:00 2001
From: Raghav Chari <raghavchari2021@gmail.com>
Date: Wed, 17 Jun 2026 12:00:50 -0400
Subject: [PATCH 8/9] =?UTF-8?q?fix(extension):=20vet=20template=20on=20Pic?=
 =?UTF-8?q?colo=201.19;=20public=20Piccolo.Callbacks=20(no=20reach-through?=
 =?UTF-8?q?);=20rollout+subspace=20fidelity=20(F=3D0.99994,=20=E2=89=A41)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Re-vetted against Piccolo 1.19 (what Pkg.add installs today, per Jack's #7 note).
Kills the methods(solve!) IpoptSolverExt reach-through — Callbacks is public in 1.19.
Fidelity now = unitary_fidelity over the computational subspace from a fresh
unitary_rollout (was reading >1 from raw-propagator integrator drift).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../extension/templates/solve_template.jl     | 45 ++++++++++---------
 1 file changed, 24 insertions(+), 21 deletions(-)

diff --git a/packages/extension/templates/solve_template.jl b/packages/extension/templates/solve_template.jl
index 87d97f738..7eda801c9 100644
--- a/packages/extension/templates/solve_template.jl
+++ b/packages/extension/templates/solve_template.jl
@@ -2,8 +2,8 @@
 # Amicode solve template — fill in the `# FILL IN` block, then:
 #   amico-run --project <julia-project> solve.jl
 # Emits the run-dir contract (AMICODE_ITER, iter_<N>.png, result.toml, pulse.jld2, DONE).
-# Vetted against Piccolo 0.11 (QuantumCollocation/DirectTrajOpt 0.8): a single-qubit
-# X gate on a 3-level transmon converges to subspace fidelity ~1.0 in ~1 min.
+# Vetted against Piccolo 1.19 (the version `Pkg.add Piccolo` installs today): a
+# single-qubit X gate on a 3-level transmon converges to subspace fidelity ~1.0.
 using Piccolo
 using CairoMakie
 using JLD2
@@ -29,32 +29,30 @@ qtraj = UnitaryTrajectory(sys, ZeroOrderPulse(initial, times), op)
 qcp = SmoothPulseProblem(qtraj, N;
     piccolo_options = PiccoloOptions(timesteps_all_equal = true),
     Q = 100.0, R = 1e-2)
-dto_prob = hasproperty(qcp, :prob) ? qcp.prob : qcp
+prob = hasproperty(qcp, :prob) ? qcp.prob : qcp
 
-# Per-iter callback machinery lives in DirectTrajOpt's internal IpoptSolverExt
-# (not re-exported); reach it through the solve! method table (β.1 pattern).
-const Callbacks = first(filter(
-    m -> string(m.module) == "DirectTrajOpt.IpoptSolverExt",
-    collect(methods(solve!)))).module.Callbacks
+# Per-iter callbacks via Piccolo's PUBLIC `Callbacks` module (Piccolo 1.19).
+# NOTE on solver portability: this is the Ipopt intermediate-callback path
+# (rich state: obj_value/inf_pr/inf_du). When the default solver moves to
+# MadNLP/Altissimo, migrate to the solver-agnostic `AbstractIntermediateCallback`
+# (e.g. `LivePulsePlotCallback`), which fires `(primal, iter)` across backends.
+const CB = Piccolo.Callbacks
 
 const PLOT_EVERY = 10
 iters = Ref(0)
-cb_update = Callbacks.callback_update_trajectory_factory(dto_prob)
 function cb_log(optimizer, st; kwargs...)
     k = Int(st.iter_count); iters[] = k
     @printf("AMICODE_ITER iter=%d f=%.6e inf_pr=%.3e inf_du=%.3e\n", k, st.obj_value, st.inf_pr, st.inf_du)
     flush(stdout)
-    if k % PLOT_EVERY == 0
-        save_control_plot(k)
-    end
+    (k % PLOT_EVERY == 0) && save_control_plot(k)
     return true
 end
 
-# Cheap per-iter plot: control amplitudes vs time (no rollout — keeps the
-# live solve fast). `cb_update` has refreshed dto_prob.trajectory by now.
+# Cheap per-iter plot: control amplitudes vs time (no rollout — keeps the live
+# solve fast). callback_update_trajectory_factory keeps prob.trajectory current.
 function save_control_plot(k::Int)
     try
-        u = dto_prob.trajectory[:u]            # (n_drives × N) control amplitudes
+        u = prob.trajectory[:u]                 # (n_drives × N) control amplitudes
         fig = Figure(size = (640, 360))
         ax = Axis(fig[1, 1], xlabel = "timestep", ylabel = "drive amplitude (GHz)",
                   title = @sprintf("iter %d", k))
@@ -70,18 +68,23 @@ end
 
 t0 = time()
 solve!(qcp; max_iter = max_iter, print_level = 1,
-       callback = Callbacks.callback_factory(cb_update, cb_log))
+       callback = CB.callback_factory(CB.callback_update_trajectory_factory(prob), cb_log))
 wall = time() - t0
 
-# Fidelity over the COMPUTATIONAL subspace (full-space fidelity is misleading
-# for an embedded gate — it includes leakage levels + global phase).
-Ufin = iso_vec_to_operator(get_trajectory(qcp)[:Ũ⃗][:, end])
-fid  = unitary_fidelity(Ufin, op.operator; subspace = op.subspace)
+# Fidelity over the COMPUTATIONAL subspace, from a fresh high-tolerance rollout.
+# Two reasons this is the right metric:
+#   - subspace (not full-space): the embedded goal pins identity on the leakage
+#     level, which the solve doesn't enforce — full-space would read ~0.44 even
+#     for a perfect qubit gate. We want the gate fidelity on {|0>,|1>}.
+#   - rollout (not the raw final propagator): re-integrating at 1e-8 yields a
+#     clean unitary, avoiding the ~1e-6 norm-drift that made the raw block read >1.
+Uroll = iso_vec_to_operator(unitary_rollout(get_trajectory(qcp), sys)[:, end])
+fid   = unitary_fidelity(Uroll, op.operator; subspace = op.subspace)
 
 # ensure at least one PNG even if the solve stopped before PLOT_EVERY
 isfile(@sprintf("iter_%04d.png", iters[])) || save_control_plot(iters[])
 
-JLD2.save("pulse.jld2", "trajectory", dto_prob.trajectory)
+JLD2.save("pulse.jld2", "trajectory", prob.trajectory)
 open("result.toml.tmp", "w") do io
     TOML.print(io, Dict("fidelity" => fid, "iterations" => iters[], "wall_seconds" => wall))
 end

From a5121a9f6cd78f8d73e415243781317da55ab0ec Mon Sep 17 00:00:00 2001
From: Raghav Chari <raghavchari2021@gmail.com>
Date: Sat, 20 Jun 2026 21:40:04 -0400
Subject: [PATCH 9/9] =?UTF-8?q?fix(extension):=20address=20Jack's=20=CE=B2?=
 =?UTF-8?q?.3=20review=20(#9)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- warm-start (#3 AC2): template saves JLD2 key 'traj' so load_traj reloads it.
- status bar (#5 AC3): show 'running · iter N' live (sink.iter → setRun), not
  only at completion.
- live-stats (#5 AC2): AMICODE_ITER regex + parseAmicoNum accept Inf/-Inf/NaN
  so blow-up/stagnation iters aren't silently dropped (matches amico-run).
- log tailer: ingestRunDir returns the run.log bytes consumed; the tailer
  attaches at that offset (no skipped iters between replay and attach).
- promote-once: a run promotes at most once across run-switches; an
  already-finished run (launch-follows-latest / switch-back) never re-pops.
- inspector roots: drop the blanket /tmp webview root (redundant with runsRoot).
- result.toml records the scalar solve params (self-describing run).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 packages/extension/src/file_watcher.ts        | 59 ++++++++++++++-----
 packages/extension/src/opencode_paths.ts      |  5 +-
 packages/extension/src/run_dir_reader.ts      | 31 ++++++++--
 .../extension/templates/solve_template.jl     | 10 +++-
 .../extension/test/watcher_contract.test.ts   | 20 ++++++-
 5 files changed, 101 insertions(+), 24 deletions(-)

diff --git a/packages/extension/src/file_watcher.ts b/packages/extension/src/file_watcher.ts
index 23c2a8ff7..6d9a70762 100644
--- a/packages/extension/src/file_watcher.ts
+++ b/packages/extension/src/file_watcher.ts
@@ -6,7 +6,7 @@ import { getInspector } from "./run_inspector";
 import type { StatusBarManager } from "./status_bar";
 import type { RunStatus } from "./types";
 import {
-  AMICODE_ITER_RE, ITER_PNG_RE, ingestRunDir, readTomlSafe,
+  AMICODE_ITER_RE, ITER_PNG_RE, ingestRunDir, readTomlSafe, parseAmicoNum,
   type IterRecord, type RunCompletion, type PromoteInfo, type RunSink,
 } from "./run_dir_reader";
 
@@ -35,8 +35,13 @@ export interface RunsRootWatcherOptions {
  *  promote-once guards so replay-then-incremental never double-fires. */
 class LiveRunSink implements RunSink {
   private latestIter = -1;
-  private promoted = false;
-  constructor(private readonly opts: RunsRootWatcherOptions) {}
+  constructor(
+    private readonly opts: RunsRootWatcherOptions,
+    private readonly runId: string,
+    private readonly runDir: string,
+    /** Shared across run-switches so a run promotes at most once (no re-pop). */
+    private readonly promotedRuns: Set<string>,
+  ) {}
 
   image(fsPath: string, iter: number): void {
     if (iter <= this.latestIter) return;
@@ -44,7 +49,14 @@ class LiveRunSink implements RunSink {
     getInspector()?.setImageSource(fsPath, iter);
   }
   iter(rec: IterRecord): void {
+    if (rec.iter > this.latestIter) this.latestIter = rec.iter;
     getInspector()?.postIterationRecord(rec);
+    // Live status-bar update — show "running · iter N" as it solves, not only at
+    // completion (#5 AC3).
+    this.opts.statusBar?.setRun({
+      runId: this.runId, outputDir: this.runDir, startedAt: 0,
+      status: "running", latestIter: rec.iter,
+    });
   }
   run(c: RunCompletion): void {
     this.opts.statusBar?.setRun({
@@ -58,8 +70,8 @@ class LiveRunSink implements RunSink {
     }
   }
   promote(info: PromoteInfo): void {
-    if (this.promoted) return;
-    this.promoted = true;
+    if (this.promotedRuns.has(info.runId)) return;
+    this.promotedRuns.add(info.runId);
     void (async () => {
       const choice = await vscode.window.showInformationMessage(
         `Amicode: solve converged (F=${info.fidelity.toFixed(4)}). Promote pulse to catalog?`,
@@ -80,6 +92,10 @@ export class RunsRootWatcher implements vscode.Disposable {
   private logTailer?: LogTailer;
   private sink?: LiveRunSink;
   private finishedSeen = false;
+  /** Runs already promoted (or already-finished when first switched to) — so the
+   *  promote prompt fires at most once per run, never re-popping on re-switch /
+   *  launch-follows-latest. */
+  private readonly promotedRuns = new Set<string>();
 
   constructor(private readonly opts: RunsRootWatcherOptions) {}
 
@@ -115,14 +131,24 @@ export class RunsRootWatcher implements vscode.Disposable {
     try { this.activeRunWatcher?.close(); } catch { /* noop */ }
     this.logTailer?.dispose();
     this.activeRunDir = runDir;
-    this.sink = new LiveRunSink(this.opts);
 
+    const runId = String(readTomlSafe(path.join(runDir, "manifest.toml"))?.run_id ?? path.basename(runDir));
+    // If the run was ALREADY finished when we switched to it (e.g. launch follows
+    // `latest` to a prior completed run, or the user switches back), don't pop the
+    // promote prompt — only a FRESH live completion promotes. Pre-marking the run
+    // suppresses the replay-driven promote below.
+    const finishedAtSwitch = fs.existsSync(path.join(runDir, "FINISHED"));
+    if (finishedAtSwitch) this.promotedRuns.add(runId);
+
+    this.sink = new LiveRunSink(this.opts, runId, runDir, this.promotedRuns);
     getInspector()?.reveal();
 
-    // Replay everything already on disk (late-join safe).
-    try { ingestRunDir(runDir, this.sink, this.opts.promoteThreshold ?? 0.99); }
+    // Replay everything already on disk (late-join safe). Returns the run.log
+    // bytes consumed so the tailer attaches exactly there (no skipped iters).
+    let logBytes = 0;
+    try { logBytes = ingestRunDir(runDir, this.sink, this.opts.promoteThreshold ?? 0.99); }
     catch (err) { this.opts.channel.appendLine(`[runs] replay failed: ${(err as Error).message}`); }
-    this.finishedSeen = fs.existsSync(path.join(runDir, "FINISHED"));
+    this.finishedSeen = finishedAtSwitch;
 
     // Incremental: new iter PNGs + FINISHED.
     this.activeRunWatcher = fs.watch(runDir, { persistent: false }, (_e, filename) => {
@@ -134,13 +160,15 @@ export class RunsRootWatcher implements vscode.Disposable {
       if (filename === "FINISHED" && !this.finishedSeen) { this.finishedSeen = true; this.onFinished(runDir); }
     });
 
-    // Incremental: appended AMICODE_ITER lines.
+    // Incremental: appended AMICODE_ITER lines — start at the ingest offset so a
+    // line written between the replay read and this attach isn't skipped.
     this.logTailer = new LogTailer({
       path: path.join(runDir, "run.log"),
+      startOffset: logBytes,
       channel: this.opts.channel,
       onLine: (line) => {
         const m = AMICODE_ITER_RE.exec(line);
-        if (m) this.sink?.iter({ iter: +m[1], f_val: +m[2], inf_pr: +m[3], inf_du: +m[4] });
+        if (m) this.sink?.iter({ iter: +m[1], f_val: parseAmicoNum(m[2]), inf_pr: parseAmicoNum(m[3]), inf_du: parseAmicoNum(m[4]) });
       },
     });
     this.logTailer.start();
@@ -167,7 +195,7 @@ export class RunsRootWatcher implements vscode.Disposable {
 // LogTailer — follows run.log as julia appends, emitting each new line.
 // ===========================================================================
 
-interface LogTailerOptions { path: string; channel: vscode.OutputChannel; onLine: (line: string) => void }
+interface LogTailerOptions { path: string; channel: vscode.OutputChannel; onLine: (line: string) => void; startOffset?: number }
 
 class LogTailer implements vscode.Disposable {
   private watcher?: fs.FSWatcher;
@@ -196,8 +224,9 @@ class LogTailer implements vscode.Disposable {
 
   private attach(): void {
     if (this.disposed) return;
-    // Skip the body already replayed by ingestRunDir; tail only appended lines.
-    try { this.offset = fs.statSync(this.opts.path).size; } catch { this.offset = 0; }
+    // Start where ingestRunDir stopped reading (startOffset), not at current EOF —
+    // otherwise lines appended between the replay read and this attach are lost.
+    this.offset = this.opts.startOffset ?? 0;
     try {
       this.watcher = fs.watch(this.opts.path, { persistent: false }, (event) => {
         if (event === "change") this.drain();
@@ -205,6 +234,8 @@ class LogTailer implements vscode.Disposable {
     } catch (err) {
       this.opts.channel.appendLine(`[runs] log tail attach failed: ${(err as Error).message}`);
     }
+    // Drain immediately to catch lines already written past startOffset.
+    this.drain();
   }
 
   private drain(): void {
diff --git a/packages/extension/src/opencode_paths.ts b/packages/extension/src/opencode_paths.ts
index 0dcea8af1..5861e6d02 100644
--- a/packages/extension/src/opencode_paths.ts
+++ b/packages/extension/src/opencode_paths.ts
@@ -25,5 +25,8 @@ export function resolveRunsRoot(configValue: string): string {
 /** Local resource roots the inspector webview may load images from. Includes
  *  the runs-root so live iter_*.png under ~/.amico/runs/... are not CSP-blocked (Q69). */
 export function inspectorResourceRootDirs(extensionRoot: string, runsRoot: string): string[] {
-  return [join(extensionRoot, "dist"), join(extensionRoot, "media"), runsRoot, "/tmp"];
+  // dist + media (extension assets) and runsRoot (live iter_*.png). No "/tmp":
+  // the inspector only renders run-dir frames under runsRoot, so a blanket /tmp
+  // root needlessly broadened the webview's allowed file roots.
+  return [join(extensionRoot, "dist"), join(extensionRoot, "media"), runsRoot];
 }
diff --git a/packages/extension/src/run_dir_reader.ts b/packages/extension/src/run_dir_reader.ts
index 472ed44ba..e810faf1d 100644
--- a/packages/extension/src/run_dir_reader.ts
+++ b/packages/extension/src/run_dir_reader.ts
@@ -9,9 +9,23 @@ import type { RunStatus } from "./types";
 // isolation; the vscode-coupled RunsRootWatcher (file_watcher.ts) consumes it.
 // ============================================================================
 
-export const AMICODE_ITER_RE = /^AMICODE_ITER\s+iter=(\d+)\s+f=(-?\d+(?:\.\d+)?(?:[eE][-+]?\d+)?)\s+inf_pr=(-?\d+(?:\.\d+)?(?:[eE][-+]?\d+)?)\s+inf_du=(-?\d+(?:\.\d+)?(?:[eE][-+]?\d+)?)\s*$/;
+// Float group accepts Julia's @printf %e output incl. Inf/-Inf/NaN, so stagnation
+// and blow-up iters aren't silently dropped (they're what a researcher most wants
+// to see) — matching amico-run's own classifier, which keeps them.
+const NUM = String.raw`-?(?:Inf|NaN|\d+(?:\.\d+)?(?:[eE][-+]?\d+)?)`;
+export const AMICODE_ITER_RE = new RegExp(
+  String.raw`^AMICODE_ITER\s+iter=(\d+)\s+f=(${NUM})\s+inf_pr=(${NUM})\s+inf_du=(${NUM})\s*$`,
+);
 export const ITER_PNG_RE = /^iter_(\d+)\.png$/;   // unbounded digits (β.1 contract)
 
+/** Parse an AMICODE_ITER numeric field, mapping Julia's Inf/NaN to JS values. */
+export function parseAmicoNum(s: string): number {
+  if (s === "Inf") return Infinity;
+  if (s === "-Inf") return -Infinity;
+  if (s === "NaN" || s === "-NaN") return NaN;
+  return Number(s);
+}
+
 export interface IterRecord { iter: number; f_val: number; inf_pr: number; inf_du: number }
 export interface RunCompletion { runId: string; runDir: string; status: RunStatus; fidelity?: number }
 export interface PromoteInfo { runId: string; runDir: string; fidelity: number }
@@ -32,10 +46,12 @@ export function readTomlSafe(fp: string): Record<string, unknown> | undefined {
 
 /** Pure, stateless replay of a run dir against the β.1 contract. Calls each
  *  sink method at most once per relevant artifact. Safe to re-invoke (the live
- *  sink's guards make it idempotent). */
-export function ingestRunDir(runDir: string, sink: RunSink, promoteThreshold = 0.99): void {
+ *  sink's guards make it idempotent). Returns the number of run.log bytes
+ *  consumed, so the live tailer can attach exactly there — no gap (lines
+ *  appended after the read are tailed) and no overlap (already-replayed lines). */
+export function ingestRunDir(runDir: string, sink: RunSink, promoteThreshold = 0.99): number {
   const manifest = readTomlSafe(path.join(runDir, "manifest.toml"));
-  if (!manifest || !validateManifest(manifest).ok) return;   // no valid manifest → not a run dir yet
+  if (!manifest || !validateManifest(manifest).ok) return 0;   // no valid manifest → not a run dir yet
   const runId = String(manifest.run_id);
 
   // newest iter PNG
@@ -49,16 +65,18 @@ export function ingestRunDir(runDir: string, sink: RunSink, promoteThreshold = 0
   // run.log body → iter records (replay; the live tailer handles appended lines)
   let logBody: string | undefined;
   try { logBody = fs.readFileSync(path.join(runDir, "run.log"), "utf8"); } catch { /* none yet */ }
+  let logBytes = 0;
   if (logBody) {
+    logBytes = Buffer.byteLength(logBody, "utf8");
     for (const line of logBody.split("\n")) {
       const m = AMICODE_ITER_RE.exec(line);
-      if (m) sink.iter({ iter: +m[1], f_val: +m[2], inf_pr: +m[3], inf_du: +m[4] });
+      if (m) sink.iter({ iter: +m[1], f_val: parseAmicoNum(m[2]), inf_pr: parseAmicoNum(m[3]), inf_du: parseAmicoNum(m[4]) });
     }
   }
 
   // FINISHED is the authoritative terminal signal
   const finished = readTomlSafe(path.join(runDir, "FINISHED"));
-  if (!finished || !validateFinished(finished).ok) return;
+  if (!finished || !validateFinished(finished).ok) return logBytes;
   const status = finished.status as RunStatus;
 
   let fidelity: number | undefined;
@@ -70,4 +88,5 @@ export function ingestRunDir(runDir: string, sink: RunSink, promoteThreshold = 0
   if (status === "completed" && fidelity !== undefined && fidelity >= promoteThreshold) {
     sink.promote({ runId, runDir, fidelity });
   }
+  return logBytes;
 }
diff --git a/packages/extension/templates/solve_template.jl b/packages/extension/templates/solve_template.jl
index 7eda801c9..fda4af98f 100644
--- a/packages/extension/templates/solve_template.jl
+++ b/packages/extension/templates/solve_template.jl
@@ -84,9 +84,15 @@ fid   = unitary_fidelity(Uroll, op.operator; subspace = op.subspace)
 # ensure at least one PNG even if the solve stopped before PLOT_EVERY
 isfile(@sprintf("iter_%04d.png", iters[])) || save_control_plot(iters[])
 
-JLD2.save("pulse.jld2", "trajectory", prob.trajectory)
+JLD2.save("pulse.jld2", "traj", prob.trajectory)   # key "traj" so `load_traj` can reload it (warm-start)
 open("result.toml.tmp", "w") do io
-    TOML.print(io, Dict("fidelity" => fid, "iterations" => iters[], "wall_seconds" => wall))
+    # Record the regime each run actually solved (scalar FILL-IN params), so the
+    # result is self-describing — not just fidelity/iterations.
+    TOML.print(io, Dict(
+        "fidelity" => fid, "iterations" => iters[], "wall_seconds" => wall,
+        "params" => Dict("delta" => δ, "levels" => levels, "T" => T, "N" => N,
+                         "drive_max" => drive_max, "max_iter" => max_iter),
+    ))
 end
 mv("result.toml.tmp", "result.toml"; force = true)
 println("DONE fidelity=$(fid)"); flush(stdout)
diff --git a/packages/extension/test/watcher_contract.test.ts b/packages/extension/test/watcher_contract.test.ts
index 5a24651ab..e9f0ac779 100644
--- a/packages/extension/test/watcher_contract.test.ts
+++ b/packages/extension/test/watcher_contract.test.ts
@@ -2,7 +2,7 @@ import { describe, it, expect, vi } from 'vitest'
 import { mkdtempSync, mkdirSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
-import { ingestRunDir } from '../src/run_dir_reader'   // pure β.1-contract reader (vscode-free)
+import { ingestRunDir, AMICODE_ITER_RE, parseAmicoNum } from '../src/run_dir_reader'   // pure β.1-contract reader (vscode-free)
 
 function stageRun(opts: { status: string; exit: number; iters: number[]; fidelity?: number }): string {
   const root = mkdtempSync(join(tmpdir(), 'runs-'))
@@ -45,4 +45,22 @@ describe('ingestRunDir — β.1 contract reading (replay)', () => {
     ingestRunDir(stageRun({ status: 'completed', exit: 0, iters: [1], fidelity: 0.5 }), sink)
     expect(sink.promote).not.toHaveBeenCalled()
   })
+  it('returns the run.log byte offset (so the live tailer attaches without skipping iters)', () => {
+    const sink = fakeSink()
+    const bytes = ingestRunDir(stageRun({ status: 'completed', exit: 0, iters: [1, 2], fidelity: 0.999 }), sink)
+    expect(bytes).toBeGreaterThan(0)   // = byte length of run.log consumed during replay
+  })
+})
+
+describe('AMICODE_ITER parsing — Inf/NaN are kept, not dropped', () => {
+  it('matches blow-up / stagnation iters (Inf, -Inf, NaN), matching amico-run', () => {
+    expect(AMICODE_ITER_RE.test('AMICODE_ITER iter=3 f=Inf inf_pr=NaN inf_du=-Inf')).toBe(true)
+    expect(AMICODE_ITER_RE.test('AMICODE_ITER iter=4 f=1.2e-03 inf_pr=5e-9 inf_du=2.3')).toBe(true)
+  })
+  it('parseAmicoNum maps Julia Inf/NaN to JS values', () => {
+    expect(parseAmicoNum('Inf')).toBe(Infinity)
+    expect(parseAmicoNum('-Inf')).toBe(-Infinity)
+    expect(Number.isNaN(parseAmicoNum('NaN'))).toBe(true)
+    expect(parseAmicoNum('1.5e-3')).toBeCloseTo(0.0015)
+  })
 })