@te-river/opencode-team-mode 1.5.15 → 1.6.1

package/scripts/gen-v2-config.mjs

@@ -0,0 +1,304 @@
+#!/usr/bin/env node
+/**
+ * Project the team's roles AND slash commands into OpenCode v2 config files.
+ *
+ * A v2 plugin cannot create an agent — `AgentEditor` exposes only
+ * list/get/default/update/remove (docs/v2/build/plugins, Agent reference) — and
+ * `ctx.command.transform.add` was measured NOT to reach the UI on 2.0.16, so
+ * both have to live where the built-in Build and Plan agents do:
+ *
+ *   ~/.config/opencode/agents/<name>.md      frontmatter + body = system prompt
+ *   ~/.config/opencode/commands/<name>.md    frontmatter + body = prompt template
+ *
+ * Everything here is a projection of `src/agents.ts` / `src/commands.ts`
+ * through the built `dist/`, including the prompt strings, so the markdown
+ * cannot drift from what the v1 personality injects.
+ *
+ * ONE THING THIS CANNOT VERIFY: the v1 commands carry `agent: architect` (etc.)
+ * and that works on v1.  v2 documents `mode: subagent` as "runs ONLY in a child
+ * session through the subagent tool", so a command selecting a subagent-only
+ * role may not run as that role.  If the live host says so, the fix is one value
+ * in src/agents.ts — `mode: "all"` runs either way, and T3 ("only the lead
+ * dispatches") is held by the specialists' `subagent: deny` rule rather than by
+ * `mode`, so switching costs the picker five extra entries and nothing else.
+ *
+ * Usage:
+ *   node scripts/gen-v2-config.mjs [--dir <path>] [--print] [--force]
+ *
+ * `--dir` is the base; `agents/` and `commands/` are created under it.
+ * Refuses to touch a file it did not generate unless --force is given.
+ */
+
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs"
+import { join } from "node:path"
+import { homedir } from "node:os"
+
+const MARKER = "generated by @te-river/opencode-team-mode"
+
+const argv = process.argv.slice(2)
+const flag = (name) => argv.includes(`--${name}`)
+const opt = (name) => {
+  const i = argv.indexOf(`--${name}`)
+  return i >= 0 && argv[i + 1] && !argv[i + 1].startsWith("--") ? argv[i + 1] : undefined
+}
+
+const baseDir = opt("dir") ?? join(homedir(), ".config", "opencode")
+const printOnly = flag("print")
+const force = flag("force")
+
+const { agents } = await import(new URL("../dist/agents.js", import.meta.url).href)
+const { commands } = await import(new URL("../dist/commands.js", import.meta.url).href)
+const { triplesFromAgentPermission, V1_ONLY_TOOLS } = await import(
+  new URL("../dist/host/v2-permissions.js", import.meta.url).href
+)
+
+/** YAML is a superset of JSON, so a JSON scalar is a valid YAML scalar —
+ *  and the descriptions are full of em-dashes and colons that a hand-rolled
+ *  quote would get wrong. */
+const scalar = (v) => JSON.stringify(String(v))
+
+function agentFrontmatter(cfg, triples) {
+  const lines = [`---`, `# ${MARKER} — edit src/agents.ts and re-run the generator instead.`]
+  if (cfg.description) lines.push(`description: ${scalar(cfg.description)}`)
+  lines.push(`mode: ${scalar(cfg.mode ?? "subagent")}`)
+  if (cfg.color) lines.push(`color: ${scalar(cfg.color)}`)
+  if (triples.length) {
+    lines.push("permissions:")
+    for (const t of triples) {
+      lines.push(`  - action: ${scalar(t.action)}`)
+      lines.push(`    resource: ${scalar(t.resource)}`)
+      lines.push(`    effect: ${scalar(t.effect)}`)
+    }
+  }
+  lines.push("---", "")
+  return lines.join("\n")
+}
+
+/** v2's command markdown takes `description` / `agent` / `model` / `subagent` in
+ *  frontmatter and the template as the body — deliberately NO `template` key,
+ *  which the docs forbid because the body supplies it. */
+function commandFrontmatter(cfg) {
+  const lines = [`---`, `# ${MARKER} — edit src/commands.ts and re-run the generator instead.`]
+  if (cfg.description) lines.push(`description: ${scalar(cfg.description)}`)
+  if (cfg.agent) lines.push(`agent: ${scalar(cfg.agent)}`)
+  lines.push("---", "")
+  return lines.join("\n")
+}
+
+const body = (prompt) => {
+  const text = String(prompt ?? "").trimEnd()
+  // A body that opens with `---` would read as a second frontmatter block.
+  return text.startsWith("---") ? text.replace(/^---/, "\\---") : text
+}
+
+/**
+ * The personality fork, in one place.
+ *
+ * v2 does not register `tm_ptc_run` — the host's own `execute` (Code Mode)
+ * already runs "one program, N tool calls, zero round-trips, only the aggregate
+ * entering the context", and a live session proved the governed tm_* results
+ * still come back offloaded through it.  v1 has no Code Mode, so it keeps the
+ * tool and keeps these sentences untouched.
+ *
+ * A prompt that names a tool the model cannot call is not a style problem — it
+ * costs the round the mandate exists to save — so the v2 markdown says what v2
+ * can actually do.  Every key below MUST be found in the shared source or the
+ * generator fails: a silent no-op here would ship the v1 sentence to a v2 model
+ * and look like success.  `test-v2-adapter` group 8 pins both halves.
+ */
+const V2_TEXT = [
+  ["tm_ptc_run program, keeping only the handle.", "`execute` (the host's Code Mode tool) program, keeping only the handle."],
+  ["Batch the recon in one tm_ptc_run program", "Batch the recon in one `execute` program"],
+  ["batch recon via tm_ptc_run,", "batch recon via `execute`,"],
+  ["is ONE tm_ptc_run, not a chain.", "is ONE `execute` (Code Mode) call, not a chain."],
+  ["multi-file batch recon → tm_ptc_run (one program,", "multi-file batch recon → `execute` (one program,"],
+  ["your FIRST move is ONE tm_ptc_run program:", "your FIRST move is ONE `execute` (Code Mode) program:"],
+  ["## Recon batching (PTC-first)", "## Recon batching (Code Mode first)"],
+  ["Local-repo recon is PTC-first:", "Local-repo recon is Code-Mode-first:"],
+  ["cross-referencing searches → ONE tm_ptc_run program", "cross-referencing searches → ONE `execute` program"],
+  /*
+   * The delegation half of the lead prompt.  On v2 the host's tool is named
+   * `subagent` — measured, not inferred: a live dispatch reached
+   * `execute.before {tool:"subagent"}` and `permission.evaluate {action:"subagent"}`.
+   * A mandate that names `task` points at a tool the role cannot call, which costs
+   * the round it exists to save (the tm_ptc_run lesson, same shape).  And on v2
+   * `background` needs no operator flag — the plugin sets it on every dispatch —
+   * so the "pick the shape by rule" instruction is not a choice the model has.
+   */
+  ["## Delegation — the host's task tool, and what you do while it runs", "## Delegation — the host's subagent tool, and what you do while it runs"],
+  ["delegation goes through the host's `task` — governed, visible, killable.", "delegation goes through the host's `subagent` — governed, visible, killable."],
+  ["you will keep following up while they run → `task { background: true }`: the", "you will keep following up while they run → `subagent { background: true }`: the"],
+  ["`task`. Do not choose background when you would only park waiting for it.",
+   "`subagent`. On this host the plugin forces `background: true` on EVERY dispatch, so this is not a choice you make, and the operator flag v1 needed does not exist here."],
+  ["Background needs the operator flag `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true`;",
+   "Assume the card is asynchronous: say who is running instead of pretending to block."],
+  ["without it `task` only blocks, so say so rather than pretending to overlap.",
+   "There is no flag to check and no synchronous fallback to fall back on."],
+  ["a background `task` names its own session id", "a background `subagent` names its own session id"],
+  ["a synchronous `task` call, so chaining waits", "a synchronous `subagent` call, so chaining waits"],
+  ["blocking on `task`", "blocking on `subagent`"],
+  /*
+   * The file ladder (the tm_read / tm_grep / tm_bash retirement).  v2 does not
+   * register those three, so every sentence that routes a role through them has
+   * to name what is actually on the surface instead — and the native tools are
+   * NOT ungoverned here: `execute.after` offloads their oversized results, and
+   * the address / R6 red lines ride `permission.evaluate` (both landed BEFORE
+   * this fork, which is the ordering the retirement requires).
+   *
+   * Two words are host-vocabulary, not ours: v2 names the shell tool `shell`,
+   * and its `background` argument is documented on the native tool (AGENTS.md,
+   * "native shell … has background:true").  The pty line is rewritten around
+   * that, NOT around anything I have measured in a live v2 session — a v2
+   * session has yet to make a background shell call, and #8/#9 are where that
+   * gets checked.  Until then the sentence says only "returns at once".
+   */
+  ["tm_grep / tm_read first, a second lookup only for what it genuinely missed.", "grep / read first, a second lookup only for what it genuinely missed."],
+  ["All file reads / searches / enumeration go through tm_read / tm_grep / tm_bash.\nThe built-in read/grep/glob/list tools are removed from the tool surface —\nretrying them only wastes a turn.  Built-in bash exists only where granted\n(team / implementer / reviewer / tester run commands: build / test / git);\narchitect and researcher have no bash at all — one-off read-only commands\ngo through tm_bash or are reported as a gap.",
+   "File reads / searches / enumeration go through the built-in read / grep /\nglob tools — on this host they ARE the governed path: an oversized result comes\nback as a short preview plus a handle, and `tm_fetch` pages the rest, so a wide\ncall is cheap here and still the right move.  Built-in shell exists only where\ngranted (team / implementer / reviewer / tester run commands: build / test /\ngit); architect and researcher have no shell at all — a one-off read-only\ncommand they cannot run is reported as a gap, not retried."],
+  ["code search → tm_grep · enumeration and quick\n  probes → tm_bash · multi-file", "code search → grep · enumeration and quick\n  probes → glob / shell where granted · multi-file"],
+  ["use the **built-in bash** tool — not tm_bash.  tm_bash hard-blocks them with\nno dialog; built-in bash triggers the official confirmation dialog (once /\nalways / reject).  Dangerous commands (rm / git push / npm publish / etc.)\nalways trigger the dialog regardless of tool.",
+   "there is no second, ungoverned shell to fall back to on this host: the one\n**shell** tool IS the R6 surface, and its classifier only ever makes a rule\nstricter — an env dump or a delete asks the host, which opens its own dialog\n(once / always / reject).  Dangerous commands (rm / git push / npm publish /\netc.) ask regardless of what the config said."],
+  ["probes toward one goal — tm_read / tm_grep / tm_bash\nOR built-in bash alike — your FIRST move is ONE", "probes toward one goal — read / grep / glob / shell alike — your FIRST move is ONE"],
+  ["Plain shell probes the governed channel cannot run\n(e.g. env-path checks, which the tm_* channel hard-blocks by\ndesign) go as ONE compound built-in bash command (`a; b; c` in a\nsingle call)",
+   "Several cheap probes of one kind go as ONE compound `shell`\ncommand (`a; b; c` in a\nsingle call)"],
+  ["searches are PTC work;", "searches are one-program work;"],
+  ["(tm.read / tm.grep / tm.bash ride inside; ALWAYS `return` the", "(the built-in read / grep / shell tools are callable inside it; ALWAYS `return` the"],
+  ["(or one PTC program), never in two.", "(or one `execute` program), never in two."],
+  ["run one cheap tm_grep.  Do NOT pull big payloads", "run one cheap grep.  Do NOT pull big payloads"],
+  ["or tm_grep + tm_bash yourself)", "or grep + shell yourself)"],
+  ["into its OWN tm_pty session (returns at once, the user sees the terminal,\n  every start passes the official dialog) rather than being chained with\n  `;` behind one long bash call.  tm_pty returns no transcript — tee it to\n  a log and read that log when it reports exited.",
+   "into its OWN separate `shell` call rather than being chained with\n  `;` behind one long shell call — and when the step is genuinely slow, use\n  `shell {background:true}`: the ack gives a shell ID plus the file its output\n  streams to, and the host notifies on exit (do NOT poll for it).  Have it write\n  its own log file and read that log when it reports exited — do not re-run the\n  command to see its output."],
+  ["probes via bash where granted) BEFORE answering from memory.", "probes via shell where granted) BEFORE answering from memory."],
+  ["FIRST there, because that is the only path with the domain allowlist, the\nper-request dialog and the R6 red lines; an MCP fetcher of the same page\nsilently skips all three (and dumps raw HTML into your context).  Fall to a",
+   "FIRST there, because that is the only path with the address red line (no\nmetadata / private-range fetch) and the threshold offload; an MCP fetcher of the\nsame page silently skips both (and dumps raw HTML into your context).  Fall to a"],
+  ["- Files/docs → tm_read · code search →", "- Files/docs → read · code search →"],
+  ["  --help) → built-in bash where granted ·", "  --help) → `shell` where granted ·"],
+  ["## PTC batch orchestration", "## Batch orchestration (Code Mode first)"],
+  ["file tool at all (architect and researcher have no write/edit/bash; reviewer\n  has only the read-only bash, which refuses redirection). Pass the `session`",
+   "file tool at all (architect and researcher have no write / edit / shell, and\n  reviewer's shell is the host's own, classified per command). Pass the `session`"],
+  ["- The host stops a bash command after 120 s unless you pass a larger", "- The host stops a shell command after 120 s unless you pass a larger"],
+  /*
+   * The LEDGER.  v2 gives a plugin no `todowrite` (V2_ONLY_ACTIONS names it as a
+   * key with no v2 counterpart), so the mandate's tool is the one this plugin
+   * registers instead — `tm_ledger`, stored in the host's own ctx.storage.  A v2
+   * lead told to "create a todo list" without a named tool either invents a
+   * MANIFEST.md (the prompt forbids that, correctly) or keeps the list in prose
+   * and loses it at the next compaction, which is the failure the rule exists to
+   * prevent.  The status words move with it: `in_progress`/`completed` are
+   * todowrite's enum, and tm_ledger's are open/doing/done/blocked.
+   */
+  ["## Hard rule — TodoList discipline (non-negotiable)\nBefore you touch anything on a medium-or-larger task you MUST create a todo\nlist.",
+   "## Hard rule — LEDGER discipline (`tm_ledger`, non-negotiable)\nBefore you touch anything on a medium-or-larger task you MUST put the list on\nrecord: `tm_ledger { action:\"add\", text:\"…\" }` per work package."],
+  ["- Keep it LIVE: an item is `in_progress` while you or a dispatched child is\n  actually working it, and `completed` only after its work is verified —",
+   "- Keep it LIVE: an item is `doing` while you or a dispatched child is\n  actually working it, and `done` only after its work is verified —"],
+  ["genuinely are in_progress at once; that is the intended shape, not a\n  violation of single-task focus (one worker, one in_progress).",
+   "genuinely are `doing` at once; that is the intended shape, not a\n  violation of single-task focus (one worker, one `doing`)."],
+  ["- The goal travels with the work: it goes in the todo list, into every dispatch",
+   "- The goal travels with the work: it goes in `tm_ledger`, into every dispatch"],
+  ["NO MANIFEST.md — your state memory is the todo list.", "NO MANIFEST.md — your state memory is `tm_ledger`."],
+  ["  todo list, dispatched to `implementer` with the exact finding text.",
+   "  ledger, dispatched to `implementer` with the exact finding text."],
+  ["  list, lay out the merge structure,", "  ledger (`tm_ledger { action:\"list\" }` marks what the round finished), lay out the merge structure,"],
+  ["Do NOT store task state or oversized content there — todo list and\nboard files own those.",
+   "Do NOT store task state or oversized content there — the lead's `tm_ledger`\nand board files own those."],
+  ["dropped: the list is the user's audit surface (pending / in_progress /\n  completed / blocked)", "dropped: the list is the user's audit surface (open / doing /\n  done / blocked — `tm_ledger` keeps the states, and `blocked` carries the note\n  naming what blocked it)"],
+  /* tm_pty is v1-only on purpose: `client.pty` does not exist on the v2 plugin
+   * ctx, so the tool could only ever answer "pty 接口不可用".  The v2 rules now DO name a
+   * replacement, because #28 measured it out of the 2.0.16 build
+   * (docs/research/v2-builtin-tools.md §2.5): `shell` takes `background:true`, the ack is
+   * "Command moved to the background (shell ID: X)" plus the file the output streams to,
+   * the host says DO NOT poll, and completion returns later as a synthetic
+   * `<shell id=… state=… command=…>` message.  `shell` and `subagent` are the ONLY two
+   * built-ins with a background parameter, which is also why tm_pty stays retired: the pty
+   * REST surface is still absent, and the native path has no per-command dialog (and its
+   * completion envelope re-enters context carrying the command text — an R6 touchpoint). */
+  ["either: give each its own call, or run it through tm_pty (non-blocking,\n  where granted) and check `status` later.  A tm_pty session writes no\n  transcript back to you, so tee its output to a file (`<cmd> 2>&1 | tee\n  <log>`) and read that file for EVIDENCE once it reports exited.",
+   "either: give each its own call, or run it through `shell` with\n  `background:true` (it returns at once with a shell ID and the file its output\n  streams to, and the host notifies you when it exits — so do NOT poll, and never\n  re-run the command to watch it pass again).  Either way tee the output\n  (`<cmd> 2>&1 | tee\n  <log>`) and read that log for EVIDENCE."],
+  /* Option A (user decision 2026-09-25): interactive browsing goes to the host's own
+   * browser_* tools, because that is the only browser the desktop renders in its side
+   * panel (docs/research/browser-pane.md).  Governance is NOT taken off the table: the gate
+   * lives in src/host/v2-browser-gate.ts (execute.before + a leak-detected fallback that
+   * replaces the page with the refusal), and snapshots stay addressable through
+   * capKeepingAddressing.  tm_browser stays named as the fallback for a host with no
+   * desktop browser (CLI / standalone server).  Every key below must match the v1 prompt
+   * byte-exactly: assertForkApplied() throws when one stops matching. */
+  ["  URLs → tm_webfetch, JS-rendered pages → tm_browser (network roles only).", "  URLs → tm_webfetch, JS-rendered pages → the host's own browser_* tools (they drive\n  the side panel the user can actually see), falling back to tm_browser when no desktop browser is connected (network roles only)."],
+  ["- a visual state (a rendered UI, a chart) → tm_browser", "- a visual state (a rendered UI, a chart) → the host's browser_* tools (browser_tabs_open → browser_snapshot → browser_screenshot), or tm_browser when they are not offered"],
+  ["## UI verification (tm_browser — you carry it)", "## UI verification (the host's browser_* tools — you carry them)"],
+  ["For user-visible frontend changes, verify through the governed tm_browser", "For user-visible frontend changes, verify through the host's own browser_* tools (tm_browser only when they are absent)"],
+  ["If tm_browser is unavailable on this host, the action you need is not", "If neither browser_* nor tm_browser is available on this host, the action you need is not"],
+  ["  via your governed tm_search / tm_browser / tm_webfetch first,", "  via your governed tm_search / tm_webfetch and the host's browser_* tools (or tm_browser when no desktop browser is connected) first,"],
+  ["  lookups: governed tm_search / tm_browser / tm_webfetch first, then user MCP tools.", "  lookups: governed tm_search / tm_webfetch + the host's browser_* tools first, then user MCP tools."],
+]
+
+function forkBody(text, hits) {
+  let out = text
+  for (const [from, to] of V2_TEXT) {
+    if (!out.includes(from)) continue
+    out = out.split(from).join(to)
+    hits.add(from)
+  }
+  return out
+}
+
+/** Every key must land in at least one role, or the fork is silently stale. */
+function assertForkApplied(hits) {
+  const dead = V2_TEXT.map(([from]) => from).filter((from) => !hits.has(from))
+  if (dead.length) {
+    throw new Error(
+      `v2 提示词分叉有 ${dead.length} 条没命中任何角色（源文改了，这里没跟上）：\n  - ` +
+        dead.join("\n  - "),
+    )
+  }
+}
+
+const written = []
+const skipped = []
+
+function emit(dir, name, content) {
+  const file = join(dir, `${name}.md`)
+  if (existsSync(file)) {
+    const current = readFileSync(file, "utf8")
+    if (!current.includes(MARKER) && !force) {
+      skipped.push(`${file} — 不是我生成的文件，未覆盖（--force 强制）`)
+      return
+    }
+    if (current === content) {
+      skipped.push(`${file} — 已是最新`)
+      return
+    }
+  }
+  if (printOnly) {
+    console.log(`=== ${file}\n${content.slice(0, 700)}\n… (${content.length} 字节)`)
+    written.push(file)
+    return
+  }
+  mkdirSync(dir, { recursive: true })
+  writeFileSync(file, content, "utf8")
+  written.push(file)
+}
+
+const agentsDir = join(baseDir, "agents")
+const forkHits = new Set()
+for (const [id, cfg] of Object.entries(agents)) {
+  const { triples } = triplesFromAgentPermission(cfg.permission, { escalateShellAsk: false, agentName: id })
+  // An `allow` for a tool v2 never registers would claim a capability that does
+  // not exist; V1_ONLY_TOOLS is the same set v2.ts skips when registering.
+  const v2Triples = triples.filter((t) => !V1_ONLY_TOOLS.has(t.action))
+  const text = forkBody(body(cfg.prompt), forkHits)
+  emit(agentsDir, id, agentFrontmatter(cfg, v2Triples) + text + "\n")
+}
+assertForkApplied(forkHits)
+
+const commandsDir = join(baseDir, "commands")
+for (const [name, cfg] of Object.entries(commands)) {
+  emit(commandsDir, name, commandFrontmatter(cfg) + body(cfg.template) + "\n")
+}
+
+console.log(`目标：${agentsDir} 与 ${commandsDir}`)
+for (const f of written) console.log(printOnly ? `将写入 ${f}` : `已写入 ${f}`)
+for (const s of skipped) console.log(`跳过 ${s}`)
+console.log(
+  `\n共 ${written.length} 个文件（角色 ${Object.keys(agents).length} + 命令 ${Object.keys(commands).length}）` +
+    `${printOnly ? "（--print，未落盘）" : ""}。重启桌面端（或 opencode reload）后 Team 出现在 agent 选择器、/team-* 出现在命令列表。`,
+)

