create-walle 0.10.2 → 0.10.3

package/template/coding-task-manager/lib/opencode-launch-model.js

@@ -0,0 +1,471 @@
+'use strict';
+
+// The never-prompted OpenCode 1.x lead-model switch (docs/opencode-lead-and-delegate-model-
+// selection-2026-10-28.html §5 R-2/R-4/R-5/R-7/R-8/R-9, §6.3, §8 WP-1).
+//
+// Why this is a SEPARATE controller and not a branch of lib/lead-model-switch.js: the journaled
+// Claude/Codex machine is built around an owner tuple, a provider thread and a history handoff.
+// An OpenCode 1.x tab that has never been prompted has NONE of those -- its session does not exist
+// yet (probe P-9), the owner is null and the resume id is empty -- so it is a distinct request kind,
+// `launch_model`, guarded by the process generation instead of `expected_owner` (R-3). The switch is
+// park -> fresh relaunch with `--model provider/model` (R-2, probe P-8), and it settles only on an
+// `opencode:message` observation carrying the requested model (R-7) -- never on argv, never on
+// `session.model` alone.
+//
+// What it deliberately does NOT do:
+//   - a v2 binary keeps its `--model`-free argv (R-8): the 2.x TUI rejects the flag (probe P-12), so
+//     its target rides the inline config + the CTM 2.x plugin's `switch_model` instead (WP-2/WP-4).
+//   - effort (R-9): OpenCode 1.x has no `--variant` on the TUI argv.
+//
+// Revision 2 (opencode-v2-model-switch-standalone-plugin-2026-10-30.html §5.1 R-9, §6.7): a tab WITH a
+// resume id is NO LONGER refused. TUI 1.x still keeps the model its last user message recorded and
+// still ignores `--model` on a resume (probe P-7, upstream #53806), but a server plugin's
+// `chat.message` hook CAN rewrite `output.message.model` (P-V2/P-V4). So a prompted v1 tab switches by
+// the SAME park + resume relaunch as Claude/Codex, with `lib/opencode-v1-plugin/model-carrier.mjs`
+// added to that one relaunch's inline config and the target riding the spawn env (subagent-pick.js's
+// opencodeV1CarrierEnv). Settlement is unchanged (R-5).
+//
+// Revision 3 (opencode-v2-model-switch-standalone-plugin-2026-10-30.html §5.1 R-4/R-5, §8 WP-4): the
+// SAME park + resume relaunch now serves an OpenCode 2.x tab. Its target rides the launch's inline
+// config `model` and the CTM 2.x plugin's `switch_model` (subagent-pick.js's opencodeV2PluginEnv) --
+// never a flag, since the 2.x TUI rejects `--model`. A v2 tab with no resume id is a fresh relaunch.
+//
+// It reuses the SAME `park` and `restore` primitives the journaled machine uses (the runtime passes
+// the same two lambdas), so a relaunch is one park and one restore, exactly as Claude's is.
+
+const crypto = require('node:crypto');
+const { publicSessionModelRequest } = require('./session-model-action-preconditions');
+const { leadWireAgent } = require('./lead-wire-agent');
+const { OPENCODE_LEAD_MODEL_REF } = require('./session-create/opencode-lead-provider');
+
+const SESSION_NOT_FOUND = 'session_not_found';
+const FLIGHT_KEY = 'relaunching';
+const MAX_MODEL_ID_LENGTH = 200;
+const MAX_ROUTE_ID_LENGTH = 200;
+const MAX_CLIENT_REQUEST_ID_LENGTH = 128;
+
+// The sentence each refusal carries, so every client shows a reason instead of a bare HTTP status
+// (the shared presenter prefers its own sentence for a code it knows, then this `message`).
+const REFUSAL_MESSAGES = Object.freeze({
+  invalid_request_kind: 'This OpenCode tab can only switch at launch; reopen the model picker and try again.',
+  invalid_route_id: 'The gateway route this pick carried was not usable. Reopen the model picker and try again.',
+  lead_route_invalid: 'That gateway route is not available for this lead right now.',
+  model_owner_changed: 'This OpenCode tab restarted since the picker opened. Reopen the picker and try again.',
+  lead_switch_busy: 'OpenCode is busy right now, so nothing was restarted. Try again in a moment.',
+  lead_switch_in_flight: 'A model switch for this tab is already running.',
+  opencode_catalog_unavailable: 'OpenCode could not list its models, so nothing was restarted.',
+  lead_switch_park_failed: 'CTM could not stop this OpenCode tab to restart it, so it keeps its current model.',
+  lead_switch_restore_failed: 'OpenCode did not restart on the new model.',
+  lead_switch_not_cancellable: 'There is no pending model switch to cancel.',
+});
+// Park refusals that only mean "not right now" (the journaled machine requeues these, lib/lead-model-switch.js
+// REQUEUE_PARK_CODES): a busy/protected tab or the post-boot restore window. A pinned tab, a draft or a
+// non-resumable tab is a real refusal and is reported as such.
+const TRANSIENT_PARK_CODES = new Set(['session_protected', 'park_race_protected']);
+const NON_TRANSIENT_PROTECTIONS = new Set(['pinned', 'draft', 'not-resumable']);
+
+function refusal(status, code, extra = {}) {
+  const message = REFUSAL_MESSAGES[code];
+  return { ok: false, status, code, ...(message ? { message } : {}), ...extra };
+}
+
+// The session's observed model in the SAME `provider/model` spelling a catalog row carries.
+// `session.model_id` may already be qualified (`moonshotai/kimi-k3`) or bare (`kimi-k3`) with the
+// provider kept separately; only the bare form is qualified here.
+function observedModelValue(session) {
+  const raw = String((session && session.model_id) || '').trim();
+  if (!raw) return '';
+  if (raw.includes('/')) return raw;
+  const provider = String((session && session.model_provider) || '').trim();
+  return provider ? `${provider}/${raw}` : raw;
+}
+
+/**
+ * @param {object} deps
+ * @param {(id: string) => ({ agent: string|null, resumeId?: string, live?: boolean, processGeneration?: number }|null)} deps.getSessionInfo
+ * @param {(id: string) => (object|null)} deps.getSession   the live session object (model_id/model_provider/model_source/model_observed_at)
+ * @param {(opts: { bin: string, env: object }) => Promise<object|null>} deps.opencodeVersion
+ * @param {(opts: { bin: string, env: object }) => Promise<object[]>} deps.listModels  `opencodeCatalog`
+ * @param {(id: string, opts: object) => Promise<object>} deps.park   the runtime's parkSession lambda
+ * @param {(id: string, opts: object) => Promise<boolean>} deps.restore the runtime's restore lambda
+ * @param {(id: string) => Promise<boolean>} deps.isIdle
+ * @param {(frame: object) => void} deps.broadcast
+ * @param {(agent: string, routeId: string, modelId: string, sessionId: string) => Promise<object>} [deps.resolveLeadRoute]
+ *   the runtime's shared routed-target resolver (the SAME lambda the journaled machine calls): it logs
+ *   refusals and returns `{ ok:true, display, contextWindow, deployment, profileFingerprint, … }` or
+ *   `{ ok:false, reason, message }`.
+ * @param {(sessionId: string) => (object|null)} [deps.getLeadRoute]  the session's stored lead-route row, or null.
+ * @param {(sessionId: string, agent: string, route: object|null) => Promise<void>} [deps.persistLeadRoute]
+ *   writes (route) or clears (null) the session's lead-route row — the journaled machine's own lambda.
+ * @param {(id: string, kind: string, detail: object) => void} [deps.diagnostic]
+ * @param {() => number} [deps.now]
+ * @param {() => string} [deps.newId]
+ */
+function createOpencodeLaunchModel({
+  getSessionInfo, getSession, opencodeVersion, listModels,
+  park, restore, isIdle, broadcast, diagnostic = null,
+  resolveLeadRoute = null, getLeadRoute = null, persistLeadRoute = null,
+  now = Date.now, newId = () => crypto.randomUUID(),
+} = {}) {
+  // One entry per session: a later request for the same tab REPLACES the previous one (terminal or
+  // not), so the map is bounded by the number of live OpenCode tabs.
+  const entries = new Map();
+
+  // The session's launch env, when the observation pipeline captured one. The version probe must ask
+  // the SAME `opencode` the tab launched -- a PATH-only lookup could answer for a different install.
+  function launchEnvFor(sessionId) {
+    const session = getSession(String(sessionId || ''));
+    const overrides = session && session._launchEnvOverrides;
+    if (overrides && typeof overrides === 'object' && !Array.isArray(overrides)) {
+      return { ...process.env, ...overrides };
+    }
+    return process.env;
+  }
+
+  async function readVersion(sessionId) {
+    try { return await opencodeVersion({ bin: 'opencode', env: launchEnvFor(sessionId) }); }
+    catch (error) {
+      void error; /* REPORT: an unusable probe is "unknown version", which is read-only (R-1) */
+      return null;
+    }
+  }
+
+  // The session's stored lead-route row, or null. Optional dep: a harness without it simply never has a
+  // route (the pre-WP-3 behaviour), and a throwing reader is treated as "no route" rather than a crash.
+  function readLeadRoute(sessionId) {
+    if (typeof getLeadRoute !== 'function') return null;
+    try { return getLeadRoute(String(sessionId || '')) || null; }
+    catch (error) { void error; return null; }
+  }
+
+  /**
+   * How this tab may switch, decided per launch from the installed binary (R-1), never guessed.
+   * @returns {Promise<{ line: 'v1'|'v2'|null, switch_mode: 'fresh_relaunch'|'resume_relaunch'|'read_only', reason: string, process_generation?: number }>}
+   */
+  async function sessionMode(sessionId) {
+    const info = getSessionInfo(String(sessionId || ''));
+    if (!info || info.agent !== 'opencode') return { line: null, switch_mode: 'read_only', reason: 'opencode_version_unknown' };
+    const version = await readVersion(sessionId);
+    if (!version || (version.line !== 'v1' && version.line !== 'v2')) {
+      return { line: null, switch_mode: 'read_only', reason: 'opencode_version_unknown' };
+    }
+    // `process_generation` is the CAS token the client echoes as `expected_process_generation` (R-3).
+    const processGeneration = Number(info.processGeneration || 0);
+    // R-4/R-5: a live 2.x tab switches by the SAME park + resume relaunch Claude/Codex and 1.x use. The
+    // target rides the launch's inline config `model` + plugin `switch_model` (WP-2/WP-4), never a flag:
+    // the 2.x TUI rejects `--model`, so nothing may reach a v2 argv. Without a resume id there is no
+    // conversation to continue, so the relaunch is fresh (the config model seeds it).
+    if (version.line === 'v2') {
+      return { line: 'v2', switch_mode: info.resumeId ? 'resume_relaunch' : 'fresh_relaunch', reason: '', process_generation: processGeneration };
+    }
+    // R-9: a prompted v1 tab switches by park + resume relaunch, with the model carrier riding that one
+    // relaunch (the TUI keeps sending its recorded model, and the carrier rewrites it). A native pick
+    // rides `launchModelOverride`; a routed pick rides `launchLeadRoute` (the fixed ref ctm-lead/lead).
+    if (info.resumeId) return { line: 'v1', switch_mode: 'resume_relaunch', reason: '', process_generation: processGeneration };
+    return { line: 'v1', switch_mode: 'fresh_relaunch', reason: '', process_generation: processGeneration };
+  }
+
+  function frame(entry) {
+    return { type: 'lead-model-request', request: publicSessionModelRequest(entry.req) };
+  }
+
+  function report(entry) {
+    if (typeof diagnostic !== 'function') return;
+    try {
+      diagnostic(entry.req.ctm_session_id, `opencode-launch-model-${entry.req.state}`, {
+        client_request_id: entry.req.client_request_id, model_id: entry.req.model_id,
+        reason: entry.req.reason, detail: entry.req.detail,
+      });
+    } catch { /* expected: a diagnostic sink failure must not change the switch verdict */ }
+  }
+
+  // A refusal that PRE-DATES the park: nothing was started, so the placeholder entry must not
+  // survive as a request the client would later read back as its own.
+  function withdraw(entry) {
+    if (entry && entry.controller) entry.controller.abort();
+    if (entry && entries.get(entry.req.ctm_session_id) === entry) entries.delete(entry.req.ctm_session_id);
+  }
+
+  function failEntry(entry, reason, detail) {
+    entry.req.state = 'failed';
+    entry.req.phase = 'failed';
+    entry.req.reason = reason;
+    entry.req.detail = String(detail || '').slice(0, 200);
+    entry.req.cancellable = false;
+    entry.req.settled_at = now();
+    report(entry);
+    broadcast(frame(entry));
+  }
+
+  /**
+   * Settle an `awaiting_turn` request from the session's own observation fields (R-7). Only an
+   * `opencode:message` observation NEWER than the relaunch counts; anything else leaves it waiting.
+   */
+  function settle(entry) {
+    if (!entry || entry.req.state !== 'awaiting_turn') return;
+    const session = getSession(entry.req.ctm_session_id);
+    if (!session) return;
+    if (String(session.model_source || '') !== 'opencode:message') return;
+    const at = Number(session.model_observed_at || 0);
+    if (!Number.isFinite(at) || at <= Number(entry.req.relaunched_at || 0)) return;
+    const observed = observedModelValue(session);
+    entry.req.observed_model = observed || null;
+    entry.req.observed_source = 'opencode:message';
+    entry.req.cancellable = false;
+    entry.req.settled_at = now();
+    // A routed target launches the fixed ref `ctm-lead/lead` (the gateway provider's alias), NOT the
+    // route's model id, so a routed request settles on the ref. Every other target settles on its own id.
+    const expected = entry.expectedObserved || entry.req.model_id;
+    if (observed && observed === expected) {
+      entry.req.state = 'succeeded';
+      entry.req.phase = 'succeeded';
+      entry.req.reason = null;
+      entry.req.detail = '';
+    } else {
+      entry.req.state = 'failed';
+      entry.req.phase = 'failed';
+      entry.req.reason = 'observed_model_mismatch';
+      entry.req.detail = '';
+    }
+    report(entry);
+    broadcast(frame(entry));
+  }
+
+  /**
+   * A never-prompted OpenCode 1.x switch request. Validations run in the design's order, and the
+   * entry is installed SYNCHRONOUSLY once the cheap refusals are out of the way, so two concurrent
+   * requests can never both reach `park` (exactly one park for N concurrent requests).
+   * @returns {Promise<{ ok:true, request: object }|{ ok:false, status:number, code:string }>}
+   */
+  async function request(sessionId, body) {
+    const id = String(sessionId || '');
+    const info = getSessionInfo(id);
+    // 1. This controller is only ever reached for an OpenCode tab; anything else is the runtime's
+    //    routing bug, and the honest answer is the same 404 the router would have produced.
+    if (!info || info.agent !== 'opencode') return refusal(404, SESSION_NOT_FOUND);
+    const input = body && typeof body === 'object' && !Array.isArray(body) ? body : {};
+    // 2. A default-scope write is not what this kind offers; a missing/unknown scope is invalid.
+    if (input.scope === 'session+default') return refusal(400, 'lead_default_unsupported', { agent: 'opencode' });
+    if (input.scope !== 'session') return refusal(400, 'invalid_scope');
+    // 3. The distinct request kind (R-3): a launch-time model, never an in-place switch.
+    if (input.request_kind !== 'launch_model') return refusal(400, 'invalid_request_kind');
+    // 4. Bounded target + idempotency key.
+    const modelId = input.model_id;
+    if (typeof modelId !== 'string' || !modelId.length || modelId.length > MAX_MODEL_ID_LENGTH) {
+      return refusal(400, 'invalid_model_id');
+    }
+    // 4b. An OPTIONAL gateway route id (WP-3). Present = a ROUTED target: the pick names one of Wall-E's
+    //     shared routed rows, proven by the same resolver the journaled machine uses, never the
+    //     `opencode models` catalog (a gateway model is not in the CLI's own list).
+    const routeId = input.route_id;
+    if (routeId != null && (typeof routeId !== 'string' || !routeId.length || routeId.length > MAX_ROUTE_ID_LENGTH)) {
+      return refusal(400, 'invalid_route_id');
+    }
+    const routed = typeof routeId === 'string' && routeId.length > 0;
+    const clientRequestId = input.client_request_id;
+    if (typeof clientRequestId !== 'string' || !clientRequestId.length
+        || clientRequestId.length > MAX_CLIENT_REQUEST_ID_LENGTH) {
+      return refusal(400, 'invalid_request');
+    }
+    // 5. Capability of the INSTALLED binary (R-1, R-4, R-5, R-8, R-9). A prompted v1 (R-9) or v2 (R-4)
+    //    tab switches by the SAME park + resume relaunch: its model rides the launch's carrier — the 1.x
+    //    plugin env, injected by the spawn path from `launchModelOverride` / `launchLeadRoute` — or the
+    //    2.x inline config + plugin `switch_model`, native and routed alike. Only an unreadable binary
+    //    has nothing to offer.
+    const storedRoute = readLeadRoute(id);
+    const mode = await sessionMode(id);
+    if (mode.switch_mode === 'read_only') return refusal(409, 'lead_switch_unsupported', { reason: mode.reason });
+    // 6. A parked/deferred tab has no process to relaunch.
+    if (!info.live) return refusal(409, 'lead_switch_unsupported', { reason: 'not_live' });
+    // 7. The process-generation CAS (R-3): the client's generation must still be the running one.
+    if (String(input.expected_process_generation) !== String(info.processGeneration)) {
+      return refusal(409, 'model_owner_changed');
+    }
+    // 8. Idempotent replay of the SAME request, or a switch already in flight.
+    const existing = entries.get(id);
+    if (existing && existing.req.client_request_id === clientRequestId) {
+      return { ok: true, request: publicSessionModelRequest(existing.req) };
+    }
+    if (existing && existing.req.state === FLIGHT_KEY) return refusal(409, 'lead_switch_in_flight');
+
+    const entry = {
+      req: {
+        id: newId(), ctm_session_id: id, client_request_id: clientRequestId, agent: 'opencode',
+        model_id: modelId, effort: null, effort_only: false, scope: 'session',
+        ...(routed ? { route_id: routeId } : {}),
+        state: FLIGHT_KEY, phase: FLIGHT_KEY, reason: null, detail: '', cancellable: false,
+        requested_at: now(), relaunched_at: null, settled_at: null,
+        observed_model: null, observed_source: null,
+      },
+      // A routed launch runs the fixed ref `ctm-lead/lead`, so its observation settles on the REF, not
+      // the route's model id (R-7). Private to the entry — never in the public request shape.
+      expectedObserved: routed ? OPENCODE_LEAD_MODEL_REF : modelId,
+      // The shared routed resolver requires an AbortSignal (its profile step throws "AbortSignal
+      // required" without one -- observed live, opencode-followups WP-6); a pre-park withdraw aborts it.
+      controller: new AbortController(),
+    };
+    // Installed SYNCHRONOUSLY, BEFORE the catalog/idle awaits below: a second request arriving while
+    // this one is between validation and park must see it (and be told `lead_switch_in_flight`).
+    // It is NOT broadcast yet: a refusal below withdraws it silently, so no viewer may have seen it.
+    entries.set(id, entry);
+
+    // 9. Target proof. A ROUTED target is proven by the SHARED resolver (existence / enabled / routable /
+    //    servable-for-this-agent + the model in Wall-E's coding catalog) — never the CLI's own list. A
+    //    NATIVE target is proven by the `opencode models` catalog (R-5): the CLI stores anything, so the
+    //    pick is what proves the id is real. An unreadable catalog is its own typed refusal, not an empty 400.
+    let resolved = null;
+    if (routed) {
+      if (typeof resolveLeadRoute !== 'function') {
+        withdraw(entry);
+        return refusal(400, 'lead_route_invalid', { reason: 'route_invalid', message: '' });
+      }
+      let v;
+      try { v = await resolveLeadRoute('opencode', routeId, modelId, id, { signal: entry.controller.signal }); }
+      catch (error) { v = { ok: false, reason: 'route_invalid', message: String(error && error.message || error).slice(0, 200) }; }
+      if (entries.get(id) !== entry) return refusal(409, 'lead_switch_in_flight');
+      if (!v || !v.ok) {
+        withdraw(entry);
+        return refusal(400, 'lead_route_invalid', { reason: (v && v.reason) || 'route_invalid', message: (v && v.message) || '' });
+      }
+      resolved = v;
+    } else {
+      let rows;
+      try {
+        rows = await listModels({ bin: 'opencode', env: launchEnvFor(id) });
+      } catch (error) {
+        void error; /* REPORT: the refusal below names the code; the cause never reaches the client */
+        withdraw(entry);
+        return refusal(503, 'opencode_catalog_unavailable');
+      }
+      if (entries.get(id) !== entry) return refusal(409, 'lead_switch_in_flight');
+      if (!Array.isArray(rows) || !rows.some((row) => String(row && row.value) === modelId)) {
+        withdraw(entry);
+        return refusal(400, 'lead_model_not_switchable', { model_id: modelId });
+      }
+    }
+    // 10. Relaunching WOULD interrupt a busy tab, so the same idle verdict Claude/Codex use applies.
+    const idle = await isIdle(id);
+    if (entries.get(id) !== entry) return refusal(409, 'lead_switch_in_flight');
+    if (idle !== true) {
+      withdraw(entry);
+      return refusal(409, 'lead_switch_busy');
+    }
+
+    // R-2/R-6: park, then relaunch with the model on the ONE launch's argv. No user config is written.
+    // A THROWN park/restore is a refusal too: leaving the entry in `relaunching` would block this tab
+    // forever (the in-flight guard), so every exit below is a terminal state.
+    let parked;
+    try { parked = await park(id, { manual: true, reason: 'model' }); }
+    catch (error) {
+      const code = String((error && error.message) || error || 'park_failed').slice(0, 200);
+      failEntry(entry, 'park_refused', code);
+      return refusal(409, 'lead_switch_park_failed', { park_code: 'park_threw' });
+    }
+    if (!parked || parked.ok === false) {
+      const code = String((parked && (parked.code || parked.reason)) || 'park_failed');
+      const protections = Array.isArray(parked && parked.protections) ? parked.protections : [];
+      if (TRANSIENT_PARK_CODES.has(code) && !protections.some((p) => NON_TRANSIENT_PROTECTIONS.has(p))) {
+        // Nothing was stopped: the tab is busy or inside CTM's post-boot restore window. Withdraw the
+        // never-broadcast entry and answer "busy", with the time the window ends when park knows it.
+        withdraw(entry);
+        const retryAt = Number(parked && parked.retryAt);
+        return refusal(409, 'lead_switch_busy', { park_code: code, protections,
+          ...(Number.isFinite(retryAt) && retryAt > 0 ? { retry_at: retryAt } : {}) });
+      }
+      failEntry(entry, 'park_refused', code);
+      // `code` is the refusal's own identity; the park's reason rides `park_code` (the same field
+      // name the journaled machine records), so neither can overwrite the other.
+      return refusal(409, 'lead_switch_park_failed', { park_code: code });
+    }
+    if (routed) entry.req.route_display = resolved.display || '';
+    let started;
+    // A NATIVE pick relaunches with `--model <id>`; a ROUTED pick hands the spawn path a `launchLeadRoute`
+    // object (gateway ref + env + configPatch), exactly as a routed Claude/Codex lead does. A native pick
+    // on a tab that HAS a stored route passes an EXPLICIT `launchLeadRoute: null`, so the spawn path clears
+    // the row instead of re-applying the route the user just left.
+    const restoreOpts = routed
+      ? { launchLeadRoute: {
+        routeId, model: modelId,
+        display: resolved.display || modelId,
+        contextWindow: resolved.contextWindow != null ? resolved.contextWindow : (resolved.deployment?.contextTokens ?? null),
+      } }
+      : (storedRoute ? { launchModelOverride: modelId, launchLeadRoute: null } : { launchModelOverride: modelId });
+    try { started = await restore(id, restoreOpts); }
+    catch (error) {
+      void error; /* REPORT: the failure path below records the terminal state */
+      started = false;
+    }
+    // The tab is parked: from here on every exit is a broadcast state, so the first frame viewers see
+    // is one that will be followed by its outcome (a refusal before this point broadcasts nothing).
+    broadcast(frame(entry));
+    if (started !== true) {
+      failEntry(entry, 'restore_failed', 'restore_refused');
+      return refusal(409, 'lead_switch_restore_failed');
+    }
+    entry.req.state = 'awaiting_turn';
+    entry.req.phase = 'awaiting_turn';
+    entry.req.relaunched_at = now();
+    entry.req.cancellable = true;
+    // The session's lead-route row follows the switch (WP-3), so the NEXT resume re-applies it: a routed
+    // target writes the row (the same field set the journaled machine persists) and a native target on a
+    // routed tab clears it. A write failure is REPORTED via `diagnostic` and never fails the switch — the
+    // relaunched process already carries the target.
+    if ((routed || storedRoute) && typeof persistLeadRoute === 'function') {
+      try {
+        if (routed) {
+          await persistLeadRoute(id, leadWireAgent('opencode'), {
+            routeId, model: modelId, display: resolved.display || modelId,
+            contextWindow: resolved.contextWindow != null ? resolved.contextWindow : (resolved.deployment?.contextTokens ?? null),
+            profileFingerprint: resolved.profileFingerprint || null,
+            factsRevision: resolved.deployment?.factsRevision || null,
+            processGeneration: resolved.processGeneration || null,
+            transitionId: null,
+          });
+        } else {
+          await persistLeadRoute(id, leadWireAgent('opencode'), null);
+        }
+      } catch (error) {
+        if (typeof diagnostic === 'function') {
+          try { diagnostic(id, 'opencode-launch-model-persist-route-failed', { message: String((error && error.message) || error).slice(0, 200) }); }
+          catch { /* expected: a diagnostic sink failure must not change the switch verdict */ }
+        }
+      }
+    }
+    broadcast(frame(entry));
+    return { ok: true, request: publicSessionModelRequest(entry.req) };
+  }
+
+  /** The public request for this tab, settled lazily (the poll path), or null. */
+  function get(sessionId) {
+    const entry = entries.get(String(sessionId || ''));
+    if (!entry) return null;
+    if (entry.req.state === 'awaiting_turn') settle(entry);
+    return publicSessionModelRequest(entry.req);
+  }
+
+  /** Cancelling an unconfirmed switch abandons the REQUEST; the relaunched process keeps running. */
+  function cancel(sessionId) {
+    const entry = entries.get(String(sessionId || ''));
+    if (!entry || entry.req.state !== 'awaiting_turn') {
+      return { ok: false, status: 409, code: 'lead_switch_not_cancellable' };
+    }
+    entry.req.state = 'cancelled';
+    entry.req.phase = 'cancelled';
+    entry.req.cancellable = false;
+    entry.req.settled_at = now();
+    broadcast(frame(entry));
+    return { ok: true, request: publicSessionModelRequest(entry.req) };
+  }
+
+  /**
+   * A model observation for this tab arrived (the runtime calls this on a status edge). Settles an
+   * `awaiting_turn` request from the session's own fields, so a switch completes without a poll.
+   */
+  function notifyObservation(sessionId) {
+    settle(entries.get(String(sessionId || '')));
+  }
+
+  return { request, get, cancel, sessionMode, notifyObservation };
+}
+
+module.exports = { createOpencodeLaunchModel, observedModelValue };

