From e79f1694ceaaf0e367f13056e220d24b2baa9e6c Mon Sep 17 00:00:00 2001
From: Aaron Trowbridge <aaron.j.trowbridge@gmail.com>
Date: Thu, 24 Sep 2026 17:17:55 -0400
Subject: [PATCH 1/3] feat(app): the harness switcher in the chat box (#1549)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The composer gets a fourth select-slot — the harness — riding the
solver-mode trio end to end:

- engine: GET/POST /amicode/harness (server/amicode/harness.ts). The id
  allowlist IS the extension-published registry view
  (harness-options.json) — the engine never hardcodes harness identity;
  POST validates against it, no-ops when already current, and writes
  {harness, status:"switching"} to the ops dir (same loopback guard +
  fixed value-free refusals as the solver-mode flip).
- extension: harness_switch.ts (the handshake reader/writer + the
  watcher, the solver watcher's poll+busy-latch discipline) and the
  registry layer (harness.ts): harnessMenu — the ONE serialization both
  fronts render — and decideHarnessSwitch — the ONE gate both consult
  (unknown/needs-setup/unentitled blocked with their reason; the
  harness.telaio read-side gate lives here, never as a spawn-time
  failure). The palette command now renders from the same menu and gates
  through the same decision; the watcher persists the setting, republishes
  the menu, restarts, and settles ready — a refused switch settles ready
  at the STILL-CURRENT harness, never a lie.
- composer: the harness select (disabled-with-reason entries carrying the
  disclosure "switching harnesses switches session history" at the point
  of switching), harnessDegraded dimming of agent/model/variant under a
  non-opencode harness (Harness Contract v1 accepts none), and the
  harness switch banner narrating switching → restarting → ready.

Under opencode, byte-for-byte unchanged when untouched: no published
registry → the control renders nothing.
---
 packages/app-bundle/manifest.json             |  32 +++-
 .../src/components/harness-switch-banner.tsx  |  91 +++++++++
 .../app/src/components/harness-switch.test.ts |  44 +++++
 .../app/src/components/harness-switch.ts      |  48 +++++
 .../app/src/components/prompt-input-v2.tsx    |   9 +
 .../prompt-input/harness-control.tsx          | 125 ++++++++++++
 .../components/prompt-input/harness.test.ts   |  79 ++++++++
 .../src/components/prompt-input/harness.ts    |  80 ++++++++
 .../packages/app/src/pages/layout-new.tsx     |   5 +
 .../opencode/src/server/amicode/harness.ts    | 158 +++++++++++++++
 .../server/routes/instance/httpapi/server.ts  |  18 ++
 .../test/server/amicode-harness.test.ts       | 180 ++++++++++++++++++
 .../src/v2/components/prompt-input/index.tsx  |  81 +++++---
 packages/extension/src/extension.ts           | 153 ++++++++++++---
 packages/extension/src/harness.ts             |  93 +++++++++
 packages/extension/src/harness_switch.ts      |  96 ++++++++++
 packages/extension/test/harness.test.ts       | 120 +++++++++++-
 .../extension/test/harness_switch.test.ts     | 172 +++++++++++++++++
 18 files changed, 1518 insertions(+), 66 deletions(-)
 create mode 100644 packages/app-bundle/overlay/packages/app/src/components/harness-switch-banner.tsx
 create mode 100644 packages/app-bundle/overlay/packages/app/src/components/harness-switch.test.ts
 create mode 100644 packages/app-bundle/overlay/packages/app/src/components/harness-switch.ts
 create mode 100644 packages/app-bundle/overlay/packages/app/src/components/prompt-input/harness-control.tsx
 create mode 100644 packages/app-bundle/overlay/packages/app/src/components/prompt-input/harness.test.ts
 create mode 100644 packages/app-bundle/overlay/packages/app/src/components/prompt-input/harness.ts
 create mode 100644 packages/app-bundle/overlay/packages/opencode/src/server/amicode/harness.ts
 create mode 100644 packages/app-bundle/overlay/packages/opencode/test/server/amicode-harness.test.ts
 create mode 100644 packages/extension/src/harness_switch.ts
 create mode 100644 packages/extension/test/harness_switch.test.ts

diff --git a/packages/app-bundle/manifest.json b/packages/app-bundle/manifest.json
index 8e65c7f34..b26f2b0d9 100644
--- a/packages/app-bundle/manifest.json
+++ b/packages/app-bundle/manifest.json
@@ -111,11 +111,14 @@
     "packages/app/src/components/dialog-select-directory-v2.css": "2e2f18abdca77f9fe85da157c40f288f3b1641ca92845208749e16455fd58637",
     "packages/app/src/components/dialog-select-file.tsx": "e6278ee35dd27d203e00ad73f70c709c44a6c06f81ffbd931edfaa0c986b9e03",
     "packages/app/src/components/external-link.tsx": "7130044026ad3ec417de4ba7389cc6059de46f21b370047046269c772aa7a4bb",
+    "packages/app/src/components/harness-switch-banner.tsx": "aba66bdbcdeb0e674f07e7f22827b509a66fae2a2e5fbc8eb12e1d54baa311a0",
+    "packages/app/src/components/harness-switch.test.ts": "db263ece42911e756fb8b6e88697a6bbbd0d1317decd1e63b027d9fe8c69b405",
+    "packages/app/src/components/harness-switch.ts": "b4cb2b2241d71c477be71285fe6041d4b0d604a26d74c30dc5239694211a1f90",
     "packages/app/src/components/help-button.tsx": "780d533f776a784660cfed072a131198bc6fcc8e8fe332e8e1a220d516c9684e",
     "packages/app/src/components/pane-bridge.tsx": "756b3306b51c963fac6778716f6c6c4626f0f3bf75c93b7cb4cab58ea0bf3d4e",
     "packages/app/src/components/profile-popover.tsx": "eff742e90544455f13234a9351bb1b82189663cba2cd3172bdcea1a8a37284e8",
     "packages/app/src/components/prompt-input-clipboard-structure.test.ts": "946b718c2164da394602f26e4d9919d752da0d0b9bee714f345ba16c274542da",
-    "packages/app/src/components/prompt-input-v2.tsx": "5ab46e41bda4fa11e99f06c37df76c1fd3cce061c6ba7a9f85bee369a965b98a",
+    "packages/app/src/components/prompt-input-v2.tsx": "7f3677740abfd76c0884c824523ab5f385bab9377b345477794f04276d618f40",
     "packages/app/src/components/prompt-input.tsx": "97a9bc55b46cf1f2d7c3e38110e736f7fa9db7f89121d3c013b9650a60d382d4",
     "packages/app/src/components/prompt-project-selector.tsx": "0157c954b938bce2b5aca9a82f4a72338e361f4c9027e55a7fd5a14a1654d294",
     "packages/app/src/components/report-bug-button.css": "909809b6241d53c386aa4c8ea34539ba162a8998fff755834c783025bc53a5fd",
@@ -210,7 +213,7 @@
     "packages/app/src/pages/home-session-archive.test.ts": "e8f1126287a3e9daa455efcc378e5d72aebdd092158bf8526f7779669b72e850",
     "packages/app/src/pages/home-session-archive.ts": "1b56c173f37f4a4dfd54088ef5fdb0dbcd3d9b62aeb08de4bfa0ed34f07d7ad5",
     "packages/app/src/pages/home.tsx": "06fb5c7718aacfd29b35e730e05d45076b39d6cd5d936d1270fb1bd9424c32fa",
-    "packages/app/src/pages/layout-new.tsx": "3ef477634cb6d7de0c32d3572c5ff699e07efff47e6e75458583456eb1ff8b27",
+    "packages/app/src/pages/layout-new.tsx": "8e1c643a47182db5c2bb7b0f6248196ca71e38394c5fe02dbe7f133beab32171",
     "packages/app/src/pages/layout.tsx": "eaf8bed869b5ec53582db732119fb903b223d749ebda354b1e388de3be02dc52",
     "packages/app/src/pages/new-session-landing.test.ts": "95e2780456a653a71e6f66b4302ae546e308a29e6b8ad9e84442938a3a226905",
     "packages/app/src/pages/new-session-landing.ts": "528d27cd5d441b521674328fb7812fb2acf77233e9e436d081c98ce611e8b268",
@@ -332,6 +335,7 @@
     "packages/opencode/test/server/amicode-credentials.test.ts": "ba77d064fd2be799930524510ce6e32c6f6a0d144d3cdf41673a8283dbe95bf6",
     "packages/opencode/test/server/amicode-dashboard.test.ts": "e25b284b9eb434da7f07dfa8b72b7919a0cd1ffaed275a6725d9cd44cd1298c0",
     "packages/opencode/test/server/amicode-file-resolve.test.ts": "39db84780125c8fd4551137e4f6a0ea6b0a9dce45b04e26ed15f649efe251311",
+    "packages/opencode/test/server/amicode-harness.test.ts": "96cc4f3e07b80624eb286a405839ab7469ee5244987a0a33235fbc063914b1a2",
     "packages/opencode/test/server/amicode-library.test.ts": "87b986c43390e1f94d6bcded0bb5d22be24beaab2c336773bb438ed1fc6a2d95",
     "packages/opencode/test/server/amicode-problems.test.ts": "4a8a9011f3796df4d6cde9999b86b507a8126fdc9138cc3ba305f930968c3392",
     "packages/opencode/test/server/amicode-profile.test.ts": "5e5dcfd2b3db5cb8d7aba2cf1f74ed2d76716af6e4f761f54b94e77174b314de",
@@ -617,6 +621,9 @@
     "packages/app/src/components/prompt-input/clipboard-bridge.test.ts": "15f76dca1a25d024128718e4099220b79ca029263410aab55502cf9caf9b2914",
     "packages/app/src/components/prompt-input/clipboard-bridge.ts": "4b5a1edf59d4c85268d6ff72aa9f9d66f82d4fdb887121fb978c09caf4c5be65",
     "packages/app/src/components/prompt-input/context-items.tsx": "027b02e394ccd14849052bf3fcacdae1e090c71d164fa8955addfe3f7abf1758",
+    "packages/app/src/components/prompt-input/harness-control.tsx": "c2fb0a672498fe4809cf88ddb3b52c1d04ddcc3d3b710cf40acb6a1dab212f9d",
+    "packages/app/src/components/prompt-input/harness.test.ts": "35739529b06829dd9fa169209c54ae668e0fc06d6968b00cfce638a221ce1361",
+    "packages/app/src/components/prompt-input/harness.ts": "8ae6a783c18a906383061cb1254101015f025080b39be3786c27be9bcd0ba9d1",
     "packages/app/src/components/prompt-input/image-attachments.tsx": "aa451ed6aa61a68ba0e8dacd8c45137f84c62566797a5242b75a89487ef0e9bf",
     "packages/app/src/components/prompt-input/placeholder.test.ts": "d3cee5e2c758faf5fda626e270adad81129622bbc2bf2c335c2bffe1544165c3",
     "packages/app/src/components/prompt-input/placeholder.ts": "6b2af23a0588e7970cd0dd059fc60c3671c907a76ba3db660483a932f1dce79d",
@@ -717,6 +724,7 @@
     "packages/opencode/src/server/amicode/credentials.ts": "f3a15c82496f9a3b6e8c1006a6a4ab419a02156e9a93a43c6c2319632c30063f",
     "packages/opencode/src/server/amicode/dashboard.ts": "031a4f40bfdc847984a1deecfefbe0fd27f42cbd1caf8823dc43c7eb5bcb9af0",
     "packages/opencode/src/server/amicode/file-resolve.ts": "3f0548fc97aad431d3f7707fd0b911e66fb4fd68ac4f643da71a2f00a73beffe",
+    "packages/opencode/src/server/amicode/harness.ts": "510d2373c377395d509b84795da65005532a32c816b1fa5f7b76fb413be5ed95",
     "packages/opencode/src/server/amicode/library.ts": "36013b19f7c57afaa1bab63e5ff34d79f09ec42640e2a8c4a40cb14c97c4b859",
     "packages/opencode/src/server/amicode/pasqal-secret.ts": "a0b53498bb7415c96e14b435367ffa93bd3d298fe12f7584cd401e649312fd69",
     "packages/opencode/src/server/amicode/problems.ts": "d56513cff90193ab436dcca379f065a4ce963eeb45c22178cf9a0151b49c9487",
@@ -847,8 +855,8 @@
     "packages/sdk/js/src/v2/gen/sdk.gen.ts": "6610638b4fb71bac498da98d232ef9adcd4b011b63e5e81a63fc6dc20d311b17",
     "packages/sdk/js/src/v2/gen/types.gen.ts": "0c23b262085d1e14b89bd03292a380c9ec8b52e66c4308304a05173362b79339",
     "packages/session-ui/src/v2/components/prompt-input/attachments.ts": "ff66078f2edc9a67a4df0d7dfd76a49be5eab27ac332b303f3412721ef7268ea",
-    "packages/session-ui/src/v2/components/prompt-input/index.tsx": "194b1c6d0c99000579df78b47c7ff72fe34f62a92ecd21b2a9377133d6d27bb9",
-    "packages/opencode/src/server/routes/instance/httpapi/server.ts": "85c200797fed41c0cd08e7aa699ce13aeb8a3d23aa2b9eddc4d72e72b8b5082c",
+    "packages/session-ui/src/v2/components/prompt-input/index.tsx": "811ebe3d4f6ba6318d3bf3efbac678d4d0484f83929b8f8ae1b7af1bc29911f4",
+    "packages/opencode/src/server/routes/instance/httpapi/server.ts": "8a8e47c2242bc61be078c2fb97ecaa37ebe45cb410b95819102731b52f2b3c31",
     "packages/opencode/src/server/routes/instance/httpapi/groups/experimental.ts": "944a0aee215a917e867fd9482f3c2bd40f49082bd3174c8a7d967ca40e34ec15",
     "packages/opencode/src/server/routes/instance/httpapi/groups/file.ts": "ed165131c62eeb29375db39edf89db8f87488e24ef99fc6f2cf19705ba35751a",
     "packages/opencode/src/server/routes/instance/httpapi/groups/mcp.ts": "048efa7b74d43c4ad4a75d0f8421c808760c8c0dcd593f0051a87044e40487d6",
@@ -873,10 +881,10 @@
     "packages/ui/src/v2/components/text-shimmer-v2.tsx"
   ],
   "exceptions": [],
-  "extracted_at": "2026-09-24T04:46:38.771Z",
+  "extracted_at": "2026-09-24T21:16:08.091Z",
   "per_package": {
     "packages/app": {
-      "A": 186,
+      "A": 192,
       "M": 157,
       "D": 0
     },
@@ -891,7 +899,7 @@
       "D": 0
     },
     "packages/opencode": {
-      "A": 69,
+      "A": 71,
       "M": 81,
       "D": 0
     },
@@ -922,7 +930,7 @@
     }
   },
   "counts": {
-    "overlay_total": 851,
+    "overlay_total": 859,
     "deletions": 7,
     "server_coupled": 0
   },
