geneseed 3.4.0 → 3.6.0

package/adapters/opencode/GLOBAL-HARNESS-SPEC.md

@@ -185,7 +185,7 @@ repo's layout defeats the convention.
 
 ### 3.5 Injection block format (mirror `harness.py cmd_context`)
 
-Byte-identical structure to [harness.py:237-263](../../rituals/harness.py) so both
+Byte-identical structure to the retired Python `harness.py` (lines 237-263) so both
 enforcement paths read the same. Adds a machine marker (first line) for §4.
 
 ```

package/adapters/opencode/README.md

@@ -380,8 +380,8 @@ behaviour** — nothing changes the machine's current agent/model unless you opt
   `tokyonight`, `rosepine`, `gruvbox`, `nord`, `everforest`, `kanagawa`, `dracula` — each
   in a **solid** (opaque) and a **transparent** (terminal-background-through) flavour.
   These are decoupled from the voice theme: any voice theme can run any colour theme.
-  Authored under `themes/opencode/` (see its README and
-  [the spec](../../docs/specs/2026-06-17-opencode-color-themes.md)).
+  Authored under `themes/opencode/` (see its README; the design record was the
+  `2026-06-17-opencode-color-themes` spec).
 - **Runtime guard plugin** (`geneseed-guard.js`, installed with the others). Enforces
   the safety Laws at the tool boundary: **blocks** writes to private-key/credential
   files (Law I), catastrophic shell like `rm -rf /` (Law IV), and any mutation under

package/adapters/opencode/plugins/geneseed-context.js

@@ -138,10 +138,12 @@ let fallbackVisible = false
 function log(msg) { if (DEBUG) console.error(`[geneseed-context] ${msg}`) }
 
 // ---- convention --------------------------------------------------------------
-// Root-level files injected in full. Agent-directed rules + canonical entry docs.
+// Root-level files injected in full. Canonical entry docs + agent-directed rules OpenCode
+// does not read by itself. AGENT.md (opencode.json `instructions`), AGENTS.md and CLAUDE.md
+// (OpenCode's own native roots) are deliberately absent: OpenCode already has them, and
+// injecting them again re-sent the whole harness on every request until 2026-09.
 const EAGER_ROOT = new Set([
-  "AGENTS.md", "AGENT.md", "CLAUDE.md", ".cursorrules",
-  "README.md", "CONTRIBUTING.md", "user-rules.md", "PROFILE.md",
+  ".cursorrules", "README.md", "CONTRIBUTING.md", "user-rules.md", "PROFILE.md",
 ])
 // Doc trees walked recursively; everything found is lazy (listed, not injected).
 const LAZY_DIRS = ["docs", "doc", "documentation", "architecture", "adr", "ADR"]

package/adapters/opencode/plugins/geneseed-workflow.js

@@ -17,6 +17,7 @@
 // Quiet by default; GENESEED_DEBUG=1 logs to stderr. GENESEED_WORKFLOWS_DIR overrides
 // where saved workflows are loaded from.
 
+import { execFile } from "node:child_process"
 import { promises as fs } from "node:fs"
 import * as path from "node:path"
 import { fileURLToPath, pathToFileURL } from "node:url"
@@ -63,6 +64,17 @@ function nowStamp() {
   return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`
 }
 
+// The runtime's git executor, for `isolation: "worktree"`. argv only, never a shell string:
+// branch and directory names derive from agent labels a script author wrote.
+function git(argv, cwd) {
+  return new Promise((resolve, reject) => {
+    execFile("git", argv, { cwd, windowsHide: true, maxBuffer: 16 * 1024 * 1024 }, (err, stdout, stderr) => {
+      if (err) reject(new Error(`git ${argv[0]}: ${String(stderr || err.message).trim()}`))
+      else resolve(String(stdout))
+    })
+  })
+}
+
 function safeJson(v) {
   try { return JSON.stringify(v, null, 2) } catch { return String(v) }
 }