package/template/coding-task-manager/lib/opencode-v1-plugin/model-carrier.mjs

@@ -0,0 +1,35 @@
+// WP-5 (docs/opencode-v2-model-switch-standalone-plugin-2026-10-30.html §3.5 P-V2..P-V5, §5.1 R-9,
+// §5.2 D-9/D-10/D-11, §6.7): the OpenCode 1.x model carrier.
+//
+// A resumed 1.x TUI re-sends the model its conversation recorded on every prompt (the TUI syncs its
+// model from the last user message once per session, prompt/index.tsx:311-331), so `--model` on a
+// resume is ignored (round-1 P-7, upstream #53806). A SERVER plugin's `chat.message` hook can rewrite
+// `output.message.model` before the request is made, so this file is what carries a prompted tab's
+// switch: CTM adds this one file to the launch's inline `plugin` array and sets the target ref and the
+// resumed session id in the spawn env (`CTM_OPENCODE_SWITCH_MODEL`, `CTM_OPENCODE_SWITCH_SESSION`).
+//
+// The rewrite is NOT unconditional (P-V3/P-V4): the first model seen on the target session is `from`,
+// and only a prompt still arriving on `from` is rewritten. Any other model is a pick the user made in
+// the TUI itself, which wins — the carrier disarms for good rather than fighting it.
+//
+// Loaded by OpenCode 1.x under Bun: ESM, no imports. It NEVER throws — a carrier failure leaves the
+// prompt on its own model (the chip then never settles, R-5), which is strictly better than failing a
+// user's turn.
+export const CtmModelCarrier = async () => {
+  const target = process.env.CTM_OPENCODE_SWITCH_MODEL || '';      // 'provider/model' (first '/' splits)
+  const sessionID = process.env.CTM_OPENCODE_SWITCH_SESSION || '';
+  const cut = target.indexOf('/');
+  if (!sessionID || cut <= 0 || cut === target.length - 1) return {};
+  const providerID = target.slice(0, cut), modelID = target.slice(cut + 1);
+  let from = null, off = false;
+  return { 'chat.message': async (input, output) => {
+    try {
+      const m = output && output.message && output.message.model;
+      if (off || !m || !input || input.sessionID !== sessionID) return;
+      const key = m.providerID + '/' + m.modelID;
+      if (from === null) from = key;
+      if (key !== from) { off = true; return; }                  // the user picked in the TUI (P-V4)
+      output.message.model = { ...m, providerID, modelID };
+    } catch { /* expected: a carrier failure leaves the prompt on its own model; the chip never settles (R-5) */ }
+  } };
+};