@@ -1030,6 +1038,9 @@
     "packages/app/src/components/dialog-select-directory-v2.css": "M",
     "packages/app/src/components/dialog-select-file.tsx": "M",
     "packages/app/src/components/external-link.tsx": "M",
+    "packages/app/src/components/harness-switch-banner.tsx": "A",
+    "packages/app/src/components/harness-switch.test.ts": "A",
+    "packages/app/src/components/harness-switch.ts": "A",
     "packages/app/src/components/help-button.tsx": "M",
     "packages/app/src/components/pane-bridge.tsx": "A",
     "packages/app/src/components/profile-popover.tsx": "A",
@@ -1251,6 +1262,7 @@
     "packages/opencode/test/server/amicode-credentials.test.ts": "A",
     "packages/opencode/test/server/amicode-dashboard.test.ts": "A",
     "packages/opencode/test/server/amicode-file-resolve.test.ts": "A",
+    "packages/opencode/test/server/amicode-harness.test.ts": "A",
     "packages/opencode/test/server/amicode-library.test.ts": "A",
     "packages/opencode/test/server/amicode-problems.test.ts": "A",
     "packages/opencode/test/server/amicode-profile.test.ts": "A",
@@ -1536,6 +1548,9 @@
     "packages/app/src/components/prompt-input/clipboard-bridge.test.ts": "A",
     "packages/app/src/components/prompt-input/clipboard-bridge.ts": "A",
     "packages/app/src/components/prompt-input/context-items.tsx": "M",
+    "packages/app/src/components/prompt-input/harness-control.tsx": "A",
+    "packages/app/src/components/prompt-input/harness.test.ts": "A",
+    "packages/app/src/components/prompt-input/harness.ts": "A",
     "packages/app/src/components/prompt-input/image-attachments.tsx": "M",
     "packages/app/src/components/prompt-input/placeholder.test.ts": "M",
     "packages/app/src/components/prompt-input/placeholder.ts": "M",
@@ -1636,6 +1651,7 @@
     "packages/opencode/src/server/amicode/credentials.ts": "A",
     "packages/opencode/src/server/amicode/dashboard.ts": "A",
     "packages/opencode/src/server/amicode/file-resolve.ts": "A",
+    "packages/opencode/src/server/amicode/harness.ts": "A",
     "packages/opencode/src/server/amicode/library.ts": "A",
     "packages/opencode/src/server/amicode/pasqal-secret.ts": "A",
     "packages/opencode/src/server/amicode/problems.ts": "A",
diff --git a/packages/app-bundle/overlay/packages/app/src/components/harness-switch-banner.tsx b/packages/app-bundle/overlay/packages/app/src/components/harness-switch-banner.tsx
new file mode 100644
index 000000000..f9e419f84
--- /dev/null
+++ b/packages/app-bundle/overlay/packages/app/src/components/harness-switch-banner.tsx
@@ -0,0 +1,91 @@
+import { Show, createEffect, createSignal, onCleanup } from "solid-js"
+import {
+  harnessSwitchExpired,
+  harnessSwitchLabel,
+  harnessSwitchPhase,
+  type HarnessSwitchPhase,
+} from "@/components/harness-switch"
+import { useServerSDK } from "@/context/server-sdk"
+
+// Amicode: the visible half of a harness switch (amicode#1549) — the
+// solver-switch banner's twin for the composer's harness control. The switch
+// is real: the extension watcher persists the setting and restarts the server
+// underneath the webview; the SSE stream dies for those seconds and this
+// banner is the only narration. Scope mirrors the solver twin: it speaks ONLY
+// for a switch the app itself requested, so it cannot get stuck on a
+// transient blip.
+
+// Module-level: the call site (the composer's harness control) and the one
+// banner in the layout live in different component trees.
+const [target, setTarget] = createSignal<string | undefined>()
+const [startedAt, setStartedAt] = createSignal(0)
+
+/** Announce a switch the app just requested — `displayName` is the registry's
+ *  name for the picked harness, so the narration names what was picked. This
+ *  only mirrors the request; it never causes one. */
+export function beginHarnessSwitch(displayName: string) {
+  setTarget(displayName)
+  setStartedAt(Date.now())
+}
+
+function endHarnessSwitch() {
+  setTarget(undefined)
+  setStartedAt(0)
+}
+
+export function HarnessSwitchBanner() {
+  const sdk = useServerSDK()
+  const [sawDrop, setSawDrop] = createSignal(false)
+  const [elapsed, setElapsed] = createSignal(0)
+
+  // One clock, alive only while a switch is outstanding: it drives the expiry
+  // check, which has nothing else to react to.
+  createEffect(() => {
+    if (!target()) {
+      setSawDrop(false)
+      setElapsed(0)
+      return
+    }
+    const timer = setInterval(() => setElapsed(Date.now() - startedAt()), 500)
+    onCleanup(() => clearInterval(timer))
+  })
+
+  // Latch the drop: once the server has gone down, coming back up is the
+  // switch completing rather than the request still waiting to be picked up.
+  createEffect(() => {
+    if (target() && sdk().event.status() === "disconnected") setSawDrop(true)
+  })
+
+  const phase = (): HarnessSwitchPhase =>
+    harnessSwitchPhase({
+      target: target(),
+      connected: sdk().event.status() === "connected",
+      sawDrop: sawDrop(),
+    })
+
+  createEffect(() => {
+    const current = phase()
+    if (current === "idle") return
+    // Hold the completed chip briefly — the only confirmation the user gets
+    // inside the app; the extension's toast lands outside the webview.
+    if (current === "ready") {
+      const done = setTimeout(endHarnessSwitch, 3000)
+      onCleanup(() => clearTimeout(done))
+      return
+    }
+    if (harnessSwitchExpired(current, elapsed())) endHarnessSwitch()
+  })
+
+  const label = () => harnessSwitchLabel(phase(), target())
+
+  return (
+    <Show when={label()}>
+      {(text) => (
+        <div data-component="amicode-harness-switch" data-phase={phase()} role="status" aria-live="polite">
+          <i aria-hidden="true" />
+          <span>{text()}</span>
+        </div>
+      )}
+    </Show>
+  )
+}
diff --git a/packages/app-bundle/overlay/packages/app/src/components/harness-switch.test.ts b/packages/app-bundle/overlay/packages/app/src/components/harness-switch.test.ts
new file mode 100644
index 000000000..1bb12591e
--- /dev/null
+++ b/packages/app-bundle/overlay/packages/app/src/components/harness-switch.test.ts
@@ -0,0 +1,44 @@
+import { describe, expect, test } from "bun:test"
+import {
+  harnessSwitchPhase,
+  harnessSwitchExpired,
+  harnessSwitchLabel,
+  HARNESS_SWITCH_STALL_MS,
+  HARNESS_SWITCH_MAX_MS,
+} from "./harness-switch"
+
+// amicode#1549 — the harness banner's decision layer, the solver-switch
+// twin's shape: pure helpers over two observable facts (a switch outstanding,
+// has the stream dropped), so the phase contract is testable without a DOM.
+
+describe("harnessSwitchPhase", () => {
+  test("no target → idle", () => {
+    expect(harnessSwitchPhase({ target: undefined, connected: true, sawDrop: false })).toBe("idle")
+  })
+
+  test("requested until the stream drops, restarting while down, ready on return", () => {
+    expect(harnessSwitchPhase({ target: "telaio", connected: true, sawDrop: false })).toBe("requested")
+    expect(harnessSwitchPhase({ target: "telaio", connected: false, sawDrop: false })).toBe("restarting")
+    expect(harnessSwitchPhase({ target: "telaio", connected: true, sawDrop: true })).toBe("ready")
+  })
+})
+
+describe("harnessSwitchExpired — never trap the user behind theater", () => {
+  test("requested stalls past the stall window; restarting past the ceiling", () => {
+    expect(harnessSwitchExpired("requested", HARNESS_SWITCH_STALL_MS + 1)).toBe(true)
+    expect(harnessSwitchExpired("requested", HARNESS_SWITCH_STALL_MS - 1)).toBe(false)
+    expect(harnessSwitchExpired("restarting", HARNESS_SWITCH_MAX_MS + 1)).toBe(true)
+    expect(harnessSwitchExpired("restarting", HARNESS_SWITCH_MAX_MS - 1)).toBe(false)
+    expect(harnessSwitchExpired("ready", Number.MAX_SAFE_INTEGER)).toBe(false)
+  })
+})
+
+describe("harnessSwitchLabel — honest narration, one name end to end", () => {
+  test("the labels narrate switching → restarting → ready", () => {
+    expect(harnessSwitchLabel("requested", "telaio (subscription)")).toBe("Switching to telaio (subscription)…")
+    expect(harnessSwitchLabel("restarting", "telaio (subscription)")).toBe("Restarting session server…")
+    expect(harnessSwitchLabel("ready", "telaio (subscription)")).toBe("telaio (subscription) ready")
+    expect(harnessSwitchLabel("idle", "telaio (subscription)")).toBeUndefined()
+    expect(harnessSwitchLabel("requested", undefined)).toBeUndefined()
+  })
+})
diff --git a/packages/app-bundle/overlay/packages/app/src/components/harness-switch.ts b/packages/app-bundle/overlay/packages/app/src/components/harness-switch.ts
new file mode 100644
index 000000000..6006cb03e
--- /dev/null
+++ b/packages/app-bundle/overlay/packages/app/src/components/harness-switch.ts
@@ -0,0 +1,48 @@
+// amicode#1549 — the harness banner's decision layer, the solver-switch twin
+// (solver-switch.ts) in shape and discipline: a switch is not instant and it
+// is not quiet — the extension watcher sees {status:"switching"}, performs
+// the registry-gated setting persist, and RESTARTS the server underneath the
+// webview. For those seconds the SSE stream is simply gone; without a signal
+// that reads as an upgrade, the drop reads as a fault. Like the solver twin,
+// this speaks ONLY for a switch the app itself requested.
+//
+// Pure helpers so the phase contract is testable without a DOM.
+
+export type HarnessSwitchPhase = "idle" | "requested" | "restarting" | "ready"
+
+/** Phase from the two observable facts: is a switch outstanding, and has the
+ *  stream dropped yet. `sawDrop` is latched by the caller — once the server
+ *  has gone down, coming back up means "ready", not "still waiting to start". */
+export function harnessSwitchPhase(input: {
+  target: string | undefined
+  connected: boolean
+  sawDrop: boolean
+}): HarnessSwitchPhase {
+  if (!input.target) return "idle"
+  if (!input.connected) return "restarting"
+  return input.sawDrop ? "ready" : "requested"
+}
+
+/** The watcher polls harness.json every 1s, so a request that has not taken
+ *  the server down well inside this window is not going to — abandon quietly
+ *  rather than leave a permanent pill on screen (the solver twin's discipline). */
+export const HARNESS_SWITCH_STALL_MS = 12_000
+/** Total ceiling: never trap the user behind theater, however wedged the
+ *  restart is. */
+export const HARNESS_SWITCH_MAX_MS = 90_000
+
+export function harnessSwitchExpired(phase: HarnessSwitchPhase, elapsedMs: number): boolean {
+  if (phase === "requested") return elapsedMs > HARNESS_SWITCH_STALL_MS
+  if (phase === "restarting") return elapsedMs > HARNESS_SWITCH_MAX_MS
+  return false
+}
+
+/** One name end to end — the banner narrates the displayName the registry
+ *  published, so the banner and the select never disagree about what the user
+ *  just picked. */
+export function harnessSwitchLabel(phase: HarnessSwitchPhase, target: string | undefined): string | undefined {
+  if (!target || phase === "idle") return undefined
+  if (phase === "requested") return `Switching to ${target}…`
+  if (phase === "restarting") return "Restarting session server…"
+  return `${target} ready`
+}
diff --git a/packages/app-bundle/overlay/packages/app/src/components/prompt-input-v2.tsx b/packages/app-bundle/overlay/packages/app/src/components/prompt-input-v2.tsx
index ad9cc7ecb..d97434a56 100644
--- a/packages/app-bundle/overlay/packages/app/src/components/prompt-input-v2.tsx
+++ b/packages/app-bundle/overlay/packages/app/src/components/prompt-input-v2.tsx
@@ -38,6 +38,8 @@ import {
   createPromptInputV2State,
   type PromptInputV2Interaction,
 } from "@opencode-ai/session-ui/v2/prompt-input/interaction"