package/scripts/lib/config-surgery.cjs

@@ -0,0 +1,239 @@
+// 2.x config surgery, shared by scripts/install.sh and scripts/install.ps1 so the two
+// installers cannot drift into two different ideas of what "installed" means.
+//
+// Adds the plugin entry and/or sets default_agent, then READS THE VALUE BACK from disk
+// before reporting success. Comments are masked to spaces at identical offsets, so a
+// commented-out key can never be mistaken for a live one (the read-back would pass
+// while the config said nothing).
+//
+// Why the key is `plugins` and not `plugin`, why one entry may not sit in two files,
+// and why a directory target needs a root index.js: docs/research/plugin-loader-contract.md
+// usage: node config-surgery.cjs <file> <plugins|default-agent> <value> [otherFileToScrub]
+const fs = require("fs");
+const [file, mode, value, other] = process.argv.slice(2);
+if (!file || !mode || !value) {
+  console.error("ERR usage: node this.js <file> <plugins|default-agent> <value> [otherFileToScrub]");
+  process.exit(1);
+}
+
+const mask = (s) => {
+  let out = "", i = 0, inStr = false, esc = false;
+  while (i < s.length) {
+    const c = s[i];
+    if (inStr) {
+      out += c;
+      if (esc) esc = false; else if (c === "\\") esc = true; else if (c === '"') inStr = false;
+      i++; continue;
+    }
+    if (c === '"') { inStr = true; out += c; i++; continue; }
+    if (c === "/" && s[i + 1] === "/") { while (i < s.length && s[i] !== "\n") { out += " "; i++; } continue; }
+    if (c === "/" && s[i + 1] === "*") {
+      while (i < s.length && !(s[i] === "*" && s[i + 1] === "/")) { out += s[i] === "\n" ? "\n" : " "; i++; }
+      out += "  "; i += 2; continue;
+    }
+    out += c; i++;
+  }
+  return out;
+};
+
+const lineOf = (s, idx) => s.slice(0, idx).split("\n").length;
+let src = fs.readFileSync(file, "utf8");
+const open = mask(src).indexOf("{");
+if (open < 0) { console.error("ERR no top-level object in " + file); process.exit(1); }
+const nextNonWs = (s, i) => { while (i < s.length && /\s/.test(s[i])) i++; return i; };
+/** insert one member right after the object's opening brace (top level by
+ *  definition: in a JSONC config the first '{' IS the document's own). */
+const insertMember = (s, member) => {
+  const after = nextNonWs(s, open + 1);
+  const comma = s[after] === "}" ? "" : ",";   // an empty object takes none
+  return s.slice(0, open + 1) + "\n  " + member + comma + s.slice(open + 1);
+};
+const lineNo = (s, idx) => " (line " + lineOf(s, idx) + " of " + file + ")";
+
+if (mode === "plugins") {
+  // OpenCode 2.x reads `config.plugins` (PLURAL). The singular `plugin` key is the
+  // 1.18.x spelling; a 2.x host never reads it, so an entry written there looks like
+  // an installed plugin and is nothing. It is left in place (a user may still share
+  // the file with a 1.18.x install) but REPORTED.
+  //
+  // Exactly ONE entry for our package, in either spelling: the host loads every entry
+  // it finds, and the same plugin loaded twice means two personalities registering the
+  // same tools and hooks. So a previous entry of OURS (npm specifier vs ./vendor path)
+  // is REPLACED, never duplicated; entries naming anything else are untouched.
+  const lit = JSON.stringify(value);
+  // Case-insensitive, hyphen-optional and slash-tolerant, because a local install is
+  // spelled with the working tree's own directory name (`D:/Github/Opencode-TeamMode`,
+  // no hyphen between team and mode) while the npm entry is `opencode-team-mode`. An
+  // entry we fail to recognise as ours is one we would ADD next to the existing one —
+  // and two entries is two loads, which is the defect this function exists to prevent.
+  const ours = (t) => /opencode[-_]?team[-_]?mode|vendor[/\\]team-mode/i.test(t);
+  const findArray = (mk, key) => {
+    const m = new RegExp('"' + key + '"\\s*:\\s*\\[').exec(mk);
+    if (!m) return null;
+    let i = m.index + m[0].length, depth = 1;
+    while (i < mk.length) {
+      const c = mk[i];
+      if (c === '"') { const j = mk.indexOf('"', i + 1); if (j < 0) return null; i = j + 1; continue; }
+      if (c === "[" || c === "{") depth++;
+      else if (c === "]" || c === "}") { depth--; if (depth === 0) return { head: m.index + m[0].length, end: i }; }
+      i++;
+    }
+    return null;
+  };
+  /** [start,end) spans of the array's own elements in [head,end); commas and whitespace
+   *  are skipped, so a trailing comma — which a hand-edited or host-written config often
+   *  carries — cannot end up producing ", ,", which would break the parse. */
+  const elements = (mk, head, end) => {
+    const out = []; let i = head;
+    while (i < end) {
+      const c = mk[i];
+      if (c === "," || /\s/.test(c)) { i++; continue; }
+      if (c === '"') { const j = mk.indexOf('"', i + 1); if (j < 0 || j >= end) break; out.push([i, j + 1]); i = j + 1; continue; }
+      if (c === "{" || c === "[") {
+        let d = 0, k = i;
+        for (; k < end; k++) {
+          const q = mk[k];
+          if (q === '"') { k = mk.indexOf('"', k + 1); if (k < 0 || k >= end) { k = end; break } continue; }
+          if (q === "{" || q === "[") d++;
+          else if (q === "}" || q === "]") { d--; if (!d) { k++; break; } }
+        }
+        out.push([i, k]); i = k; continue;
+      }
+      let k = i; while (k < end && !/[,}\]\s]/.test(mk[k])) k++;
+      out.push([i, k]); i = k;
+    }
+    return out;
+  };
+  const view = (text) => { const mk = mask(text); const a = findArray(mk, "plugins"); return { mk, a, els: a ? elements(mk, a.head, a.end) : [] }; };
+
+  const v0 = view(src);
+  if (findArray(v0.mk, "plugin")) {
+    console.log("NOTE this file also has a top-level \"plugin\" (singular) key — OpenCode 2.x loads" +
+      "\n     config.plugins (plural) and never reads the singular one. Left untouched; if 1.18.x\n" +
+      "     is gone from this machine, the key and its entries are dead weight you can delete.");
+  }
+  if (!v0.a) {
+    fs.writeFileSync(file, insertMember(src, '"plugins": [\n    ' + lit + "\n  ]"));
+    console.log("OK  created the plugins array with " + lit);
+  } else {
+    const same = v0.els.filter(([a, b]) => v0.mk.slice(a, b) === lit);
+    const dupe = v0.els.filter(([a, b]) => ours(v0.mk.slice(a, b)) && v0.mk.slice(a, b) !== lit);
+    if (dupe.length) {
+      // Replace the first, drop the rest: two entries of ours = two loaded personalities.
+      let out = src;
+      for (let n = dupe.length - 1; n >= 0; n--) {
+        const [a, b] = dupe[n];
+        out = n === 0 ? out.slice(0, a) + lit + out.slice(b) : out.slice(0, a) + out.slice(b);
+      }
+      fs.writeFileSync(file, out);
+      console.log("OK  replaced " + dupe.length + " previous Team entry/entries with " + lit);
+    } else if (same.length) {
+      console.log("OK  plugins already lists " + lit +
+        (same.length > 1 ? " — " + same.length + " times, which loads the plugin twice" : ""));
+    } else {
+      const last = v0.els[v0.els.length - 1];
+      const at = last ? last[1] : v0.a.head;
+      const pad = last ? ",\n    " : "\n    ";
+      fs.writeFileSync(file, src.slice(0, at) + pad + lit + src.slice(at));
+      console.log("OK  added " + lit + " alongside " + v0.els.length + " existing entr" + (v0.els.length === 1 ? "y" : "ies"));
+    }
+  }
+  // Read it back off the disk. The host's loader skips a plugin directory whose
+  // entrypoint it cannot resolve with NO message at all, and a key nobody reads is
+  // indistinguishable from an install — so the only claim made here is the measured one.
+  const v1 = view(fs.readFileSync(file, "utf8"));
+  const got = v1.els.filter(([a, b]) => v1.mk.slice(a, b) === lit).length;
+  if (!got) {
+    console.error("ERR read-back: plugins does not hold " + lit + " (array " + (v1.a ? "present" : "ABSENT") + ")");
+    console.error("    Add it by hand at the top level of " + file + ":  \"plugins\": [" + lit + "]");
+    process.exit(1);
+  }
+  const stillOurs = v1.els.filter(([a, b]) => ours(v1.mk.slice(a, b))).length;
+  console.log("OK  read back: plugins holds " + lit + " (" + v1.els.length + " entries, " +
+    stillOurs + " of them Team)");
+  if (got > 1 || stillOurs > 1) {
+    console.error("ERR the array carries our package more than once — the host would load it twice");
+    process.exit(1);
+  }
+  // Reclaim our entry from the OTHER global config file. The two files are merged at
+  // parse time and the host dedupes only on an identical string, so leaving our entry
+  // in opencode.json while writing this one would register the plugin twice — two
+  // personalities, the same tools and hooks bound twice, and a boot log that reads as
+  // one healthy install. Foreign entries (another plugin, any other key) are untouched.
+  if (other && other !== file && fs.existsSync(other)) {
+    const osrc = fs.readFileSync(other, "utf8");
+    const ov = view(osrc);
+    const mine = ov.els.filter(([a, b]) => ours(ov.mk.slice(a, b)));
+    if (mine.length) {
+      let out = osrc;
+      for (let n = mine.length - 1; n >= 0; n--) {
+        const [a, b] = mine[n];
+        // Take the comma with the element, and pick the RIGHT side: dropping a trailing
+        // comma when the element is the last one would leave `"x",\n  ]`, which only
+        // parses because the host reads JSONC with allowTrailingComma — and a config that
+        // is valid solely under a lenient parser is a trap for the next hand edit.
+        let prev = a - 1;
+        while (prev >= 0 && /\s/.test(out[prev])) prev--;
+        if (prev >= 0 && out[prev] === ",") {
+          out = out.slice(0, prev) + out.slice(b);        // not first: remove prev comma + element
+        } else {
+          let next = b;
+          while (next < out.length && /\s/.test(out[next])) next++;
+          out = out.slice(0, a) + out.slice(out[next] === "," ? next + 1 : b);  // first: remove element + its comma
+        }
+      }
+      fs.writeFileSync(other, out);
+      // [Q, T,] with T removed keeps a comma either way (a separator on one side, a
+      // trailing one on the other), so a single element + comma delete cannot produce
+      // strict JSON. Strip a comma that now dangles immediately before THIS array's own
+      // closing bracket — that region and no other, because the rest of the file is not
+      // ours to reformat.
+      const after = view(fs.readFileSync(other, "utf8"));
+      if (after.a) {
+        let p = after.a.end - 1;
+        while (p > after.a.head && /\s/.test(out[p])) p--;
+        if (out[p] === ",") {
+          out = out.slice(0, p) + out.slice(p + 1);
+          fs.writeFileSync(other, out);
+        }
+      }
+      const chk = view(fs.readFileSync(other, "utf8"));
+      const left = chk.els.filter(([a, b]) => ours(chk.mk.slice(a, b))).length;
+      if (left) {
+        console.error("ERR " + other + " still lists Team after the reclaim — the plugin would load twice");
+        process.exit(1);
+      }
+      console.log("OK  reclaimed " + mine.length + " Team entr" + (mine.length === 1 ? "y" : "ies") +
+        " from " + other + " (a second copy means a second load)");
+    }
+  }
+} else if (mode === "default-agent") {
+  const lit = JSON.stringify(value);
+  const re = /"default_agent"(\s*:\s*)("(?:[^"\\]|\\.)*"|[^,}\s][^,}\n]*)/;
+  const m = re.exec(mask(src));
+  if (m) {
+    const vStart = m.index + m[0].length - m[2].length;
+    if (m[2].trim() === lit) {
+      console.log("OK  default_agent already " + lit + lineNo(src, m.index));
+    } else {
+      fs.writeFileSync(file, src.slice(0, vStart) + lit + src.slice(vStart + m[2].length));
+      console.log("OK  default_agent rewritten (was " + m[2].trim() + ")");
+    }
+  } else {
+    fs.writeFileSync(file, insertMember(src, '"default_agent": ' + lit));
+    console.log("OK  default_agent added");
+  }
+  // Read it back — a fresh read of the file from disk, comments masked again.
+  src = fs.readFileSync(file, "utf8");
+  const chk = re.exec(mask(src));
+  const got = chk ? chk[2].trim() : null;
+  if (got !== lit) {
+    console.error("ERR default_agent read back as " + (got === null ? "(key absent)" : got) + ", not " + lit);
+    console.error("    Add it by hand at the top level of " + file + ":  \"default_agent\": " + lit);
+    process.exit(1);
+  }
+  console.log("OK  read back: " + lit + lineNo(src, chk.index));
+} else {
+  console.error("ERR unknown mode '" + mode + "'");
+  process.exit(1);
+}