​

Concurrent Self-Editing Workstreams + Conflict Resolution

​

0. TL;DR (the recommended architecture)

• A workstream = a registered federation thread + a git branch + (when it needs to build/verify) a K8sExecSandbox worktree. No new registry — extend the turn-86 thread registry (metadata.kind: "workstream") that register-thread/list-threads/tell-thread already ride on.
• Git-layer isolation comes first. Today git-commit.ts commits straight to main — there are no “two workstreams”, just a push race. The fix is branch-per-workstream: each self-editing thread commits to its own branch via the GitHub Data API; main is only ever reached by an auto-merge on workstream-done.
• Git does ~95% of the merge. On workstream-done, a merge attempt (GitHub merge API / three-way merge) resolves every mechanically non-conflicting change. The LLM resolver spawns only for the true conflict git can’t auto-merge. Do NOT build a merge engine — git already is one. The resolver is for intent, not diff3.
• Merge → re-verify → deploy-once. A clean git merge is NOT a green light. Two workstreams can merge cleanly at the text layer and produce a broken brain. So every merge (auto OR resolver-produced) runs through verify() (self-capable arc Layer 1); for a deployable image the unit is merged source → rebuild → re-verify → ONE deploy. Resolution is authoritative: other in-flight workstreams rebase onto the resolved main.
• The resolver CONVERSES, on beta Signals, now. Per Augustin’s redirect (“we are bleeding edge… we will adapt as needed”), the resolver does not merely notify. It reaches BACK to the originating workstreams — “does this merge preserve your intent? I need you to move your helper into lib/” — and gets a reply. This is built on the beta subscribeToThread / sendMessage.accepted.output reply-correlation + sendStateSignal shared-state lanes, all isolated behind lib/autonomy.ts (the existing anti-corruption boundary). Beta risk is real and called out in §7; the stance is “isolated, adapt on churn,” not “wait for GA.”
• The self-image special case is the sharp edge. Two workstreams both editing images/mastra → you cannot “merge two image tags.” You merge SOURCE, rebuild, re-verify, deploy ONCE. And the brain is replicas:1 + Recreate, so a bad self-image can’t roll gracefully — the resolver’s re-verify is the load-bearing backstop, revert-to-last-good-SHA is the parachute.

​

1. Grounding: what this system actually is (so we design onto it, not beside it)

1. Federation model (LOCKED turn 76, LIVE turn 86). “ONE broad agent, MANY threads, ONE shared memory; coordinate via SIGNALS; no hierarchy.” A new automation is a new thread (data), not a new class (code) — “runtime spawning is free” (REWRITE-NOTES:106). The mesh today: registerThread/listThreads/tellThread in lib/autonomy.ts, exposed as register-thread/list-threads/tell-thread tools (tools/autonomy.ts). A conflict-resolver is therefore just another thread with a goal. Reaching back to a workstream is sendMessage/subscribeToThread through that same boundary.
2. tellThread is fire-and-wake today, and it DELIBERATELY drops the reply. lib/autonomy.ts:276 awaits result.accepted and returns only accepted.action — it explicitly does NOT await accepted.output (“that would block on the peer finishing”). But accepted.output exists: it’s a MastraModelOutput promise on the wake/deliver members of the union (verified node_modules/@mastra/core/dist/agent/types.d.ts:120,137). So the conversational round-trip is not a different API — it is awaiting the field the current code drops. That is the single most important beta finding in this doc.
3. The write path commits straight to main, one repo, via the GitHub API — no branch, no clone, no shell. git-commit.ts:19 WRITE_ROOTS = ["cluster/", "apps-src/"]; lib/github.ts commitFile (Contents API) and commitFiles (Data API: blobs→tree→commit→ref) both hardcode branch: BRANCH (=main) and PATCH refs/heads/main with force:false. There is no branching machinery yet — but the Data API commitFiles already builds a commit object against a base tree, which is 90% of what branch-per-workstream needs. A force:false ref PATCH is exactly the push-race today: whichever workstream PATCHes second gets a 422 (non-fast-forward). That is the “collision” in the current system — a lost write, not a merge conflict.
4. The isolated executor is a real WorkspaceSandbox, tokenless, and the self-capable arc’s verify() generalizes it. durable/executor.ts K8sExecSandbox: bare pod on i5, zero-privilege SA (automountServiceAccountToken:false, zero role bindings), cap-dropped, activeDeadlineSeconds. It has git inside it — durable/workspace.ts:95 runs git init, and gitCommitAll/gitLog drive git in-pod. This is where a three-way merge and a rebuild physically happen. The pod can git fetch, git merge, git rebase, git worktree — git is a binary in the image, driven by fixed argv, never a model shell (P3 held: the sandbox is workflow-internal, never agent-attached).
5. Self-deploy is fully autonomous through git→CI→Flux, and the brain can’t roll gracefully. REWRITE-NOTES turn 109: YES, the agent may bump its own tag + redeploy all 9 images incl. images/mastra. AGENTS.md: self-deploy goes through git, never the agent’s own kubectl apply. images/mastra is replicas:1 + Recreate (libsql single-writer), so a bad self-image kills the old pod then crashloops the new one with nothing serving. Backstop = revert-tag-to-last-good-SHA.