+import { HarnessComposerControl } from "@/components/prompt-input/harness-control"
+import { harnessDegraded, liveHarnessState } from "@/components/prompt-input/harness"
 
 export type PromptInputV2ComposerProps = {
   class?: string
@@ -64,6 +66,13 @@ export function PromptInputV2Composer(props: PromptInputV2ComposerProps) {
         variantControlVisible={!props.controller.model.loading}
         attachKeybind={command.keybindParts("file.attach")}
         attachShortcut={command.keybind("file.attach")}
+        // amicode#1549: the harness switcher — a fourth select-slot riding the
+        // solver-mode trio. The control self-hides when no registry is
+        // published (stock-opencode behavior, unchanged); the degradation dim
+        // follows the serving harness's contract (telaio accepts no
+        // agent/model/variant).
+        harnessControl={<HarnessComposerControl />}
+        harnessDegraded={harnessDegraded(liveHarnessState())}
         // amicode/opencode#116: report-a-bug, right-anchored immediately left
         // of send. The boot-param gate lives HERE (not inside the button) so a
         // gated-off button passes `undefined` and the row's layout never shifts.
diff --git a/packages/app-bundle/overlay/packages/app/src/components/prompt-input/harness-control.tsx b/packages/app-bundle/overlay/packages/app/src/components/prompt-input/harness-control.tsx
new file mode 100644
index 000000000..bb1f39e6a
--- /dev/null
+++ b/packages/app-bundle/overlay/packages/app/src/components/prompt-input/harness-control.tsx
@@ -0,0 +1,125 @@
+import { For, Show, createEffect } from "solid-js"
+import { MenuV2 } from "@opencode-ai/ui/v2/menu-v2"
+import { ButtonV2 } from "@opencode-ai/ui/v2/button-v2"
+import { Icon as IconV2 } from "@opencode-ai/ui/v2/icon"
+import { TooltipV2 } from "@opencode-ai/ui/v2/tooltip-v2"
+import { useServer } from "@/context/server"
+import { useServerSDK } from "@/context/server-sdk"
+import { amicodeGet, amicodePost } from "@/utils/amicode-fetch"
+import { showToast } from "@/utils/toast"
+import { adoptHarnessState, liveHarnessState, parseHarnessState } from "@/components/prompt-input/harness"
+import { beginHarnessSwitch } from "@/components/harness-switch-banner"
+
+// amicode#1549 — the harness switcher in the chat box. A fourth composer
+// select-slot riding the solver-mode trio: the state comes from the engine's
+// GET /amicode/harness (the extension-published registry view — ONE registry,
+// the same serialization the palette command renders); the write path is
+// POST /amicode/harness, whose switching file the extension watcher performs.
+// An unresolvable or unentitled harness renders disabled WITH its reason —
+// never selectable-then-failing. No published registry (stock opencode, or
+// the extension not yet booted) renders nothing at all.
+
+/** The palette's disclosure, carried verbatim to the point of switching. */
+const DISCLOSURE = "Sessions are harness-local — switching harnesses switches session history."
+
+async function refreshHarnessState(server: ReturnType<typeof useServer>): Promise<void> {
+  try {
+    adoptHarnessState(parseHarnessState(await amicodeGet(server.current, "/amicode/harness")))
+  } catch {
+    // No answer (no extension yet, route absent) → the control stays hidden.
+    adoptHarnessState(undefined)
+  }
+}
+
+export function HarnessComposerControl() {
+  const server = useServer()
+  const sdk = useServerSDK()
+
+  // Refetch on server change and on every (re)connect — a harness switch
+  // restarts the server, so the post-restart reconnect is when the new
+  // current lands here.
+  createEffect(() => {
+    if (server.current) void refreshHarnessState(server)
+  })
+  createEffect(() => {
+    if (sdk().event.status() === "connected") void refreshHarnessState(server)
+  })
+
+  const onPick = async (id: string) => {
+    const state = liveHarnessState()
+    if (!state || id === state.harness) return
+    const conn = server.current
+    if (!conn) return
+    try {
+      const res = (await amicodePost(conn, "/amicode/harness", { harness: id })) as {
+        ok?: unknown
+        noop?: unknown
+        harness?: unknown
+        error?: unknown
+      }
+      if (res.ok !== true || typeof res.harness !== "string") {
+        showToast({
+          variant: "error",
+          title: "Amicode: harness switch failed",
+          description: typeof res.error === "string" ? res.error : "The switch could not be requested.",
+        })
+        return
+      }
+      if (res.noop === true) return
+      // Narrate the restart this is about to trigger — the extension watcher
+      // is the durable half; the banner carries the webview through the gap.
+      const picked = state.options.find((option) => option.id === res.harness)
+      beginHarnessSwitch(picked?.displayName ?? res.harness)
+    } catch (e) {
+      showToast({
+        variant: "error",
+        title: "Amicode: harness switch failed",
+        description: e instanceof Error ? e.message : String(e),
+      })
+    }
+  }
+
+  return (
+    <Show when={liveHarnessState()}>
+      {(state) => (
+        <TooltipV2 placement="top" gutter={4} value="Choose harness">
+          <MenuV2 gutter={6} modal={false} placement="top-start">
+            <MenuV2.Trigger
+              as={ButtonV2}
+              variant="ghost-muted"
+              size="normal"
+              class="max-w-[220px] justify-start ![font-weight:440]"
+              aria-label="Choose harness"
+              data-action="prompt-harness"
+            >
+              <span class="truncate leading-5">
+                {state().options.find((option) => option.id === state().harness)?.displayName ?? state().harness}
+              </span>
+              <span class="-ml-0.5 -mr-1 flex shrink-0">
+                <IconV2 name="chevron-down" />
+              </span>
+            </MenuV2.Trigger>
+            <MenuV2.Portal>
+              <MenuV2.Content>
+                <MenuV2.RadioGroup value={state().harness} onChange={(id: string) => void onPick(id)}>
+                  <For each={state().options}>
+                    {(option) => (
+                      <MenuV2.RadioItem value={option.id} disabled={option.disabled} closeOnSelect>
+                        <div class="flex flex-col items-start gap-0.5 py-0.5">
+                          <span class="leading-5">{option.displayName}</span>
+                          <span class="max-w-[280px] text-[11px] leading-4 whitespace-normal text-v2-text-text-faint">
+                            {option.disabled ? (option.reason ?? "Unavailable") : DISCLOSURE}
+                          </span>
+                        </div>
+                      </MenuV2.RadioItem>
+                    )}
+                  </For>
+                </MenuV2.RadioGroup>
+              </MenuV2.Content>
+            </MenuV2.Portal>
+          </MenuV2>
+        </TooltipV2>
+      )}
+    </Show>
+  )
+}
diff --git a/packages/app-bundle/overlay/packages/app/src/components/prompt-input/harness.test.ts b/packages/app-bundle/overlay/packages/app/src/components/prompt-input/harness.test.ts
new file mode 100644
index 000000000..7829530f5
--- /dev/null
+++ b/packages/app-bundle/overlay/packages/app/src/components/prompt-input/harness.test.ts
@@ -0,0 +1,79 @@
+import { describe, expect, test } from "bun:test"
+import { parseHarnessState, harnessDegraded, type HarnessViewState } from "./harness"
+
+// amicode#1549 — the composer's harness state is whatever the engine's
+// GET /amicode/harness answers, parsed tolerantly: a response without a
+// published registry view means "no control" (stock-opencode behavior,
+// unchanged); a view with a non-opencode current means the serving harness's
+// contract dims agent/model/variant.
+
+const READY_MENU = {
+  ok: true,
+  harness: "opencode",
+  status: "ready",
+  options: [
+    { id: "opencode", displayName: "opencode (default)", state: "ready", detail: "The default harness.", disabled: false },
+    {
+      id: "telaio",
+      displayName: "telaio (subscription)",
+      state: "ready",
+      detail: "Serves the Harness Contract v1 API.",
+      disabled: false,
+    },
+  ],
+}
+
+describe("parseHarnessState — tolerant, hide-when-unpublished", () => {
+  test("a published view parses fully", () => {
+    const parsed = parseHarnessState(READY_MENU)
+    expect(parsed?.harness).toBe("opencode")
+    expect(parsed?.status).toBe("ready")
+    expect(parsed?.options).toHaveLength(2)
+    expect(parsed?.options[1]?.id).toBe("telaio")
+  })
+
+  test("no options (or an empty/invalid list) → undefined: the control stays hidden", () => {
+    expect(parseHarnessState({ ok: true, harness: "opencode", status: "ready" })).toBeUndefined()
+    expect(parseHarnessState({ ok: true, harness: "opencode", status: "ready", options: [] })).toBeUndefined()
+    expect(parseHarnessState({ ok: true, harness: "opencode", options: ["junk"] })).toBeUndefined()
+  })
+
+  test("off-shape responses collapse to undefined, never a throw", () => {
+    expect(parseHarnessState(undefined)).toBeUndefined()
+    expect(parseHarnessState("nope")).toBeUndefined()
+    expect(parseHarnessState({ ok: false, harness: "opencode", options: READY_MENU.options })).toBeUndefined()
+    expect(parseHarnessState({ ok: true, options: READY_MENU.options })).toBeUndefined()
+  })
+
+  test("option entries missing required fields are dropped, not repaired", () => {
+    const parsed = parseHarnessState({
+      ok: true,
+      harness: "telaio",
+      status: "ready",
+      options: [{ id: "telaio" }, READY_MENU.options[1]],
+    })
+    expect(parsed?.options.map((o) => o.id)).toEqual(["telaio"])
+  })
+
+  test("a reason rides the option when present", () => {
+    const parsed = parseHarnessState({
+      ok: true,
+      harness: "opencode",
+      status: "ready",
+      options: [{ ...READY_MENU.options[1], disabled: true, reason: "Requires the `harness.telaio` entitlement." }],
+    })
+    expect(parsed?.options[0]?.reason).toContain("harness.telaio")
+  })
+})
+
+describe("harnessDegraded — the honest dim under a non-opencode harness", () => {
+  test("opencode (or no state) never degrades — today's behavior, unchanged", () => {
+    expect(harnessDegraded(undefined)).toBe(false)
+    expect(harnessDegraded(parseHarnessState(READY_MENU))).toBe(false)
+  })
+
+  test("a telaio current degrades the agent/model/variant slots", () => {
+    const state = parseHarnessState({ ...READY_MENU, harness: "telaio" }) as HarnessViewState
+    expect(harnessDegraded(state)).toBe(true)
+  })
+})
diff --git a/packages/app-bundle/overlay/packages/app/src/components/prompt-input/harness.ts b/packages/app-bundle/overlay/packages/app/src/components/prompt-input/harness.ts
new file mode 100644
index 000000000..2c41e8251
--- /dev/null
+++ b/packages/app-bundle/overlay/packages/app/src/components/prompt-input/harness.ts
@@ -0,0 +1,80 @@
+// amicode#1549 — the composer's harness state. The engine's
+// GET /amicode/harness answers {ok, harness, status, options?} where
+// `options` is the extension-published registry view (harness-options.json —
+// the registry lives in the extension; this side only parses it). A response
+// WITHOUT a published view means "no harness control" — stock-opencode
+// behavior, unchanged. Pure helpers so the view contract is testable without
+// a DOM (the solver-toggle decision-helper split).
+import { createSignal } from "solid-js"
+
+export interface HarnessOptionView {
+  id: string
+  displayName: string
+  state: "ready" | "needs-setup"
+  detail: string
+  disabled: boolean
+  reason?: string
+}
+
+export interface HarnessViewState {
+  harness: string
+  status: "ready" | "switching"
+  options: HarnessOptionView[]
+}
+
+/** Tolerant parse: anything off-shape, or a response with no usable registry
+ *  view, parses to undefined — the caller hides the control. Option entries
+ *  missing required fields are dropped, not repaired. */
+export function parseHarnessState(raw: unknown): HarnessViewState | undefined {
+  if (typeof raw !== "object" || raw === null) return undefined
+  const body = raw as Record<string, unknown>
+  if (body.ok !== true || typeof body.harness !== "string") return undefined
+  if (!Array.isArray(body.options) || body.options.length === 0) return undefined
+  const options: HarnessOptionView[] = []
+  for (const entry of body.options) {
+    if (typeof entry !== "object" || entry === null) continue
+    const o = entry as Record<string, unknown>
+    if (typeof o.id !== "string" || o.id === "") continue
+    if (typeof o.displayName !== "string") continue
+    if (o.state !== "ready" && o.state !== "needs-setup") continue
+    if (typeof o.disabled !== "boolean") continue
+    options.push({
+      id: o.id,
+      displayName: o.displayName,
+      state: o.state,
+      detail: typeof o.detail === "string" ? o.detail : "",
+      disabled: o.disabled,
+      ...(typeof o.reason === "string" ? { reason: o.reason } : {}),
+    })
+  }
+  if (options.length === 0) return undefined
+  return {
+    harness: body.harness,
+    status: body.status === "switching" ? "switching" : "ready",
+    options,
+  }
+}
+
+/** The degradation contract (ADR-0011 Harness Contract v1): telaio accepts no
+ *  agent/model/variant on session-create or prompt, so those slots dim with
+ *  an honest affordance. opencode — or no harness state at all — never
+ *  degrades. */
+export function harnessDegraded(state: HarnessViewState | undefined): boolean {
+  return state !== undefined && state.harness !== "opencode"
+}
+
+// Module-level singleton: the composer's harness state is app-lifetime and
+// one-per-server (the same shape the solver banner's module signals use). The
+// control component refetches on server changes and reconnects.
+const [harnessState, setHarnessState] = createSignal<HarnessViewState | undefined>(undefined)
+
+/** Adopt a parsed GET response (or undefined to hide the control). */
+export function adoptHarnessState(state: HarnessViewState | undefined): void {
+  setHarnessState(state)
+}
+
+/** The live harness state — undefined before the first fetch or when no
+ *  registry is published (control hidden). */
+export function liveHarnessState(): HarnessViewState | undefined {
+  return harnessState()
+}
diff --git a/packages/app-bundle/overlay/packages/app/src/pages/layout-new.tsx b/packages/app-bundle/overlay/packages/app/src/pages/layout-new.tsx
index 7fc2541a8..4125e0e93 100644
--- a/packages/app-bundle/overlay/packages/app/src/pages/layout-new.tsx
+++ b/packages/app-bundle/overlay/packages/app/src/pages/layout-new.tsx
@@ -3,6 +3,7 @@ import { createStore } from "solid-js/store"
 import { TabsInfoPopup } from "@/components/help-button"
 import { Titlebar, type TitlebarUpdate } from "@/components/titlebar"
 import { SolverSwitchBanner } from "@/components/solver-switch-banner"
+import { HarnessSwitchBanner } from "@/components/harness-switch-banner"
 import { VaultPanel } from "@/components/vault-panel"
 import { usePlatform } from "@/context/platform"
 import { setV2Toast, ToastRegion } from "@/utils/toast"
@@ -55,6 +56,10 @@ export default function NewLayout(props: ParentProps) {
           under the webview. Speaks only for switches the app requested — unlike
           the removed ConnectionBanner, silence is still the default. */}
       <SolverSwitchBanner />
+      {/* amicode#1549: a harness switch restarts the server under the webview
+          too — the composer's harness control narrates through the gap. Same
+          discipline: speaks only for switches the app requested. */}
+      <HarnessSwitchBanner />
       {/* DebugBar removed with the fork's debug-bar deletion (kept during the
           upstream merge) — the debugTools toggle state stays for the titlebar's
           channel indicator. */}
diff --git a/packages/app-bundle/overlay/packages/opencode/src/server/amicode/harness.ts b/packages/app-bundle/overlay/packages/opencode/src/server/amicode/harness.ts
new file mode 100644
index 000000000..e184dccee
--- /dev/null
+++ b/packages/app-bundle/overlay/packages/opencode/src/server/amicode/harness.ts
@@ -0,0 +1,158 @@
+// AMICODE: harness switch routes (#1549) — the engine half of the
+// harness.json contract. The app's composer control POSTs {harness} here;
+// this route validates the id against the EXTENSION-published registry view
+// (harness-options.json — the registry lives in the extension, this side
+// never computes it) and writes {harness, status:"switching"} to the ops
+// dir. The amicode extension's watcher (packages/extension/src/
+// harness_switch.ts) consumes the request and performs the real switch —
+// the setting persist and the server restart — settling status:"ready".
+// Sibling of the solver-mode flip in connections.ts: same loopback guard,
+// same fixed value-free refusals, same atomic switching write.
+import { readFileSync } from "node:fs"
+import path from "node:path"
+import { atomicWriteFileSync } from "./credentials"
+import { amicodeOpsDir, isLoopbackHostname, getBindHostname } from "./connections"
+
+/** ops-dir override → ~/.amico/amicode — the SAME resolution the extension's
+ *  watcher reads (substrate/vault_store.ts amicodeOpsDir), so the watcher
+ *  reads exactly where this route writes and tests stay hermetic. */
+export function harnessFile(): string {
+  return path.join(amicodeOpsDir(), "harness.json")
+}
+
+export function harnessOptionsFile(): string {
+  return path.join(amicodeOpsDir(), "harness-options.json")
+}
+
+export interface HarnessOptionView {
+  id: string
+  displayName: string
+  state: "ready" | "needs-setup"
+  detail: string
+  disabled: boolean
+  reason?: string
+}
+
+export interface HarnessOptionsView {
+  current: string
+  options: HarnessOptionView[]
+}
+
+/** Tolerant {harness, status} read — the solver-mode reader's semantics:
+ *  anything absent/off-shape collapses to opencode/ready. */
+export function readHarnessState(file: string = harnessFile()): { harness: string; status: "ready" | "switching" } {
+  try {
+    const parsed = JSON.parse(readFileSync(file, "utf8")) as { harness?: unknown; status?: unknown }
+    return {
+      harness: typeof parsed.harness === "string" && parsed.harness !== "" ? parsed.harness : "opencode",
+      status: parsed.status === "switching" ? "switching" : "ready",
+    }
+  } catch {
+    return { harness: "opencode", status: "ready" }
+  }
+}
+
+/** Tolerant registry-view read — undefined when the extension hasn't
+ *  published one (standalone opencode, extension not yet booted). Entries
+ *  missing required fields are dropped, not repaired. */
+export function readHarnessOptions(file: string = harnessOptionsFile()): HarnessOptionsView | undefined {
+  try {
+    const parsed = JSON.parse(readFileSync(file, "utf8")) as { current?: unknown; options?: unknown }
+    if (!Array.isArray(parsed.options)) return undefined
+    const options: HarnessOptionView[] = []
+    for (const raw of parsed.options) {
+      if (typeof raw !== "object" || raw === null) continue
+      const entry = raw as Record<string, unknown>
+      if (typeof entry.id !== "string" || entry.id === "") continue
+      if (typeof entry.displayName !== "string") continue
+      if (entry.state !== "ready" && entry.state !== "needs-setup") continue
+      if (typeof entry.disabled !== "boolean") continue
+      options.push({
+        id: entry.id,
+        displayName: entry.displayName,
+        state: entry.state,
+        detail: typeof entry.detail === "string" ? entry.detail : "",
+        disabled: entry.disabled,
+        ...(typeof entry.reason === "string" ? { reason: entry.reason } : {}),
+      })
+    }
+    if (options.length === 0) return undefined
+    return {
+      current: typeof parsed.current === "string" && parsed.current !== "" ? parsed.current : "opencode",
+      options,
+    }
+  } catch {
+    return undefined
+  }
+}
+
+// --- mutation body (POST). Sibling discipline with the connection routes:
+// never reject, ok:false + "code: detail" on failure, every failure message a
+// FIXED string — nothing the caller sent is ever echoed.
+
+export function synthesizeHarness(code: string, detail: string): string {
+  return JSON.stringify({ ok: false, harness: null, error: `${code}: ${detail}` })
+}
+
+const MAX_BODY_BYTES = 16 * 1024
+
+/** The FIXED partial-failure warning (sibling "code: detail" shape). */
+export const HARNESS_SWITCH_WARNING = "harness_switch_failed: the harness switch could not be requested"
+
+/** GET /amicode/harness — the current harness + the published registry view.
+ *  `current` prefers the extension's setting-backed view; the handshake
+ *  file's harness only speaks when no view exists yet. A response without
+ *  `options` means "no registry published" — the composer control stays
+ *  hidden (stock-opencode behavior, unchanged). */
+export function harnessStateResponse(): string {
+  const options = readHarnessOptions()
+  const state = readHarnessState()
+  const harness = options?.current ?? state.harness
+  return JSON.stringify({
+    ok: true,
+    harness,
+    status: state.status,
+    ...(options !== undefined ? { options: options.options } : {}),
+  })
+}
+
+/** POST /amicode/harness — body {harness}. Validates against the published
+ *  registry view, no-ops when the harness is already current (the watcher is
+ *  never poked for nothing), and otherwise writes the switching request the
+ *  extension watcher performs. NEVER throws. */
+export function harnessResponse(rawBody: string): string {
+  const bind = getBindHostname()
+  if (!isLoopbackHostname(bind)) return synthesizeHarness("non_loopback", "harness mutations serve loopback binds only")
+  let parsed: unknown
+  try {
+    if (rawBody.length > MAX_BODY_BYTES) return synthesizeHarness("bad_request", "body must be JSON {harness}")
+    parsed = JSON.parse(rawBody)
+  } catch {
+    return synthesizeHarness("bad_request", "body must be JSON {harness}")
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return synthesizeHarness("bad_request", "body must be JSON {harness}")
+  }
+  const requested = (parsed as { harness?: unknown }).harness
+  if (typeof requested !== "string" || requested === "") {
+    return synthesizeHarness("bad_request", "body must be JSON {harness}")
+  }
+  // The registry view IS the id allowlist: the engine never hardcodes
+  // harness identity (the wire-protocol rule) — the extension publishes it.
+  const options = readHarnessOptions()
+  if (options === undefined) {
+    return synthesizeHarness("registry_unavailable", "no harness registry is published — is the Amicode extension running?")
+  }
+  if (!options.options.some((o) => o.id === requested)) {
+    return synthesizeHarness("unsupported_harness", "the requested harness is not in the published registry")
+  }
+  if (requested === options.current) {
+    return JSON.stringify({ ok: true, harness: requested, noop: true, error: null })
+  }
+  try {
+    atomicWriteFileSync(harnessFile(), JSON.stringify({ harness: requested, status: "switching" }))
+  } catch {
+    return JSON.stringify({ ok: false, harness: null, error: HARNESS_SWITCH_WARNING })
+  }
+  return JSON.stringify({ ok: true, harness: requested, noop: false, error: null })
+}
diff --git a/packages/app-bundle/overlay/packages/opencode/src/server/routes/instance/httpapi/server.ts b/packages/app-bundle/overlay/packages/opencode/src/server/routes/instance/httpapi/server.ts
index 57278e498..435c36012 100644
--- a/packages/app-bundle/overlay/packages/opencode/src/server/routes/instance/httpapi/server.ts
+++ b/packages/app-bundle/overlay/packages/opencode/src/server/routes/instance/httpapi/server.ts
@@ -80,6 +80,7 @@ import * as AmicodeWidgetFrame from "@/server/amicode/widget-frame-html"
 import * as AmicodeLibrary from "@/server/amicode/library"
 import * as AmicodeProfile from "@/server/amicode/profile"
 import * as AmicodeConnections from "@/server/amicode/connections"
+import * as AmicodeHarness from "@/server/amicode/harness"
 import * as AmicodeProject from "@/server/amicode/project"
 import { ServerAuth } from "@/server/auth"
 import { InstanceHttpApi, RootHttpApi } from "./api"
@@ -516,6 +517,23 @@ const amicodeConnectionsRoute = HttpRouter.use((router) =>
         })
       }),
     )