package/template/coding-task-manager/lib/opencode-v2-plugin/server.js

@@ -0,0 +1,118 @@
+'use strict';
+// WP-2 (docs/opencode-v2-model-switch-standalone-plugin-2026-10-30.html §3.2 P-S7/P-S8, §5.1 R-3/R-4,
+// §5.2 D-12/D-13, §6.3 revision 3): the CTM OpenCode 2.x plugin. OpenCode 2.x loads a `plugins` entry
+// by DIRECTORY (a single file path is skipped, P-S7) and requires this module's `server.js`; the entry
+// shape that works is CommonJS (`module.exports` + `.default`, P-S3b), so this file is CommonJS even
+// though 1.x loads its plugin as ESM.
+//
+// It runs INSIDE OpenCode's private per-tab server (R-1), so it never requires a CTM module and never
+// throws: no imports, never awaits a post, aborts a request after 1500 ms, and is inert when the spawn
+// path did not pass a port or a session id (the 1.x plugin rules, lib/agent-hooks-opencode-plugin.js:6-8,
+// 30-40). Identity comes from ctx.options, filled by the spawn path from the SAME spawn env values the
+// 1.x plugin reads (CTM_PORT / CTM_SESSION_ID / CTM_MODEL_PROCESS_GENERATION).
+//
+// Three jobs (R-3):
+//   1. switch_model, once, in setup, BEFORE subscribing (D-12): ctx.session.switchModel({ sessionID,
+//      model: { providerID, id } }) applies the target to a session that already exists (P-S8c). On a
+//      never-prompted tab the call rejects Session.NotFoundError (P-S8a) -- the inline config model
+//      applies instead, so this is the expected fresh-tab case and stays silent. Any OTHER rejection is
+//      one line to stderr. The outcome is never posted: the next completed turn's model is the truth.
+//   2. turn state (D-13): only events whose sessionID is THIS tab's session id, one post per transition
+//      -- session.execution.started -> 'start' (busy once), any other session.execution.* -> 'stop'
+//      (the first end after a start). A child's execution events are ignored by construction (the
+//      session id check below), so a subagent's turn never posts start/stop for the tab.
+//      Routes /hook/opencode/start and /hook/opencode/stop are the 1.x ingress routes, unchanged.
+//   3. permission.asked -> 'waiting', permission.replied -> 'resumed' (OQ-2, cited @opencode/schema 2.2.5;
+//      WP-3b, OQ-5): 2.x has no permission.updated (D-6). Waiting is a status report only -- it does not
+//      touch the busy flag, so the turn-state transitions above are unchanged. Two pieces of state make
+//      the report exact:
+//        - children: a subagent (task tool) runs in its OWN session, and P-S11 observed on 2.2.4 that its
+//          ask carries the CHILD session id while its session.created carries data.parentID = the parent's
+//          id (both at the top level of data). So session.created builds a Set of descendant session ids
+//          (parentID is the tab's own id OR an id already in the set -- grandchildren included) BEFORE the
+//          own-session filter would drop them, and a permission event is accepted when its sessionID is
+//          the tab's own id or in that set. Without this a blocked subagent never shows "Needs you".
+//        - pending: the set of open ask ids (permission.asked.data.id). 'waiting' posts only on the
+//          empty -> non-empty edge and 'resumed' only when the set is empty again after removing
+//          permission.replied.data.requestID, so overlapping asks from the tab and its children yield one
+//          waiting/resumed pair; a requestID that was never seen removes nothing and the empty check
+//          still holds (the WP-3 reply-without-ask case).
+//      Routes /hook/opencode/waiting and /hook/opencode/resumed are the 1.x ingress routes
+//      (lib/agent-hooks-opencode-plugin.js:56-57), unchanged.
+
+// post(route): best effort, never awaited, never throws (a slow CTM must not stall the agent).
+function makePost(o, ctx) {
+  return (route) => {
+    try {
+      fetch('http://127.0.0.1:' + o.ctm_port + '/hook/opencode/' + route, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({
+          ctm_id: o.ctm_session_id,
+          process_generation: o.process_generation || undefined,
+          cwd: ctx.location && ctx.location.directory,
+          session_id: o.session_id,
+        }),
+        signal: AbortSignal.timeout(1500),
+      }).catch(() => { /* expected: a status report is best effort; a slow CTM must not stall the agent */ });
+    } catch (e) { /* expected: a status report is best effort; a slow CTM must not stall the agent */ }
+  };
+}
+
+async function setup(ctx) {
+  const o = (ctx && ctx.options) || {};
+  // 1. switch_model, once, before subscribing (P-S8c).
+  const sw = o.switch_model;
+  if (sw && typeof sw === 'object') {
+    try {
+      await ctx.session.switchModel(sw);
+    } catch (e) {
+      // P-S8a: a never-prompted tab rejects Session.NotFoundError and the config model applies instead.
+      if (!e || e._tag !== 'Session.NotFoundError') {
+        process.stderr.write('[ctm.status] switchModel failed: ' + String((e && e.message) || e) + '\n');
+      }
+    }
+  }
+  // 2. status: started by setup, never awaited by it; a missing port/id leaves the plugin inert.
+  if (!o.ctm_port || !o.ctm_session_id) return;
+  const post = makePost(o, ctx);
+  void (async () => {
+    try {
+      let busy = false;
+      const children = new Set(); // child (subagent) session ids under this tab, grandchildren included
+      const pending = new Set(); // open permission-ask ids (the tab's own and its children's)
+      for await (const ev of ctx.event.subscribe()) {
+        const data = ev && ev.data;
+        if (!data) continue;
+        const type = ev.type;
+        const sid = data.sessionID;
+        if (type === 'session.created') {
+          // P-S11 observed on 2.2.4: a child ask carries the child session id, and the child's
+          // session.created carries data.parentID = the parent's id. Track descendants BEFORE the
+          // own-session filter, which would otherwise drop the event (it is not the tab's own id).
+          if (data.parentID && sid && (data.parentID === o.session_id || children.has(data.parentID))) children.add(sid);
+          continue;
+        }
+        if (sid !== o.session_id && !children.has(sid)) continue;
+        if (type === 'session.execution.started') {
+          // Turn state is the tab's OWN session only: a child's execution events never post start/stop.
+          if (sid === o.session_id && !busy) { busy = true; post('start'); }
+        } else if (type === 'permission.asked') {
+          if (pending.size === 0) post('waiting'); // D-6: 2.x has no permission.updated; one pair per overlap
+          pending.add(data.id);
+        } else if (type === 'permission.replied') {
+          pending.delete(data.requestID); // unknown id: nothing to remove, the empty check below still holds
+          if (pending.size === 0) post('resumed');
+        } else if (typeof type === 'string' && type.startsWith('session.execution.')) {
+          // A turn end closes any ask left open (a reject/abort path that emits no permission.replied is
+          // unmeasured), so the NEXT turn's first ask posts 'waiting' again.
+          if (sid === o.session_id && busy) { busy = false; pending.clear(); post('stop'); }
+        }
+      }
+    } catch (e) { /* expected: the status loop is best effort; a broken stream never breaks the agent */ }
+  })();
+}
+
+const def = { id: 'ctm.status', setup };
+module.exports = def;
+module.exports.default = def;

package/template/coding-task-manager/lib/owner-action-manifest-data.json

@@ -3464,7 +3464,7 @@
     ],
     [
       "POST",
-      "/api/session/image-refs",
+      "/api/sessions/:p1/image-refs",
       "respond",
       "human",
       false