​

2. What is a “workstream”, concretely

Design note — why extend the registry, not build a new one. The brief’s non-negotiable #1 is “map onto Mastra’s existing federation, not new machinery.” A workstream registry that isn’t the thread registry would be a second source of truth that drifts. metadata.kind + a branch string + a write-scope array is the whole model. This is the “runtime spawning is free” property (REWRITE-NOTES:106) applied to workstreams: a new workstream is a new thread + a new branch, no rebuild.

​

3. Git-layer isolation FIRST (the part the agent doesn’t have yet)

​

3.1 Branch-per-workstream write path

• commitFiles(files, message, branch = BRANCH) — the Data-API path already builds blobs→tree→commit→ref; the only change is which ref it reads as the base (git/ref/heads/<branch>) and PATCHes at the end. Creating the branch is one extra call (POST git/refs with refs/heads/ws/<slug> pointing at main’s head) done idempotently on first write.
• A workstream’s code writes go to ws/<slug>; main is never touched by a workstream directly — only by the merge step (§4). cluster/ manifest writes and apps-src/ writes stay on main unchanged (they’re not code, they’re not part of a self-editing workstream; keeping them on main avoids a merge-queue for ops changes that were never colliding).

​

3.2 Where the merge and rebuild physically happen

1. Executor pod clones the repo (or fetches; the pod has git + egress), checks out main.
2. git merge ws/<slug> (or merges multiple ready branches in turn).
3. Clean merge → git exits 0, working tree has the merged source → go to re-verify (§5).
4. Conflict → git exits non-zero, leaves conflict markers / git status shows unmerged paths → this is the ONLY trigger for the LLM resolver (§6). Git has already resolved everything it can; what’s left is genuine overlap.

​

4. The merge trigger + who runs it

• The merge-coordinator is a seeded, long-lived registered thread (like concierge/self-healer). Workstreams tellThread it when verified-and-ready. It holds a queue of ready branches in its thread state.
• For each ready branch (or batch), the coordinator kicks the durable merge+verify+deploy workflow (option C, run_durable_build-style tool → runDurableMerge). The workflow is where the pod clone → git merge → verify() → rebuild → deploy happens, with durability so a mastra restart mid-merge resumes.
• On a clean merge that passes re-verify, the workflow deploys once (§5) and reports back; the coordinator tells any other in-flight workstreams to rebase onto the new main (§6.4).
• On a git conflict, the workflow does NOT try to be clever — it spawns a resolver thread (§6) with the conflict context and suspends that branch’s merge until the resolver reports a resolution. The resolver is where the conversation happens.

​

5. Merge → re-verify → deploy-once (the coupling that must be explicit)