+    // amicode#1549: the harness switcher — the composer control's write path.
+    // Same trio shape as solver-mode: POST writes {harness, status:"switching"}
+    // to the ops dir; the amicode extension's watcher performs the real switch
+    // (registry gate → setting persist → server restart) and settles ready.
+    yield* router.add("GET", "/amicode/harness", () =>
+      Effect.sync(() =>
+        HttpServerResponse.text(AmicodeHarness.harnessStateResponse(), { contentType: "application/json" }),
+      ),
+    )
+    yield* router.add("POST", "/amicode/harness", (request) =>
+      Effect.gen(function* () {
+        const body = yield* Effect.orDie(request.text)
+        return HttpServerResponse.text(AmicodeHarness.harnessResponse(body), {
+          contentType: "application/json",
+        })
+      }),
+    )
   }),
 ).pipe(Layer.provide(authOnlyRouterLayer))
 
diff --git a/packages/app-bundle/overlay/packages/opencode/test/server/amicode-harness.test.ts b/packages/app-bundle/overlay/packages/opencode/test/server/amicode-harness.test.ts
new file mode 100644
index 000000000..1bd0e4e39
--- /dev/null
+++ b/packages/app-bundle/overlay/packages/opencode/test/server/amicode-harness.test.ts
@@ -0,0 +1,180 @@
+// AMICODE: harness switch route tests (amicode#1549). The engine half of the
+// harness.json contract: GET serves the current harness + the extension's
+// published registry view; POST validates against that view and writes
+// {harness, status:"switching"} for the extension watcher to perform. The
+// engine never computes the registry and never hardcodes harness identity —
+// the id allowlist IS the published view. Same env-override + tmp-dir
+// discipline as the connections suite (AMICODE_OPS_DIR).
+import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import { mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import path from "node:path"
+import {
+  HARNESS_SWITCH_WARNING,
+  harnessFile,
+  harnessOptionsFile,
+  harnessResponse,
+  harnessStateResponse,
+  readHarnessOptions,
+  readHarnessState,
+} from "@/server/amicode/harness"
+import { setBindHostname } from "@/server/amicode/connections"
+
+const ENV_KEYS = ["AMICODE_OPS_DIR"]
+
+const MENU = {
+  current: "opencode",
+  options: [
+    { id: "opencode", displayName: "opencode (default)", state: "ready", detail: "The default harness.", disabled: false },
+    {
+      id: "telaio",
+      displayName: "telaio (subscription)",
+      state: "ready",
+      detail: "Serves the Harness Contract v1 API.",
+      disabled: false,
+    },
+  ],
+}
+
+let dir: string
+
+beforeEach(() => {
+  dir = mkdtempSync(path.join(tmpdir(), "amicode-harness-"))
+  for (const key of ENV_KEYS) process.env[key] = path.join(dir, "ops")
+  mkdirSync(path.join(dir, "ops"), { recursive: true })
+})
+
+afterEach(() => {
+  for (const key of ENV_KEYS) delete process.env[key]
+})
+
+const writeOptions = (menu: unknown) => writeFileSync(harnessOptionsFile(), JSON.stringify(menu))
+
+describe("GET /amicode/harness — the state the composer renders (#1549)", () => {
+  test("no files at all → the opencode default, ready, NO options (the control stays hidden)", () => {
+    const parsed = JSON.parse(harnessStateResponse()) as Record<string, unknown>
+    expect(parsed.ok).toBe(true)
+    expect(parsed.harness).toBe("opencode")
+    expect(parsed.status).toBe("ready")
+    expect(parsed.options).toBeUndefined()
+  })
+
+  test("a published registry view rides the response; the view's current wins while it exists", () => {
+    writeOptions(MENU)
+    const parsed = JSON.parse(harnessStateResponse()) as Record<string, unknown>
+    expect(parsed.harness).toBe("opencode")
+    expect(parsed.options).toEqual(MENU.options)
+    writeOptions({ ...MENU, current: "telaio" })
+    expect((JSON.parse(harnessStateResponse()) as Record<string, unknown>).harness).toBe("telaio")
+  })
+
+  test("a switching handshake overrides the STATUS but not the displayed current", () => {
+    writeOptions(MENU)
+    writeFileSync(harnessFile(), JSON.stringify({ harness: "telaio", status: "switching" }))
+    const parsed = JSON.parse(harnessStateResponse()) as Record<string, unknown>
+    expect(parsed.harness).toBe("opencode") // the setting-backed view still speaks
+    expect(parsed.status).toBe("switching")
+  })
+
+  test("corrupt files collapse to the defaults, never a throw", () => {
+    writeFileSync(harnessOptionsFile(), "not json {{{")
+    writeFileSync(harnessFile(), "also not json {{{")
+    const parsed = JSON.parse(harnessStateResponse()) as Record<string, unknown>
+    expect(parsed.harness).toBe("opencode")
+    expect(parsed.status).toBe("ready")
+    expect(parsed.options).toBeUndefined()
+  })
+
+  test("off-shape option entries are dropped, not repaired; an all-bad view reads as absent", () => {
+    writeFileSync(
+      harnessOptionsFile(),
+      JSON.stringify({
+        current: "opencode",
+        options: [{ id: "telaio" }, { id: "", displayName: "x", state: "ready", disabled: false }, "junk", MENU.options[1]],
+      }),
+    )
+    const view = readHarnessOptions()
+    expect(view?.options.map((o) => o.id)).toEqual(["telaio"])
+    writeFileSync(harnessOptionsFile(), JSON.stringify({ current: "opencode", options: ["junk"] }))
+    expect(readHarnessOptions()).toBeUndefined()
+  })
+})
+
+describe("POST /amicode/harness — the switching write (#1549)", () => {
+  test("a valid different harness writes {harness, status:switching} and answers ok", () => {
+    writeOptions(MENU)
+    const parsed = JSON.parse(harnessResponse(JSON.stringify({ harness: "telaio" }))) as Record<string, unknown>
+    expect(parsed.ok).toBe(true)
+    expect(parsed.harness).toBe("telaio")
+    expect(parsed.noop).toBe(false)
+    expect(parsed.error).toBeNull()
+    expect(JSON.parse(readFileSync(harnessFile(), "utf8"))).toEqual({ harness: "telaio", status: "switching" })
+  })
+
+  test("selecting the current harness is a no-op: ok, and the watcher is NOT poked", () => {
+    writeOptions(MENU)
+    const parsed = JSON.parse(harnessResponse(JSON.stringify({ harness: "opencode" }))) as Record<string, unknown>
+    expect(parsed.ok).toBe(true)
+    expect(parsed.noop).toBe(true)
+    let threw = false
+    try {
+      readFileSync(harnessFile())
+    } catch {
+      threw = true
+    }
+    expect(threw).toBe(true) // no switching write happened
+  })
+
+  test("an id outside the published registry is refused and writes nothing", () => {
+    writeOptions(MENU)
+    const parsed = JSON.parse(harnessResponse(JSON.stringify({ harness: "ghost" }))) as Record<string, unknown>
+    expect(parsed.ok).toBe(false)
+    expect(parsed.harness).toBeNull()
+    expect(parsed.error).toContain("unsupported_harness")
+    expect(readHarnessState().harness).toBe("opencode")
+  })
+
+  test("NO published registry → refused (there is no extension to perform the switch)", () => {
+    const parsed = JSON.parse(harnessResponse(JSON.stringify({ harness: "telaio" }))) as Record<string, unknown>
+    expect(parsed.ok).toBe(false)
+    expect(parsed.error).toContain("registry_unavailable")
+    let threw = false
+    try {
+      readFileSync(harnessFile())
+    } catch {
+      threw = true
+    }
+    expect(threw).toBe(true)
+  })
+
+  test("malformed bodies are refused with fixed messages, writing nothing", () => {
+    writeOptions(MENU)
+    for (const body of [JSON.stringify({ mode: "hp" }), JSON.stringify({}), JSON.stringify({ harness: 42 }), "not json {{{"]) {
+      const parsed = JSON.parse(harnessResponse(body)) as Record<string, unknown>
+      expect(parsed.ok).toBe(false)
+      expect(parsed.harness).toBeNull()
+      expect(typeof parsed.error).toBe("string")
+    }
+    expect(readHarnessState().status).toBe("ready")
+  })
+
+  test("non-loopback bind is refused INERTLY — nothing is written", () => {
+    writeOptions(MENU)
+    setBindHostname("0.0.0.0")
+    const refused = JSON.parse(harnessResponse(JSON.stringify({ harness: "telaio" }))) as Record<string, unknown>
+    setBindHostname(undefined)
+    expect(refused.ok).toBe(false)
+    expect(refused.error).toContain("non_loopback")
+    expect(readHarnessState().status).toBe("ready")
+  })
+
+  test("a failing switching write → ok:false with a fixed, value-free warning (no path, no errno)", () => {
+    writeOptions(MENU)
+    // an unwritable harness.json path (a directory squatting the filename)
+    mkdirSync(harnessFile(), { recursive: true })
+    const raw = harnessResponse(JSON.stringify({ harness: "telaio" }))
+    expect((JSON.parse(raw) as Record<string, unknown>).ok).toBe(false)
+    expect((JSON.parse(raw) as Record<string, unknown>).error).toBe(HARNESS_SWITCH_WARNING)
+    expect(raw).not.toContain(dir)
+  })
+})
diff --git a/packages/app-bundle/overlay/packages/session-ui/src/v2/components/prompt-input/index.tsx b/packages/app-bundle/overlay/packages/session-ui/src/v2/components/prompt-input/index.tsx
index 78db4a102..e939e2993 100644
--- a/packages/app-bundle/overlay/packages/session-ui/src/v2/components/prompt-input/index.tsx
+++ b/packages/app-bundle/overlay/packages/session-ui/src/v2/components/prompt-input/index.tsx
@@ -41,6 +41,21 @@ export type PromptInputV2Props = {
   borderUnderlay?: boolean
   class?: string
   modelControl?: JSX.Element
+  /**
+   * Optional control rendered FIRST in the bottom row's control group,
+   * before agent/model/variant (amicode#1549: the harness switcher — the
+   * outermost context the composer serves). Follows the modelControl
+   * optional-control pattern: pass `undefined` and nothing renders — the
+   * row's layout does not shift.
+   */
+  harnessControl?: JSX.Element
+  /**
+   * Degraded-composer affordance (amicode#1549): when the serving harness's
+   * contract accepts no agent/model/variant (telaio's Harness Contract v1),
+   * those slots dim inertly with an honest why instead of silently failing.
+   * Undefined/false renders `display: contents` — byte-identical layout.
+   */
+  harnessDegraded?: boolean
   /**
    * Optional control rendered in the bottom row's right anchor, immediately
    * left of the send button (amicode/opencode#116: the report-a-bug button).
@@ -220,39 +235,47 @@ export function PromptInputV2(props: PromptInputV2Props) {
               onContext={props.controller.openContext}
               onShell={props.controller.openShell}
             />
-            <Show when={view.agent} keyed>
-              {(control) => (
-                <PromptInputV2ConfiguredSelect title="Choose agent" keybind={["Mod", "."]} control={control} />
-              )}
+            <Show when={props.harnessControl} keyed>
+              {(control) => control}
             </Show>
-            <Show
-              when={props.modelControl}
-              fallback={
-                <Show when={view.model} keyed>
-                  {(control) => (
+            <div
+              class={props.harnessDegraded ? "flex min-w-0 flex-1 items-center gap-1 opacity-40 pointer-events-none" : "contents"}
+              title={props.harnessDegraded ? "Not accepted by this harness" : undefined}
+            >
+              <Show when={view.agent} keyed>
+                {(control) => (
+                  <PromptInputV2ConfiguredSelect title="Choose agent" keybind={["Mod", "."]} control={control} />
+                )}
+              </Show>
+              <Show
+                when={props.modelControl}
+                fallback={
+                  <Show when={view.model} keyed>
+                    {(control) => (
+                      <PromptInputV2ConfiguredSelect
+                        title="Choose model"
+                        keybind={["Mod", "M"]}
+                        control={control}
+                        model
+                      />
+                    )}
+                  </Show>
+                }
+              >
+                {props.modelControl}
+              </Show>
+              <Show when={(props.variantControlVisible ?? true) && view.variant} keyed>
+                {(control) => (
+                  <Show when={control.options().length > 1}>
                     <PromptInputV2ConfiguredSelect
-                      title="Choose model"
-                      keybind={["Mod", "M"]}
+                      title="Choose model variant"
+                      keybind={["Shift", "Mod", "D"]}
                       control={control}
-                      model
                     />
-                  )}
-                </Show>
-              }
-            >
-              {props.modelControl}
-            </Show>
-            <Show when={(props.variantControlVisible ?? true) && view.variant} keyed>
-              {(control) => (
-                <Show when={control.options().length > 1}>
-                  <PromptInputV2ConfiguredSelect
-                    title="Choose model variant"
-                    keybind={["Shift", "Mod", "D"]}
-                    control={control}
-                  />
-                </Show>
-              )}
-            </Show>
+                  </Show>
+                )}
+              </Show>
+            </div>
           </div>
           <Show when={props.trailingControl} keyed>
             {(control) => <div class="mr-1 flex items-center">{control}</div>}
diff --git a/packages/extension/src/extension.ts b/packages/extension/src/extension.ts
index 55721e6c2..82265a4d7 100644
--- a/packages/extension/src/extension.ts
+++ b/packages/extension/src/extension.ts
@@ -4,7 +4,9 @@ import * as fs from "node:fs";
 import { ServerManager } from "./server_manager";
 import { fetchProviderSignal, fetchProviderIds } from "./llm_creds.mjs";
 import { resolveOpencodeBinary, OpencodeMissingError, unsupportedHostAdvice } from "./opencode_binary";
-import { resolveSelectedLaunch, HARNESS_REGISTRY } from "./harness";
+import { resolveSelectedLaunch, harnessMenu, decideHarnessSwitch } from "./harness";
+import { watchHarnessSwitch, writeHarnessOptionsFile } from "./harness_switch";
+import { readLocalEntitlements } from "./scores/entitlements";
 import { ChatPanel } from "./chat_panel";
 import { DeckPanel } from "./deck_panel";
 import { SidebarViewProvider, createNewProject, createNewEnvironment } from "./sidebar_view";
@@ -151,6 +153,39 @@ let fleetVerbRunner: (() => VerbRunResult) | undefined;
  *  rejection + the refresh pointer), and the D1 freshness verdict each render
  *  — never a silent fallthrough, never a raw-file read. The GUARD remains the
  *  enforcement (it fails closed on a broken verb); this check is the UX layer. */
+// ============================================================================
+// #1549 — the harness switcher. One registry, two fronts: the palette command
+// and the composer control (via the engine's GET/POST /amicode/harness routes)
+// both render from currentHarnessMenu's serialization and both consult
+// decideHarnessSwitch before anything persists or restarts.
+// ============================================================================
+
+/** The current registry menu for the running settings — the ONE serialization
+ *  the options file publishes and both fronts render. Entitlements resolve
+ *  from the ops-dir entitlements.toml, the same file the mode-card gate reads. */
+function currentHarnessMenu(cfg: vscode.WorkspaceConfiguration) {
+  return harnessMenu({
+    current: cfg.get<string>("harness", "opencode"),
+    entitlements: readLocalEntitlements(path.join(os.homedir(), ".amico", "amicode")).entitlements,
+    settingsBag: {
+      opencodeBinary: cfg.get<string>("opencodeBinary", ""),
+      telaioBinary: cfg.get<string>("telaioBinary", ""),
+      telaioAppDir: cfg.get<string>("telaioAppDir", ""),
+    },
+  });
+}
+
+/** Publish the registry menu for the engine's GET /amicode/harness. Best-
+ *  effort: a failed write must never block boot — the composer control simply
+ *  stays hidden until the next publish. */
+function publishHarnessOptions(cfg: vscode.WorkspaceConfiguration, log: (line: string) => void): void {
+  try {
+    writeHarnessOptionsFile(currentHarnessMenu(cfg));
+  } catch (e) {
+    log(`[harness] options publish failed — ${(e as Error).message}`);
+  }
+}
+
 function isFleetClientGuard(binary: string | undefined, log: (line: string) => void = () => {}): boolean {
   if (process.platform !== "darwin") return false;
   if (!binary || !binary.endsWith("amico-opencode-fleet-guard")) return false;
@@ -617,6 +652,10 @@ export async function activate(ctx: vscode.ExtensionContext): Promise<void> {
     });
     harnessConsumesOpencodeConfig = launch.descriptor.consumesOpencodeConfig;
     binary = launch.binary;
+    // #1549: publish the registry menu so the composer control can render it
+    // (the engine's GET /amicode/harness serves this file; the POST route
+    // validates against it). Boot is the first publish; every switch republishes.
+    publishHarnessOptions(bootCfg, (line) => opencodeChannel.appendLine(line));
     opencodeChannel.appendLine(
       bootCfg.get<string>("opencodeBinary", "").trim() !== "" && launch.descriptor.id === "opencode"
         ? `[boot] OVERRIDE: amicode.opencodeBinary = ${binary}`
@@ -1138,6 +1177,45 @@ export async function activate(ctx: vscode.ExtensionContext): Promise<void> {
       }),
     );
 
+    // Harness switcher (#1549): the composer control POSTs {harness} to the
+    // engine's /amicode/harness route, which writes {harness,
+    // status:"switching"}; we do the REAL switch — the registry gate (the
+    // same decideHarnessSwitch the palette consults), the `amicode.harness`
+    // setting persist, the restartServer respawn — and the watcher settles
+    // status:"ready" at the harness onSwitch reports. A refused switch (the
+    // gate blocked it between the UI's read and the watcher's run) settles
+    // ready at the STILL-CURRENT harness — never a ready file claiming a
+    // switch that didn't happen.
+    ctx.subscriptions.push(
+      watchHarnessSwitch(async (harness) => {
+        opencodeChannel.appendLine(`[harness] switching → ${harness}`);
+        const cfg = vscode.workspace.getConfiguration("amicode");
+        const decision = decideHarnessSwitch({
+          requested: harness,
+          current: cfg.get<string>("harness", "opencode"),
+          entitlements: readLocalEntitlements(path.join(os.homedir(), ".amico", "amicode")).entitlements,
+          settingsBag: {
+            opencodeBinary: cfg.get<string>("opencodeBinary", ""),
+            telaioBinary: cfg.get<string>("telaioBinary", ""),
+            telaioAppDir: cfg.get<string>("telaioAppDir", ""),
+          },
+        });
+        if (!decision.allowed) {
+          opencodeChannel.appendLine(`[harness] switch to "${harness}" refused — ${decision.reason ?? "blocked"}`);
+          void vscode.window.showWarningMessage(`Amicode: harness switch refused — ${decision.reason ?? "blocked"}`);
+          return cfg.get<string>("harness", "opencode");
+        }
+        if (decision.noop) return cfg.get<string>("harness", "opencode");
+        await cfg.update("harness", harness, vscode.ConfigurationTarget.Global);
+        // Republish BEFORE the restart: the fresh server's first GET must
+        // already show the new current.
+        publishHarnessOptions(cfg, (line) => opencodeChannel.appendLine(line));
+        await vscode.commands.executeCommand("amicode.restartServer");
+        opencodeChannel.appendLine(`[harness] switched → ${harness} (server back up)`);
+        return harness;
+      }),
+    );
+
     // Slack credential watcher (#1037 v2): dynamically add/remove the
     // slack-mcp-server via the engine's MCP API when the credential file
     // (~/.amico/slack.json) is created or deleted. No server restart needed.
@@ -2096,56 +2174,75 @@ export async function activate(ctx: vscode.ExtensionContext): Promise<void> {
 
   // 5. Commands
   ctx.subscriptions.push(
-    // The harness picker (ADR-0011, #659): the registry IS the menu. Entries
-    // carry honest availability; an unavailable option routes to guidance
-    // instead of switching. The disclosure rides every entry: sessions are
-    // harness-local — switching harnesses switches session history. Switch =
-    // persist + the existing restartServer respawn path.
+    // The harness picker (ADR-0011, #659; #1549): the registry IS the menu —
+    // rendered from harnessMenu, the SAME serialization the composer control
+    // renders, and gated by decideHarnessSwitch, the SAME decision the
+    // composer's watcher path consults (one registry, two fronts). Entries
+    // carry honest availability + the entitlement read-side gate as
+    // disabled-with-reason; a blocked pick routes to guidance instead of
+    // switching. The disclosure rides every entry: sessions are harness-local
+    // — switching harnesses switches session history. Switch = persist + the
+    // existing restartServer respawn path.
     vscode.commands.registerCommand("amicode.selectHarness", async () => {
       const cfg = vscode.workspace.getConfiguration("amicode");
-      const current = cfg.get<string>("harness", "opencode");
-      const settingsBag = {
-        opencodeBinary: cfg.get<string>("opencodeBinary", ""),
-        telaioBinary: cfg.get<string>("telaioBinary", ""),
-        telaioAppDir: cfg.get<string>("telaioAppDir", ""),
-      };
-      const items = HARNESS_REGISTRY.map((d) => {
-        const avail = d.availability(settingsBag);
-        const isCurrent = d.id === current;
+      const menu = currentHarnessMenu(cfg);
+      const items = menu.options.map((option) => {
+        const isCurrent = option.id === menu.current;
         return {
-          descriptor: d,
-          avail,
-          label: isCurrent ? `$(check) ${d.displayName}` : d.displayName,
-          description: isCurrent ? "current" : avail.state,
-          detail: `${avail.detail} Sessions are harness-local — switching switches session history.`,
+          option,
+          isCurrent,
+          label: isCurrent ? `$(check) ${option.displayName}` : option.displayName,
+          description: isCurrent ? "current" : option.disabled ? "unavailable" : option.state,
+          detail: `${option.detail} Sessions are harness-local — switching switches session history.`,
         };
       });
       const pick = await vscode.window.showQuickPick(items, {
         placeHolder: "Amicode: select the chat harness",
       });
-      if (!pick || pick.descriptor.id === current) return;
-      if (pick.avail.state === "needs-setup") {
+      if (!pick || pick.isCurrent) return;
+      if (pick.option.disabled) {
+        const needsSetup = pick.option.state === "needs-setup";
         const action = await vscode.window.showWarningMessage(
-          `${pick.descriptor.displayName} isn't ready yet`,
+          `${pick.option.displayName} isn't available — ${pick.option.reason ?? "unavailable"}`,
           { modal: false },
-          "Open Settings",
+          ...(needsSetup ? ["Open Settings"] : []),
         );
         if (action === "Open Settings") {
           void vscode.commands.executeCommand(
             "workbench.action.openSettings",
-            pick.descriptor.id === "telaio" ? "amicode.telaioBinary" : "amicode.harness",
+            pick.option.id === "telaio" ? "amicode.telaioBinary" : "amicode.harness",
           );
         }
         return;
       }
       const confirm = await vscode.window.showWarningMessage(
-        `Switch to ${pick.descriptor.displayName}? Sessions are harness-local — the new harness starts with its own (empty) history.`,
+        `Switch to ${pick.option.displayName}? Sessions are harness-local — the new harness starts with its own (empty) history.`,
         { modal: true },
         "Switch & Restart",
       );
       if (confirm !== "Switch & Restart") return;
-      await cfg.update("harness", pick.descriptor.id, vscode.ConfigurationTarget.Global);
-      opencodeChannel.appendLine(`[harness] selected: ${pick.descriptor.id} — restarting the server`);
+      // The SAME gate the composer's watcher path consults — if state changed
+      // between the menu render and this confirm, the decision, not the stale
+      // menu, decides. The persist + restart below is the palette front of
+      // the same state the watcher lands.
+      const decision = decideHarnessSwitch({
+        requested: pick.option.id,
+        current: cfg.get<string>("harness", "opencode"),
+        entitlements: readLocalEntitlements(path.join(os.homedir(), ".amico", "amicode")).entitlements,
+        settingsBag: {
+          opencodeBinary: cfg.get<string>("opencodeBinary", ""),
+          telaioBinary: cfg.get<string>("telaioBinary", ""),
+          telaioAppDir: cfg.get<string>("telaioAppDir", ""),
+        },
+      });
+      if (!decision.allowed) {
+        void vscode.window.showWarningMessage(`Amicode: harness switch refused — ${decision.reason ?? "blocked"}`);
+        return;
+      }
+      if (decision.noop) return;
+      await cfg.update("harness", pick.option.id, vscode.ConfigurationTarget.Global);
+      publishHarnessOptions(cfg, (line) => opencodeChannel.appendLine(line));
+      opencodeChannel.appendLine(`[harness] selected: ${pick.option.id} — restarting the server`);
       void vscode.commands.executeCommand("amicode.restartServer");
     }),
   );
diff --git a/packages/extension/src/harness.ts b/packages/extension/src/harness.ts
index 1b8249a2b..0b672bd2f 100644
--- a/packages/extension/src/harness.ts
+++ b/packages/extension/src/harness.ts
@@ -105,6 +105,99 @@ export function resolveHarness(id: string): HarnessDescriptor | undefined {
   return HARNESS_REGISTRY.find((d) => d.id === id);
 }
 
+// ============================================================================
+// #1549 — the harness switcher in the chat box. The palette command and the
+// composer control are TWO FRONTS on this ONE registry: both render from
+// harnessMenu's serialization and both consult decideHarnessSwitch before
+// anything persists or restarts. The entitlement read-side gate lives at this
+// layer (disabled with its reason) — never a hidden failure at spawn time.
+// ============================================================================
+
+export interface HarnessMenuItem {
+  id: HarnessId;
+  displayName: string;
+  state: "ready" | "needs-setup";
+  detail: string;
+  disabled: boolean;
+  /** Present exactly when disabled — the honest why, value-free copy. */
+  reason?: string;
+}
+
+export interface HarnessMenu {
+  current: HarnessId;
+  options: HarnessMenuItem[];
+}
+
+const UNENTITLED_DETAIL = (entitlement: string) =>
+  `Requires the \`${entitlement}\` entitlement — this build's subscription gate hasn't granted it.`;
+
+/** harnessMenu — the ONE serialization of the registry both fronts render.
+ *  An unset or unknown current displays as the opencode default, matching the
+ *  default resolveSelectedLaunch serves. Blocking precedence: the entitlement
+ *  first (configuring a binary is pointless without the grant), then
+ *  availability detail. */
+export function harnessMenu(input: {
+  current: string;
+  entitlements: string[];
+  settingsBag: { opencodeBinary: string; telaioBinary: string; telaioAppDir: string };
+}): HarnessMenu {
+  const current = (resolveHarness(input.current) ?? opencodeDescriptor).id;
+  const options = HARNESS_REGISTRY.map((descriptor): HarnessMenuItem => {
+    const avail = descriptor.availability(input.settingsBag);
+    const unentitled =
+      descriptor.requiredEntitlement !== undefined && !input.entitlements.includes(descriptor.requiredEntitlement);
+    const disabled = unentitled || avail.state === "needs-setup";
+    const reason = unentitled
+      ? UNENTITLED_DETAIL(descriptor.requiredEntitlement!)
+      : avail.state === "needs-setup"
+        ? avail.detail
+        : undefined;
+    return {
+      id: descriptor.id,
+      displayName: descriptor.displayName,
+      state: avail.state,
+      detail: avail.detail,
+      disabled,
+      ...(reason !== undefined ? { reason } : {}),
+    };
+  });
+  return { current, options };
+}
+
+export interface HarnessSwitchDecision {
+  allowed: boolean;
+  /** true when the requested harness is already the current one — the caller
+   *  pokes no restart for a no-op (the solver-mode watcher discipline). */
+  noop: boolean;
+  /** Present exactly when blocked — the honest why. */
+  reason?: string;
+}
+
+/** decideHarnessSwitch — the ONE gate both fronts consult before persisting
+ *  or restarting. Unknown ids are blocked here (a stale or hand-edited client
+ *  cannot poke the watcher into a fallback restart); needs-setup and
+ *  unentitled targets are blocked with their reason. */
+export function decideHarnessSwitch(input: {
+  requested: string;
+  current: string;
+  entitlements: string[];
+  settingsBag: { opencodeBinary: string; telaioBinary: string; telaioAppDir: string };
+}): HarnessSwitchDecision {
+  const requested = resolveHarness(input.requested === "" ? "opencode" : input.requested);
+  if (requested === undefined) {
+    return { allowed: false, noop: false, reason: `Unknown harness "${input.requested}" — pick one from the registry.` };
+  }
+  const current = (resolveHarness(input.current === "" ? "opencode" : input.current) ?? opencodeDescriptor).id;
+  if (requested.id === current) return { allowed: true, noop: true };
+  const item = harnessMenu({
+    current,
+    entitlements: input.entitlements,
+    settingsBag: input.settingsBag,
+  }).options.find((o) => o.id === requested.id);
+  if (item?.disabled) return { allowed: false, noop: false, reason: item.reason };
+  return { allowed: true, noop: false };
+}
+
 export interface SelectedLaunch {
   descriptor: HarnessDescriptor;
   binary: string;
diff --git a/packages/extension/src/harness_switch.ts b/packages/extension/src/harness_switch.ts
new file mode 100644
index 000000000..8eeeaecae
--- /dev/null
+++ b/packages/extension/src/harness_switch.ts
@@ -0,0 +1,96 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { amicodeOpsDir } from "./substrate/vault_store";
+import type { HarnessMenu } from "./harness";
+
+// ============================================================================
+// Harness switch — the extension half of the harness.json contract (the fork
+// half is the engine's server/amicode/harness.ts; change both in one
+// change-set). The app's composer control POSTs {harness} to
+// /amicode/harness; the engine route writes {harness, status:"switching"} to
+// the ops dir; WE do the real switch — the registry gate (decideHarnessSwitch),
+// the `amicode.harness` setting persist, the server restart — and only then
+// settle status:"ready", at the harness that ACTUALLY took effect. Mirrors
+// solver_mode.ts's watcher discipline (poll + busy latch); the difference is
+// honest refusal: a blocked switch settles ready at the harness that is still
+// current, never at the one that was refused.
+// ============================================================================
+
+export interface HarnessSwitchState {
+  harness: string;
+  status: "ready" | "switching";
+}
+
+export function harnessSwitchFile(opsDir: string = amicodeOpsDir()): string {
+  return path.join(opsDir, "harness.json");
+}
+
+export function harnessOptionsFile(opsDir: string = amicodeOpsDir()): string {
+  return path.join(opsDir, "harness-options.json");
+}
+
+/** Tolerant {harness, status} read — the solver-mode reader's semantics:
+ *  anything absent/off-shape collapses to opencode/ready. */
+export function readHarnessSwitchState(file: string = harnessSwitchFile()): HarnessSwitchState {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, "utf8")) as { harness?: unknown; status?: unknown };
+    return {
+      harness: typeof parsed.harness === "string" && parsed.harness !== "" ? parsed.harness : "opencode",
+      status: parsed.status === "switching" ? "switching" : "ready",
+    };
+  } catch {
+    return { harness: "opencode", status: "ready" };
+  }
+}
+
+/** Settle the handshake: status:"ready" at the harness that ACTUALLY took
+ *  effect. On a refused or failed switch the caller passes the still-current
+ *  harness — a ready file claiming a switch that didn't happen is the lie we
+ *  don't tell. */
+export function writeHarnessReady(harness: string, file: string = harnessSwitchFile()): void {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify({ harness, status: "ready", switched_at: new Date().toISOString() }));
+}
+
+/** Publish the registry menu for the engine's GET /amicode/harness — the ONE
+ *  serialization (harnessMenu) the composer control renders. Written at boot
+ *  and after every successful switch; the engine only ever SERVES it, never
+ *  computes it (the registry lives here). */
+export function writeHarnessOptionsFile(menu: HarnessMenu, file: string = harnessOptionsFile()): void {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(menu));
+}
+
+/** Poll-based watcher (the watchSolverMode idiom): fires onSwitch once per
+ *  switching-request; the busy latch guarantees a slow switch is never
+ *  re-entered by the next tick. onSwitch RETURNS the harness to settle ready
+ *  at — the requested one on success, the still-current one on a refusal or
+ *  failure. */
+export function watchHarnessSwitch(
+  onSwitch: (harness: string) => Promise<string>,
+  file: string = harnessSwitchFile(),
+  intervalMs = 1000,
+): { dispose(): void } {
+  let busy = false;
+  const timer = setInterval(() => {
+    if (busy) return;
+    const state = readHarnessSwitchState(file);
+    if (state.status !== "switching") return;
+    busy = true;
+    void onSwitch(state.harness)
+      .then((settled) => writeHarnessReady(settled, file))
+      .catch(() => {
+        // A throwing switch leaves the setting unchanged, so the honest
+        // settle is the default the file would read anyway.
+        writeHarnessReady("opencode", file);
+      })
+      .finally(() => {
+        busy = false;
+      });
+  }, intervalMs);
+  return {
+    dispose() {
+      clearInterval(timer);
+    },
+  };
+}
diff --git a/packages/extension/test/harness.test.ts b/packages/extension/test/harness.test.ts
index d502ab8f4..b9644d7c1 100644
--- a/packages/extension/test/harness.test.ts
+++ b/packages/extension/test/harness.test.ts
@@ -1,6 +1,6 @@
 import { describe, it, expect } from "vitest";
 import { resolveSelectedLaunch, resolveHarness, HARNESS_REGISTRY,
-         opencodeDescriptor, telaioDescriptor } from "../src/harness";
+         opencodeDescriptor, telaioDescriptor, harnessMenu, decideHarnessSwitch } from "../src/harness";
 import { resolveOpencodeBinary, OpencodeMissingError } from "../src/opencode_binary";
 
 // ============================================================================