@@ -73,7 +85,22 @@ function summarize(name, result, stats, tracePath) {
     (stats.phases.length ? `, phases: ${stats.phases.join(" → ")}` : "")
   let body = safeJson(result)
   if (body.length > 2000) body = body.slice(0, 2000) + `\n… (truncated — full result in ${tracePath})`
-  return `${head}\n\nResult:\n${body}\n\nTrace: ${tracePath}`
+  return `${head}\n\nResult:\n${body}${isolationReport(stats)}\n\nTrace: ${tracePath}`
+}
+
+// Kept worktrees are work awaiting review, and an overlap is a conflict awaiting ONE
+// merger (process 8) — both are said out loud, never left for the trace to hold.
+function isolationReport(stats) {
+  const kept = stats.worktrees || []
+  if (!kept.length) return ""
+  const lines = ["", "", `Worktrees kept (${kept.length}) — review and merge them yourself; nothing was merged:`]
+  for (const w of kept) lines.push(`- ${w.label}: ${w.branch} at ${w.dir} — ${w.files.length} file(s)`)
+  const over = stats.overlaps || []
+  if (over.length) {
+    lines.push(`CONFLICTS — ${over.length} file(s) changed by more than one agent; merge these by hand or through one merge agent:`)
+    for (const o of over) lines.push(`- ${o.file}: ${o.labels.join(", ")}`)
+  }
+  return lines.join("\n")
 }
 
 async function writeTrace(rootDir, runId, lines) {
@@ -142,7 +169,7 @@ export const GeneseedWorkflow = async (ctx) => {
     try { ({ createRuntime } = await import(pathToFileURL(path.join(WORKFLOWS_DIR, "_runtime.js")).href + "?t=" + Date.now())) }
     catch (e) { return `Workflow runtime unavailable: ${e?.message || e}` }
 
-    const rt = createRuntime({ client, directory, worktree, args: normalizeArgs(argv?.args), log: sink })
+    const rt = createRuntime({ client, directory, worktree, git, runId, args: normalizeArgs(argv?.args), log: sink })
     let result, failed = null
     try { result = await wf.run(rt) }
     catch (e) { failed = e; sink(`✗ workflow error: ${e?.stack || e?.message || e}`) }
@@ -152,7 +179,7 @@ export const GeneseedWorkflow = async (ctx) => {
     if (!failed) sink(`# result:\n${safeJson(result)}`)
     const tracePath = await writeTrace(rootDir, runId, lines)
 
-    if (failed) return `Workflow "${name}" failed: ${failed?.message || failed}\nTrace: ${tracePath}`
+    if (failed) return `Workflow "${name}" failed: ${failed?.message || failed}${isolationReport(stats)}\nTrace: ${tracePath}`
     return summarize(name, result, stats, tracePath)
   }
 

package/adapters/opencode/workflows/_runtime.js

@@ -17,6 +17,7 @@
 // hard sandbox guard. See docs/specs/2026-06-09-opencode-workflow-primitive.md.
 
 import * as os from "node:os"
+import * as path from "node:path"
 
 const DEBUG = !!process.env.GENESEED_DEBUG
 function dlog(m) { if (DEBUG) console.error(`[geneseed-workflow] ${m}`) }
@@ -150,13 +151,17 @@ function usageFrom(res) {
   return { input: Number(tok?.input ?? 0) || 0, output: Number(tok?.output ?? 0) || 0 }
 }
 
-async function runChildSession(client, { prompt, agent, model, title }) {
+async function runChildSession(client, { prompt, agent, model, title, directory }) {
   if (!client?.session?.create || !client?.session?.prompt) {
     throw new Error("OpenCode SDK session API unavailable")
   }
   let created
-  try { created = await client.session.create({ body: { title: title || "geneseed-workflow" } }) }
-  catch { created = await client.session.create() }
+  // `query.directory` routes the request to that directory's instance, and the session keeps
+  // it — so an isolated child runs in its worktree. Never retried without it: a child that
+  // asked for a worktree and silently ran in the shared tree is the failure isolation exists for.
+  const q = directory ? { query: { directory } } : {}
+  try { created = await client.session.create({ body: { title: title || "geneseed-workflow" }, ...q }) }
+  catch (e) { if (directory) throw e; created = await client.session.create() }
   const sid = sessionId(created)
   if (!sid) throw new Error("could not create child session")
   try {
@@ -164,7 +169,7 @@ async function runChildSession(client, { prompt, agent, model, title }) {
     if (agent) body.agent = agent
     if (model) body.model = model
     let res = null
-    try { res = await client.session.prompt({ path: { id: sid }, body }) }
+    try { res = await client.session.prompt({ path: { id: sid }, body, ...q }) }
     catch (e) { dlog(`prompt failed: ${e?.message || e}`) }
     const r = unwrap(res)
     let text = partsText(r?.parts ?? r?.info?.parts ?? [])
@@ -175,9 +180,52 @@ async function runChildSession(client, { prompt, agent, model, title }) {
   }
 }
 
+// ---- worktree isolation ------------------------------------------------------
+// `agent(prompt, { isolation: "worktree" })` — the same option Claude Code's Workflow
+// takes. Parallel editors in one tree lose each other's writes (process 8, one writer per
+// file), so each isolated agent gets its own branch + worktree off the root's HEAD, and
+// the files it changed are recorded for `overlaps()`. A worktree with no change is
+// removed with its branch; one with changes is KEPT for the parent to review and merge —
+// the runtime never merges, commits, or deletes work. `git(argv, cwd)` is injected by the
+// plugin so this file stays pure and testable. The worktree has no untracked files from
+// the root (no node_modules, no .env): an agent that must run the project installs first.
+const slug = (t) => String(t).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 32) || "agent"
+
+export async function isolate(git, root, name) {
+  if (typeof git !== "function") throw new Error("worktree isolation unavailable — no git executor")
+  if (!root) throw new Error("worktree isolation unavailable — unknown working dir")
+  const base = (await git(["rev-parse", "HEAD"], root)).trim()
+  const branch = `geneseed-wf/${name}`
+  const dir = path.join(os.tmpdir(), "geneseed-wf", name)
+  await git(["worktree", "add", "-b", branch, dir, base], root)
+  return { dir, branch, base }
+}
+
+export async function changedFiles(git, w) {
+  const lines = (out) => String(out).split("\n").map((l) => l.trim()).filter(Boolean)
+  const tracked = lines(await git(["diff", "--name-only", w.base], w.dir))
+  const untracked = lines(await git(["ls-files", "--others", "--exclude-standard"], w.dir))
+  return [...new Set([...tracked, ...untracked])].sort()
+}
+
+// Files more than one isolated agent changed — the conflicts a merge would otherwise
+// settle by whoever landed last. [{ file, labels }], sorted by file.
+export function overlaps(worktrees) {
+  const by = new Map()
+  for (const w of worktrees || []) for (const f of w.files || []) {
+    if (!by.has(f)) by.set(f, [])
+    by.get(f).push(w.label)
+  }
+  return [...by].filter(([, l]) => l.length > 1).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+    .map(([file, labels]) => ({ file, labels }))
+}
+
 // ---- the runtime ------------------------------------------------------------
 export function createRuntime(ctx) {
-  const { client, directory, worktree, log: sink } = ctx
+  const { client, directory, worktree, log: sink, git } = ctx
+  const root = worktree || directory
+  const runTag = slug(ctx.runId || "run")
+  const worktrees = []
   const args = ctx.args || {}
   const cap = ctx.concurrency || concurrencyCap()
   const limit = createLimiter(cap)
@@ -202,9 +250,32 @@ export function createRuntime(ctx) {
   async function spawn(prompt, opts) {
     return limit(() => runChildSession(client, {
       prompt, agent: opts.agent, model: opts.model, title: `geneseed-wf:${opts.label}`,
+      directory: opts.directory,
     }))
   }
 
+  // Git calls are serialised: concurrent `worktree add -b` calls contend for the same ref
+  // and worktree locks, and a lost lock fails an agent that did nothing wrong.
+  const gitQ = createLimiter(1)
+  const g = typeof git === "function" ? (argv, cwd) => gitQ(() => git(argv, cwd)) : undefined
+
+  // An isolated agent that changed nothing has its worktree and branch released; one that
+  // changed files is KEPT and recorded. A failed release is logged, never thrown.
+  async function settle(w, label) {
+    let files
+    try { files = await changedFiles(g, w) }
+    catch (e) { emit(`  ⚠ ${label}: could not list changes — worktree kept at ${w.dir}: ${e?.message || e}`); return }
+    if (files.length) {
+      worktrees.push({ label, dir: w.dir, branch: w.branch, base: w.base, files })
+      emit(`  ⎇ ${label}: ${files.length} file(s) changed — kept at ${w.dir} (branch ${w.branch})`)
+      return
+    }
+    try {
+      await g(["worktree", "remove", w.dir], root)
+      await g(["branch", "-D", w.branch], root)
+    } catch (e) { emit(`  ⚠ ${label}: could not release unchanged worktree — ${e?.message || e}`) }
+  }
+
   async function agent(prompt, opts = {}) {
     if (agentCount >= MAX_AGENTS) throw new Error(`workflow agent cap (${MAX_AGENTS}) exceeded`)
     if (budgetTotal != null && spent >= budgetTotal) {
@@ -213,8 +284,21 @@ export function createRuntime(ctx) {
     agentCount++
     const label = opts.label || String(prompt).slice(0, 40)
     emit(`· agent: ${label}`)
+    if (opts.isolation !== "worktree") return runAgent(prompt, { ...opts, label })
+    // The worktree wraps EVERY attempt, schema retries included — a retry that ran in the
+    // shared tree would undo the isolation it was asked for.
+    let w
+    try { w = await isolate(g, root, `${runTag}-${agentCount}-${slug(label)}`) }
+    catch (e) { emit(`✗ agent failed: ${label} — ${e?.message || e}`); return null }
+    emit(`  ⎇ ${label}: worktree ${w.dir}`)
+    try { return await runAgent(prompt, { ...opts, label, directory: w.dir }) }
+    finally { await settle(w, label) }
+  }
+
+  async function runAgent(prompt, opts) {
+    const { label } = opts
     let out
-    try { out = await spawn(prompt, { ...opts, label }) }
+    try { out = await spawn(prompt, opts) }
     catch (e) { emit(`✗ agent failed: ${label} — ${e?.message || e}`); return null }
     spent += out.usage?.output || 0
     if (!opts.schema) return out.text
@@ -270,7 +354,13 @@ export function createRuntime(ctx) {
 
   return {
     agent, parallel, pipeline, phase, log, budget, args, directory, worktree,
-    _stats: () => ({ agentCount, spent, cap, phases: [...phases], trace: [...trace] }),
+    // Isolated agents that changed something, and the files two or more of them touched.
+    worktrees: () => worktrees.map((w) => ({ ...w, files: [...w.files] })),
+    overlaps: () => overlaps(worktrees),
+    _stats: () => ({
+      agentCount, spent, cap, phases: [...phases], trace: [...trace],
+      worktrees: worktrees.map((w) => ({ ...w, files: [...w.files] })), overlaps: overlaps(worktrees),
+    }),
   }
 }