git merge (clean OR resolver-produced)
   → merged source tree in the pod
   → verify(mergedFiles, <per-image command list>)          ← self-capable arc Layer 1
       for a deployable image: the command list ENDS with a real build
       (pnpm install --frozen-lockfile && pnpm typecheck && pnpm test)
   → verify PASSES → commit merged tree to main (one commit)
                   → bump image tag in cluster/ (one commit)  ← triggers CI→Flux
   → verify FAILS  → do NOT commit to main; hand the failure back to the resolver
                     (or, if this was a clean auto-merge, spawn a resolver FOR the
                      verify failure — a clean merge that fails verify is a
                      semantic conflict git couldn't see)

​

6. The resolver thread — context, authority, and the conversation

​

6.1 What it’s handed (its context)

• Both diffs — ws/A vs merge-base, ws/B vs merge-base (the pod can git diff these).
• The conflict hunks (or, for a clean-but-failed-verify, the verify() report — the failing command + stderr tail).
• Both workstreams’ stated intent — pulled from each workstream thread’s goal/recent messages via the memory the mesh already shares (searchHistory/thread messages). This is why the workstream registry is a thread: the intent is already captured as conversation.
• The names of the originating workstream threads, so it can address them.

​

6.2 How it produces a resolution

​

6.3 The conversation back to the workstreams (the full vision, on beta, NOW)

• askThread(target, question) → reply — a NEW anti-corruption-boundary function, the conversational sibling of tellThread. Where tellThread awaits only accepted.action and drops accepted.output (lib/autonomy.ts:276), askThread awaits accepted.output — the woken run’s MastraModelOutput (verified present, types.d.ts:120,137) — and returns the peer’s reply text. This is reply-correlation with zero new Mastra surface: it’s the same sendMessage call, awaiting the field we currently throw away.
• subscribeToThread(options) (agent.d.ts:1145) backs the durable/streamed variant when the resolver wants to watch a workstream’s progress rather than block on one reply (e.g. “A, restructure your helper; I’ll watch your branch and re-merge when you push”). Wrapped as watchThread(...) behind the boundary.
• sendStateSignal(state, target) (agent.d.ts:1183, snapshot/delta modes) backs a shared merge-state lane — the resolver publishes “here’s the merged plan and which hunks each of you owns” as state the workstreams read, instead of re-sending it in every message. Wrapped as publishSharedState(...).

resolver detects overlap → askThread("A", "your helper foo() moved to lib/ in the merge;
                                          does your caller still assume it's local? reply with
                                          the corrected import or 'fine as-is'")
   → A wakes, answers (accepted.output) → resolver folds A's answer into the merged tree
   → verify() the folded tree → if A + B's constraints now both hold, deploy-once
   → if still broken, publishSharedState(mergedPlan) and watchThread(A), watchThread(B)
     while they push corrections onto their branches → re-merge → verify → deploy-once

​

6.4 Authority + rebase

Why this is not a hierarchy. The resolver has no standing authority over the workstreams — it’s spawned per-conflict, converses as a peer, and dies when the conflict is resolved. “Authoritative” applies to the resolved commit, not the thread. This preserves non-negotiable #1’s “no supervisor agent.”

​

7. Beta-primitive dependency + honest risk (the “adapt as needed” stance)

​

8. Failure / thrash modes and how the design bounds them

​

9. The self-image special case (images/mastra) — highest stakes

1. Merge the SOURCE (images/mastra/**) on a branch, in the pod (§3.2).
2. Rebuild + re-verify the merged source as ONE unit — verify(mergedMastraSource, ["pnpm install --frozen-lockfile", "pnpm typecheck", "pnpm test"]). This is the self-capable arc’s mastra self-verification (self-capable-arc §5.1), now applied to the merged tree, not a single workstream’s tree. (Open question inherited from that doc: how much of the package to inject + pod RAM sizing — §10.)
3. If re-verify passes: ONE deploy. Commit merged source to main (→ CI builds ONE new ghcr.io/amarcin/mastra image) → bump the tag in cluster/apps/agent/mastra/deployment.yaml ONCE. Never two tag bumps, never a tag “merge.”
4. If re-verify fails: nothing lands, resolver escalates (§8). The brain keeps running its current image.

1. Re-verify the MERGE, not the branches (§5) — catches the “A’s change + B’s change together break the build/tests” class, which is exactly the class a per-branch verify misses. This is the whole reason merge→re-verify is coupled.
2. Revert-to-last-good-SHA is a pure tag change (self-capable-arc §5.3): the previous mastra image is already in GHCR, so rollback = revert the one tag-bump commit → Flux rolls back → known-good brain returns. Fast because no rebuild.
3. A watcher outside the brain’s own liveness. The self-healer heartbeat runs in the mastra process — useless if that process is crashlooping. Open question (§10): does the self-image deploy need an external liveness→auto-revert (a tiny k8s-native probe or a CronJob on a different node that reverts the tag if mastra is unready for N minutes)? This is the one place the “agent can’t recover a pod it just killed” risk isn’t fully closed by the design above. Verify lowers the odds; it does not eliminate them. Honest: “verified” means “builds + tests pass,” not “cannot crashloop.”

Serialization for the brain specifically. Even though branch isolation lets many workstreams edit images/mastra concurrently, the deploy of the brain should be serialized to one-at-a-time (the coordinator already serializes merges, so this falls out — but state it: never two images/mastra deploys in flight, because the second would race the Recreate of the first). Augustin explicitly rejected serializing workstreams with a lock; this is not that — workstreams stay concurrent, only the final brain deploy is one-at-a-time, which is a physical constraint of replicas:1+Recreate, not a concurrency cop-out.

​

10. Open decisions that need Augustin

1. External liveness→auto-revert for the brain (§9). The design closes the crashloop risk with re-verify + fast revert, but the trigger for the revert, if the new brain never becomes ready, can’t live inside the brain. Options: (a) accept manual revert (Augustin reverts the tag when ntfy goes silent — but a crashlooped brain can’t ntfy); (b) a tiny external CronJob/Deployment on i3/pentium that watches mastra readiness and reverts the tag commit via the GitHub API after N minutes unready; (c) a Flux HealthCheck + a manual gate. Recommend (b) — it’s the only option that survives the brain being fully down, and it’s small. Needs Augustin’s go (it’s new machinery outside the agent, which the design otherwise avoids).
2. Merge granularity: per-branch or batched ready-sets? Merge each ready workstream as it arrives (simpler, more merges, each small) vs. batch all-currently-ready and merge together (fewer deploys, but a bigger conflict surface per merge). Recommend per-branch by default, batching only when the write-scope hint (§2) shows two ready workstreams touch the same image (merge those two together so their overlap is resolved once, not twice).
3. Inherited from self-capable-arc §7 (unchanged, still open): how much of images/mastra to inject for a merged-source verify + whether to bump the eval pod’s RAM; per-image verify command declaration (images/<name>/verify.json). The merge path reuses verify(), so these ride along.
4. Resolver model + budget. Every true conflict spawns an LLM resolution session (§8). At homelab scale (rare conflicts, one operator) this is fine — but say so: the resolver should run the same Opus-4.8-effort-high the main agent uses, and its cost is bounded by the attempt caps (§8), not open-ended. If conflicts ever become frequent, that’s the signal that workstreams are badly scoped, not that the resolver needs optimizing.

​

11. Phased build sequence (slots into the self-capable arc)

• Phase 6a — Branch-per-workstream write path (prereq; fold into arc Phase 4). Add the optional branch param to lib/github.ts commitFiles/commitFile (default main = no behavior change). Route images/** code writes for a named workstream to ws/<slug>. No resolver, no merge yet — just isolation. Independently shippable; makes the push-race impossible before any concurrency exists.
• Phase 6b — Workstream registry + ready signal. Extend ThreadKind with "workstream"; registerWorkstream + write-scope metadata; the tellThread-to-coordinator “ready” signal. Seed the merge-coordinator thread (like concierge). Still no merge — just the bookkeeping.
• Phase 6c — Merge + re-verify + deploy-once (the durable merge workflow). The runDurableMerge workflow (option C): pod clone → git merge → verify() → rebuild → deploy-once, driven by the coordinator (option B). Handles the CLEAN-merge path fully. On conflict OR failed-verify, for now: reachOut to Augustin (resolver stubbed). This alone is a huge capability — concurrent workstreams that don’t truly conflict now merge + re-verify + self-deploy autonomously.
• Phase 6d — The conversational resolver (the full vision, on beta). spawnResolver + askThread/watchThread/publishSharedState behind lib/autonomy.ts. The resolver spawns on conflict/failed-verify, converses back to the workstreams, re-verifies, deploys-once, and drives rebases. This is where the beta Signals primitives (§7) come in — isolated behind the boundary, with the degrade paths as failure handling.
• Phase 6e — Self-image hardening (§9). External liveness→auto-revert (open decision #1) + explicit one-at-a-time brain-deploy serialization. Gated on Augustin’s §10.1 call.

​

12. One-paragraph summary