@@ -166,3 +166,121 @@ describe("resolveSelectedLaunch — the one call the spawn sites make", () => {
     ).toThrow(OpencodeMissingError);
   });
 });
+
+// ============================================================================
+// #1549 — the harness switcher in the chat box. The composer control and the
+// palette command are TWO FRONTS on ONE registry: both render from
+// harnessMenu's serialization and both consult decideHarnessSwitch before
+// anything persists. The entitlement read-side gate lives HERE (disabled with
+// its reason), never as a hidden failure at spawn time.
+// ============================================================================
+
+const READY_BAG = { opencodeBinary: "", telaioBinary: "/opt/telaio", telaioAppDir: "" };
+const EMPTY_BAG = { opencodeBinary: "", telaioBinary: "", telaioAppDir: "" };
+
+describe("harnessMenu — the one serialization both fronts render (#1549)", () => {
+  it("serializes the registry in its order, current marked", () => {
+    const menu = harnessMenu({ current: "opencode", entitlements: [], settingsBag: READY_BAG });
+    expect(menu.current).toBe("opencode");
+    expect(menu.options.map((o) => o.id)).toEqual(["opencode", "telaio"]);
+    expect(menu.options[0]?.displayName).toBe("opencode (default)");
+    expect(menu.options[1]?.displayName).toBe("telaio (subscription)");
+  });
+
+  it("an unset or unknown current falls back to opencode for display — the same default resolveSelectedLaunch serves", () => {
+    expect(harnessMenu({ current: "", entitlements: [], settingsBag: READY_BAG }).current).toBe("opencode");
+    expect(harnessMenu({ current: "ghost", entitlements: [], settingsBag: READY_BAG }).current).toBe("opencode");
+  });
+
+  it("an unresolvable harness is disabled WITH its reason — never silently absent", () => {
+    const menu = harnessMenu({ current: "opencode", entitlements: ["harness.telaio"], settingsBag: EMPTY_BAG });
+    const telaio = menu.options.find((o) => o.id === "telaio");
+    expect(telaio?.disabled).toBe(true);
+    expect(telaio?.reason).toContain("amicode.telaioBinary");
+  });
+
+  it("an unentitled harness is disabled WITH its reason, even when the binary is set", () => {
+    const menu = harnessMenu({ current: "opencode", entitlements: [], settingsBag: READY_BAG });
+    const telaio = menu.options.find((o) => o.id === "telaio");
+    expect(telaio?.disabled).toBe(true);
+    expect(telaio?.reason).toContain("harness.telaio");
+  });
+
+  it("an entitled, ready harness is selectable; the default is never disabled", () => {
+    const menu = harnessMenu({ current: "opencode", entitlements: ["harness.telaio"], settingsBag: READY_BAG });
+    expect(menu.options.find((o) => o.id === "telaio")?.disabled).toBe(false);
+    expect(menu.options.find((o) => o.id === "opencode")?.disabled).toBe(false);
+    expect(menu.options.find((o) => o.id === "opencode")?.reason).toBeUndefined();
+  });
+});
+
+describe("decideHarnessSwitch — the one gate both fronts consult (#1549)", () => {
+  it("the same harness is an allowed no-op — no restart is poked for nothing", () => {
+    const d = decideHarnessSwitch({ requested: "opencode", current: "opencode", entitlements: [], settingsBag: EMPTY_BAG });
+    expect(d.allowed).toBe(true);
+    expect(d.noop).toBe(true);
+  });
+
+  it("an unset request normalizes to the opencode default before comparing", () => {
+    const d = decideHarnessSwitch({ requested: "", current: "opencode", entitlements: [], settingsBag: EMPTY_BAG });
+    expect(d.allowed).toBe(true);
+    expect(d.noop).toBe(true);
+  });
+
+  it("an entitled, launchable different harness is allowed", () => {
+    const d = decideHarnessSwitch({ requested: "telaio", current: "opencode", entitlements: ["harness.telaio"], settingsBag: READY_BAG });
+    expect(d.allowed).toBe(true);
+    expect(d.noop).toBe(false);
+  });
+
+  it("an unentitled harness is blocked with the entitlement reason — never selectable-then-failing", () => {
+    const d = decideHarnessSwitch({ requested: "telaio", current: "opencode", entitlements: [], settingsBag: READY_BAG });
+    expect(d.allowed).toBe(false);
+    expect(d.reason).toContain("harness.telaio");
+  });
+
+  it("a needs-setup harness is blocked with the setup guidance", () => {
+    const d = decideHarnessSwitch({ requested: "telaio", current: "opencode", entitlements: ["harness.telaio"], settingsBag: EMPTY_BAG });
+    expect(d.allowed).toBe(false);
+    expect(d.reason).toContain("amicode.telaioBinary");
+  });
+
+  it("an unknown id is blocked — a hand-edited or stale client cannot poke the watcher into a fallback", () => {
+    const d = decideHarnessSwitch({ requested: "ghost", current: "opencode", entitlements: ["harness.telaio"], settingsBag: READY_BAG });
+    expect(d.allowed).toBe(false);
+    expect(d.reason).toBeTruthy();
+  });
+});
+
+describe("one registry, two fronts — the same decision lands the same state (#1549)", () => {
+  // The palette command and the composer watcher are two UIs over ONE state:
+  // both flows are decideHarnessSwitch → persist. This pin holds the contract
+  // the AC names: switching from either lands the same state, and a blocked
+  // request persists NOTHING from either front.
+  const persistFlow = (front: "palette" | "composer", input: Parameters<typeof decideHarnessSwitch>[0]) => {
+    const decision = decideHarnessSwitch(input);
+    const persisted: string[] = [];
+    if (decision.allowed && !decision.noop) persisted.push(input.requested);
+    return { front, decision, persisted };
+  };
+
+  it("an allowed switch lands the same persisted harness from either front", () => {
+    const input = { requested: "telaio", current: "opencode", entitlements: ["harness.telaio"], settingsBag: READY_BAG };
+    const palette = persistFlow("palette", input);
+    const composer = persistFlow("composer", input);
+    expect(palette.persisted).toEqual(["telaio"]);
+    expect(composer.persisted).toEqual(palette.persisted);
+  });
+
+  it("a blocked switch persists NOTHING from either front", () => {
+    const input = { requested: "telaio", current: "opencode", entitlements: [], settingsBag: READY_BAG };
+    expect(persistFlow("palette", input).persisted).toEqual([]);
+    expect(persistFlow("composer", input).persisted).toEqual([]);
+  });
+
+  it("a no-op switch persists NOTHING from either front", () => {
+    const input = { requested: "opencode", current: "opencode", entitlements: [], settingsBag: EMPTY_BAG };
+    expect(persistFlow("palette", input).persisted).toEqual([]);
+    expect(persistFlow("composer", input).persisted).toEqual([]);
+  });
+});
diff --git a/packages/extension/test/harness_switch.test.ts b/packages/extension/test/harness_switch.test.ts
new file mode 100644
index 000000000..46ff849af
--- /dev/null
+++ b/packages/extension/test/harness_switch.test.ts
@@ -0,0 +1,172 @@
+import { describe, it, expect, vi } from "vitest";
+import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import {
+  harnessSwitchFile,
+  harnessOptionsFile,
+  readHarnessSwitchState,
+  writeHarnessReady,
+  writeHarnessOptionsFile,
+  watchHarnessSwitch,
+} from "../src/harness_switch";
+import { harnessMenu } from "../src/harness";
+
+// ============================================================================
+// #1549 — the harness handshake, the solver-mode file contract's twin. The
+// engine route POSTs {harness, status:"switching"}; the extension watcher
+// performs the real switch (the registry gate, the setting persist, the
+// server restart) and only then settles status:"ready" — at the harness that
+// ACTUALLY took effect, which is the previous one when the switch was refused.
+// ============================================================================
+
+describe("harness handshake files", () => {
+  it("harnessSwitchFile and harnessOptionsFile live in the ops dir, overridable for tests", () => {
+    const dir = mkdtempSync(join(tmpdir(), "hw-"));
+    expect(harnessSwitchFile(dir)).toBe(join(dir, "harness.json"));
+    expect(harnessOptionsFile(dir)).toBe(join(dir, "harness-options.json"));
+  });
+
+  it("readHarnessSwitchState defaults opencode/ready; tolerant of corrupt and off-shape files", () => {
+    const dir = mkdtempSync(join(tmpdir(), "hw-"));
+    const f = join(dir, "harness.json");
+    expect(readHarnessSwitchState(f)).toEqual({ harness: "opencode", status: "ready" });
+    writeFileSync(f, "not json {{{");
+    expect(readHarnessSwitchState(f)).toEqual({ harness: "opencode", status: "ready" });
+    writeFileSync(f, JSON.stringify({ harness: 42, status: "weird" }));
+    expect(readHarnessSwitchState(f)).toEqual({ harness: "opencode", status: "ready" });
+  });
+
+  it("the ENGINE's switching write ({harness, status:switching}) is what the watcher reads", () => {
+    const dir = mkdtempSync(join(tmpdir(), "hw-"));
+    const f = join(dir, "harness.json");
+    writeFileSync(f, JSON.stringify({ harness: "telaio", status: "switching" }));
+    expect(readHarnessSwitchState(f)).toEqual({ harness: "telaio", status: "switching" });
+  });
+
+  it("writeHarnessReady round-trips with a switched_at stamp", () => {
+    const dir = mkdtempSync(join(tmpdir(), "hw-"));
+    const f = join(dir, "harness.json");
+    writeHarnessReady("telaio", f);
+    const parsed = JSON.parse(readFileSync(f, "utf8")) as Record<string, unknown>;
+    expect(parsed.harness).toBe("telaio");
+    expect(parsed.status).toBe("ready");
+    expect(typeof parsed.switched_at).toBe("string");
+    expect(readHarnessSwitchState(f)).toEqual({ harness: "telaio", status: "ready" });
+  });
+
+  it("writeHarnessOptionsFile publishes the registry menu verbatim, creating the dir", () => {
+    const dir = join(mkdtempSync(join(tmpdir(), "hw-")), "nested");
+    const menu = harnessMenu({ current: "opencode", entitlements: [], settingsBag: { opencodeBinary: "", telaioBinary: "", telaioAppDir: "" } });
+    writeHarnessOptionsFile(menu, join(dir, "harness-options.json"));
+    expect(JSON.parse(readFileSync(join(dir, "harness-options.json"), "utf8"))).toEqual(menu);
+  });
+});
+
+describe("watchHarnessSwitch", () => {
+  it("fires once per switching request and settles ready at the harness onSwitch reports", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "hw-"));
+    const f = join(dir, "harness.json");
+    writeFileSync(f, JSON.stringify({ harness: "telaio", status: "switching" }));
+    const calls: string[] = [];
+    let release!: () => void;
+    const gate = new Promise<void>((r) => (release = r));
+    const w = watchHarnessSwitch(
+      async (harness) => {
+        calls.push(harness);
+        await gate;
+        return harness;
+      },
+      f,
+      20,
+    );
+    await new Promise((r) => setTimeout(r, 120));
+    expect(calls).toEqual(["telaio"]);
+    release();
+    await new Promise((r) => setTimeout(r, 120));
+    expect(readHarnessSwitchState(f)).toEqual({ harness: "telaio", status: "ready" });
+    w.dispose();
+  });
+
+  it("the busy latch holds — a slow switch is never re-entered by the next tick", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "hw-"));
+    const f = join(dir, "harness.json");
+    writeFileSync(f, JSON.stringify({ harness: "telaio", status: "switching" }));
+    const calls: string[] = [];
+    const w = watchHarnessSwitch(
+      async (harness) => {
+        calls.push(harness);
+        await new Promise((r) => setTimeout(r, 300));
+        return harness;
+      },
+      f,
+      20,
+    );
+    await new Promise((r) => setTimeout(r, 150));
+    expect(calls).toEqual(["telaio"]);
+    w.dispose();
+  });
+
+  it("a REFUSED switch settles ready at the harness onSwitch returns — the honest state, never the refused one", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "hw-"));
+    const f = join(dir, "harness.json");
+    writeFileSync(f, JSON.stringify({ harness: "telaio", status: "switching" }));
+    const w = watchHarnessSwitch(
+      async () => "opencode", // the watcher refuses: settle at the CURRENT harness
+      f,
+      20,
+    );
+    await new Promise((r) => setTimeout(r, 120));
+    expect(readHarnessSwitchState(f)).toEqual({ harness: "opencode", status: "ready" });
+    w.dispose();
+  });
+
+  it("a failing onSwitch settles ready at the CURRENT default rather than lying about the switch", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "hw-"));
+    const f = join(dir, "harness.json");
+    writeFileSync(f, JSON.stringify({ harness: "telaio", status: "switching" }));
+    const w = watchHarnessSwitch(
+      async () => {
+        throw new Error("restart failed");
+      },
+      f,
+      20,
+    );
+    await new Promise((r) => setTimeout(r, 120));
+    // the solver-mode watcher settles ready at the REQUESTED mode on failure;
+    // harness switching has a cheaper truth — the setting is unchanged, so the
+    // file reads the still-current default. Never a lie we can't tell.
+    expect(readHarnessSwitchState(f)).toEqual({ harness: "opencode", status: "ready" });
+    w.dispose();
+  });
+
+  it("an already-ready file never fires", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "hw-"));
+    const f = join(dir, "harness.json");
+    writeHarnessReady("opencode", f);
+    const onSwitch = vi.fn(async (h: string) => h);
+    const w = watchHarnessSwitch(onSwitch, f, 20);
+    await new Promise((r) => setTimeout(r, 120));
+    expect(onSwitch).not.toHaveBeenCalled();
+    w.dispose();
+  });
+
+  it("creates the ops dir when writing ready into a missing tree", () => {
+    const dir = join(mkdtempSync(join(tmpdir(), "hw-")), "missing", "ops");
+    writeHarnessReady("opencode", join(dir, "harness.json"));
+    expect(readHarnessSwitchState(join(dir, "harness.json"))).toEqual({ harness: "opencode", status: "ready" });
+  });
+
+  it("watchHarnessSwitch tolerates a missing file between ticks (the pre-boot state)", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "hw-"));
+    const f = join(dir, "harness.json");
+    const onSwitch = vi.fn(async (h: string) => h);
+    const w = watchHarnessSwitch(onSwitch, f, 20);
+    await new Promise((r) => setTimeout(r, 80));
+    expect(onSwitch).not.toHaveBeenCalled();
+    writeFileSync(f, JSON.stringify({ harness: "opencode", status: "switching" }));
+    await new Promise((r) => setTimeout(r, 120));
+    expect(onSwitch).toHaveBeenCalledWith("opencode");
+    w.dispose();
+  });
+});

