browser_execute: add harness zone map to tool description

Tells the agent up front: edit only under agent-workspace/ (those
edits persist), everything else gets overwritten on upgrade, and
previous trees are kept at <harness-archive>/<old-build>/ for
reference. One short paragraph; the description still defers all
workflow guidance to SKILL.md.

Templates {{HARNESS_ARCHIVE_DIR}} alongside {{HARNESS_DIR}}; both
substituted in the opencode adapter from BrowserExecute.make().

Author: Alezander9

packages/bcode-browser/src/browser-execute.ts

@@ -28,7 +28,7 @@ import os from "os"
 import path from "path"
 import { Effect, Schema, Stream } from "effect"
 import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process"
-import { resolveHarnessDir } from "./harness"
+import { harnessArchiveDir, resolveHarnessDir } from "./harness"
 import { uvLocate } from "./uv-locate"
 
 // Per-session persistent scratch under <dataDir>/sessions/<sid>/. Holds
@@ -157,7 +157,7 @@ export const make = Effect.fn("BrowserExecute.make")(function* (dataDir: string)
       }),
     )
 
-  return { parameters, execute, harnessDir }
+  return { parameters, execute, harnessDir, harnessArchiveDir: harnessArchiveDir(dataDir) }
 })
 
 export * as BrowserExecute from "./browser-execute"

packages/opencode/src/tool/browser-execute.ts

@@ -18,9 +18,11 @@ export const BrowserExecuteTool = Tool.define(
     const impl = yield* BrowserExecute.make(Global.Path.data)
     return {
       // Substitute the resolved harness path (dev: repo path; compiled:
-      // <dataDir>/harness/) so the SKILL.md / helpers.py references in the
-      // description point at files that actually exist on disk.
-      description: DESCRIPTION.replaceAll("{{HARNESS_DIR}}", impl.harnessDir),
+      // <dataDir>/harness/) and the archive path so the SKILL.md / helpers.py
+      // / archive references in the description point at concrete locations.
+      description: DESCRIPTION
+        .replaceAll("{{HARNESS_DIR}}", impl.harnessDir)
+        .replaceAll("{{HARNESS_ARCHIVE_DIR}}", impl.harnessArchiveDir),
       parameters: impl.parameters,
       execute: (args: Schema.Schema.Type<typeof impl.parameters>, ctx: Tool.Context) =>
         Effect.gen(function* () {

packages/opencode/src/tool/browser-execute.txt

@@ -4,4 +4,6 @@ Use this tool whenever the task requires driving a real browser — automation,
 
 Before the first `browser_execute` call of a session, you MUST read `{{HARNESS_DIR}}/SKILL.md`. It defines the helper surface, the screenshot-driven workflow, remote-browser setup, and gotchas — none of that is repeated here.
 
+Edits persist only under `{{HARNESS_DIR}}/agent-workspace/`. Everything else is overwritten on bcode upgrade; previous trees are kept at `{{HARNESS_ARCHIVE_DIR}}/<old-build>/` for migration reference.
+
 Optional: read `{{HARNESS_DIR}}/src/browser_harness/helpers.py` when you need an exact signature that SKILL.md does not show.