From a22007ee1a4badfca0d3fbc8368d8fcab06a6e08 Mon Sep 17 00:00:00 2001
From: Aaron Trowbridge <aaron.j.trowbridge@gmail.com>
Date: Sat, 26 Sep 2026 07:53:00 +0200
Subject: [PATCH 2/3] =?UTF-8?q?fix(service):=20forward=20/amicode/harness?=
 =?UTF-8?q?=20to=20the=20engine-owned=20route=20=E2=80=94=20the=20composer?=
 =?UTF-8?q?=20control's=20seam=20(#1549)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Live-test finding on the reference fleet (PR #1550): the app fetches
GET /amicode/harness at its panel origin — the service — whose fork-parity
discipline 404s every unmatched /amicode/* path without proxying, making the
engine-owned route unreachable from the app in EVERY topology, local mode
included. The control rendered nothing, exactly per its own degradation
comment. One named exception: /amicode/harness GET+POST forwards to the
engine when bound (the route's owner — forwarding, not laundering); an
unbound engine or a stock engine keeps the honest failure and the control's
hide-on-absent degradation. Everything else under /amicode/* keeps the
discipline. Tests pin all three seams: the menu fetch, the switch POST, the
narrow-exception 404.
---
 .../extension/src/amicode_service/server.ts   | 17 ++++++
 .../test/amicode_service_engine_proxy.test.ts | 58 ++++++++++++++++++-
 2 files changed, 74 insertions(+), 1 deletion(-)

diff --git a/packages/extension/src/amicode_service/server.ts b/packages/extension/src/amicode_service/server.ts
index 4e1724c71..51e14b045 100644
--- a/packages/extension/src/amicode_service/server.ts
+++ b/packages/extension/src/amicode_service/server.ts
@@ -245,6 +245,23 @@ export class AmicodeServiceServer {
       // proxying them would just launder our 404) → the app shelf → the
       // engine proxy.
       if (url.pathname === "/amicode" || url.pathname.startsWith("/amicode/")) {
+        // #1549 (live-test finding, PR #1550): ONE named exception to the
+        // fork-parity 404 — /amicode/harness is an ENGINE-OWNED route (the
+        // overlay's server/amicode/harness.ts: the composer control's GET,
+        // the switch's POST). The app reaches it at its panel origin, which
+        // IS this service — proxying these two methods to the engine (when
+        // bound) is forwarding to the route's owner, not laundering a 404;
+        // when the engine is not bound (or a stock engine without the route
+        // answers) the honest failure surfaces, and the control's own
+        // "route absent → stays hidden" degradation holds. Everything else
+        // under /amicode/* keeps the discipline below.
+        if (
+          url.pathname === "/amicode/harness" &&
+          (req.method === "GET" || req.method === "POST") &&
+          this.engineProxy?.handle(req, res)
+        ) {
+          return;
+        }
         send({ status: 404, body: JSON.stringify({ ok: false, error: `no route: ${req.method} ${url.pathname}` }) });
         return;
       }
diff --git a/packages/extension/test/amicode_service_engine_proxy.test.ts b/packages/extension/test/amicode_service_engine_proxy.test.ts
index d505b4364..25a278aaa 100644
--- a/packages/extension/test/amicode_service_engine_proxy.test.ts
+++ b/packages/extension/test/amicode_service_engine_proxy.test.ts
@@ -36,6 +36,28 @@ async function startMockEngine(): Promise<{ hits: RecordedHit[]; url: string; st
         res.end(JSON.stringify({ ok: true, engine: true, sessions: [] }));
         return;
       }
+      // #1549 (the harness seam): the engine-owned route the service
+      // forwards for the composer control — GET serves the registry view,
+      // POST records the switch request.
+      if (req.method === "GET" && req.url === "/amicode/harness") {
+        res.writeHead(200, { "content-type": "application/json" });
+        res.end(
+          JSON.stringify({
+            harness: "opencode",
+            status: "ready",
+            options: [
+              { id: "opencode", displayName: "opencode (default)", state: "ready", detail: "mock", disabled: false },
+              { id: "telaio", displayName: "telaio", state: "needs-setup", detail: "mock", disabled: true, reason: "not installed" },
+            ],
+          }),
+        );
+        return;
+      }
+      if (req.method === "POST" && req.url === "/amicode/harness") {
+        res.writeHead(200, { "content-type": "application/json" });
+        res.end(JSON.stringify({ ok: true, harness: JSON.parse(body || "{}").harness ?? "opencode", status: "switching" }));
+        return;
+      }
       if (req.method === "POST" && req.url === "/echo") {
         res.writeHead(200, { "content-type": String(req.headers["content-type"] ?? "text/plain") });
         res.end(body);
@@ -144,9 +166,12 @@ describe("amicode service — engine proxy (transparent passthrough to the spawn
   it("precedence: an exact /amicode/* route never reaches the proxy, and a static shelf hit never reaches the proxy", async () => {
     // /amicode/* is the service's OWN namespace — the mock engine must never
     // see it (a proxied /amicode/* would launder our route table upstream).
+    // #1549's named exception: /amicode/harness GET+POST IS forwarded (the
+    // engine-owned route — see the dedicated tests below); every OTHER
+    // /amicode/* path keeps this discipline.
     const route = await fetch(base + "/amicode/profile", { headers: { Authorization: engineAuth } });
     expect(route.status).toBe(200);
-    expect(engine.hits.some((h) => h.url.startsWith("/amicode")), "no /amicode/* hit may reach the engine").toBe(false);
+    expect(engine.hits.some((h) => h.url.startsWith("/amicode/")), "no /amicode/* hit may reach the engine").toBe(false);
     // A static asset is served by the shelf — the engine never sees it.
     const asset = await fetch(base + "/assets/app.js", { headers: { Authorization: engineAuth } });
     expect(asset.status).toBe(200);
@@ -155,6 +180,37 @@ describe("amicode service — engine proxy (transparent passthrough to the spawn
     expect(engine.hits.some((h) => h.url.startsWith("/assets")), "no /assets hit may reach the engine").toBe(false);
   });
 
+  it("#1549 the harness seam: GET /amicode/harness forwards to the ENGINE-owned route (the composer's menu fetch)", async () => {
+    // The composer control fetches this at its panel origin — the service —
+    // so the service must reach the route's owner. Without this forwarding
+    // the control renders nothing (the live-test finding on PR #1550).
+    const r = await fetch(base + "/amicode/harness", { headers: { Authorization: engineAuth } });
+    expect(r.status).toBe(200);
+    const menu = (await r.json()) as { harness: string; options: { id: string; disabled: boolean }[] };
+    expect(menu.harness).toBe("opencode");
+    expect(menu.options.map((o) => o.id)).toEqual(["opencode", "telaio"]);
+    expect(menu.options[1].disabled).toBe(true);
+    expect(engine.hits.some((h) => h.url === "/amicode/harness" && h.method === "GET"), "the menu fetch reached the engine").toBe(true);
+  });
+
+  it("#1549 the harness seam: POST /amicode/harness forwards too (the switch write path)", async () => {
+    const r = await fetch(base + "/amicode/harness", {
+      method: "POST",
+      headers: { Authorization: engineAuth, "content-type": "application/json" },
+      body: JSON.stringify({ harness: "opencode" }),
+    });
+    expect(r.status).toBe(200);
+    const answer = (await r.json()) as { status: string };
+    expect(answer.status).toBe("switching");
+    expect(engine.hits.some((h) => h.url === "/amicode/harness" && h.method === "POST"), "the switch POST reached the engine").toBe(true);
+  });
+
+  it("#1549 the exception is NARROW: an unmatched /amicode/* path still 404s at the service and never reaches the engine", async () => {
+    const r = await fetch(base + "/amicode/no-such-route", { headers: { Authorization: engineAuth } });
+    expect(r.status).toBe(404);
+    expect(engine.hits.some((h) => h.url.startsWith("/amicode/no-such-route")), "the unmatched path must never reach the engine").toBe(false);
+  });
+
   it("SSE (/event) streams UNBUFFERED through the proxy (chunks arrive as the engine sends them)", async () => {
     const r = await fetch(base + "/event", { headers: { Authorization: engineAuth } });
     expect(r.status).toBe(200);

From 0186a8c28032e8de556ae29bed196dfc84b41211 Mon Sep 17 00:00:00 2001
From: Aaron Trowbridge <aaron.j.trowbridge@gmail.com>
Date: Sun, 27 Sep 2026 10:24:43 +0200
Subject: [PATCH 3/3] fix(app): the harness select renders RIGHT of the effort
 select (#1549)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Live-test layout ruling from the reference fleet: agent → model → effort →
harness. The first-in-row placement displaced the trio's reading order and
read as a replacement of the agent select; the harness select now renders
immediately after the degraded wrapper — right of the effort/variant select,
outside the wrapper so it stays clickable under a non-opencode harness (it is
the way back). Manifest refreshed in the same commit (the discipline).
---
 packages/app-bundle/manifest.json             |  4 ++--
 .../src/v2/components/prompt-input/index.tsx  | 24 ++++++++++++-------
 2 files changed, 18 insertions(+), 10 deletions(-)

diff --git a/packages/app-bundle/manifest.json b/packages/app-bundle/manifest.json
index b26f2b0d9..92d85d165 100644
--- a/packages/app-bundle/manifest.json
+++ b/packages/app-bundle/manifest.json
@@ -855,7 +855,7 @@
     "packages/sdk/js/src/v2/gen/sdk.gen.ts": "6610638b4fb71bac498da98d232ef9adcd4b011b63e5e81a63fc6dc20d311b17",
     "packages/sdk/js/src/v2/gen/types.gen.ts": "0c23b262085d1e14b89bd03292a380c9ec8b52e66c4308304a05173362b79339",
     "packages/session-ui/src/v2/components/prompt-input/attachments.ts": "ff66078f2edc9a67a4df0d7dfd76a49be5eab27ac332b303f3412721ef7268ea",
-    "packages/session-ui/src/v2/components/prompt-input/index.tsx": "811ebe3d4f6ba6318d3bf3efbac678d4d0484f83929b8f8ae1b7af1bc29911f4",
+    "packages/session-ui/src/v2/components/prompt-input/index.tsx": "098bf84bf22573fcab2826a827e6789d41ad660545a0364ffb4a77cda5e01b30",
     "packages/opencode/src/server/routes/instance/httpapi/server.ts": "8a8e47c2242bc61be078c2fb97ecaa37ebe45cb410b95819102731b52f2b3c31",
     "packages/opencode/src/server/routes/instance/httpapi/groups/experimental.ts": "944a0aee215a917e867fd9482f3c2bd40f49082bd3174c8a7d967ca40e34ec15",
     "packages/opencode/src/server/routes/instance/httpapi/groups/file.ts": "ed165131c62eeb29375db39edf89db8f87488e24ef99fc6f2cf19705ba35751a",
@@ -881,7 +881,7 @@
     "packages/ui/src/v2/components/text-shimmer-v2.tsx"
   ],
   "exceptions": [],
-  "extracted_at": "2026-09-24T21:16:08.091Z",
+  "extracted_at": "2026-09-27T08:23:44.235Z",
   "per_package": {
     "packages/app": {
       "A": 192,
diff --git a/packages/app-bundle/overlay/packages/session-ui/src/v2/components/prompt-input/index.tsx b/packages/app-bundle/overlay/packages/session-ui/src/v2/components/prompt-input/index.tsx
index e939e2993..67bfdbc6f 100644
--- a/packages/app-bundle/overlay/packages/session-ui/src/v2/components/prompt-input/index.tsx
+++ b/packages/app-bundle/overlay/packages/session-ui/src/v2/components/prompt-input/index.tsx
@@ -42,11 +42,13 @@ export type PromptInputV2Props = {
   class?: string
   modelControl?: JSX.Element
   /**
-   * Optional control rendered FIRST in the bottom row's control group,
-   * before agent/model/variant (amicode#1549: the harness switcher — the
-   * outermost context the composer serves). Follows the modelControl
-   * optional-control pattern: pass `undefined` and nothing renders — the
-   * row's layout does not shift.
+   * Optional control rendered to the RIGHT of the effort/variant select —
+   * after agent/model/variant (amicode#1549: the harness switcher reads as
+   * the outermost context, positioned right of the trio per the live-test
+   * layout ruling). Outside the degraded wrapper so it stays clickable under
+   * a non-opencode harness. Follows the modelControl optional-control
+   * pattern: pass `undefined` and nothing renders — the row's layout does
+   * not shift.
    */
   harnessControl?: JSX.Element
   /**
@@ -235,9 +237,6 @@ export function PromptInputV2(props: PromptInputV2Props) {
               onContext={props.controller.openContext}
               onShell={props.controller.openShell}
             />
-            <Show when={props.harnessControl} keyed>
-              {(control) => control}
-            </Show>
             <div
               class={props.harnessDegraded ? "flex min-w-0 flex-1 items-center gap-1 opacity-40 pointer-events-none" : "contents"}
               title={props.harnessDegraded ? "Not accepted by this harness" : undefined}
@@ -276,6 +275,15 @@ export function PromptInputV2(props: PromptInputV2Props) {
                 )}
               </Show>
             </div>
+            {/* amicode#1549: the harness select renders to the RIGHT of the
+                effort/variant select — the outermost context read right-to-left
+                after the trio, NOT first-in-row (the live-test layout ruling:
+                agent → model → effort → harness). Deliberately OUTSIDE the
+                degraded wrapper: under a telaio harness the trio dims inert but
+                the harness select must stay clickable — it is the way back. */}
+            <Show when={props.harnessControl} keyed>
+              {(control) => control}
+            </Show>
           </div>
           <Show when={props.trailingControl} keyed>
             {(control) => <div class="mr-1 flex items-center">{control}</div>}