[EPIC] One chat vertical across the fleet — consolidate agent-app, adopt in every app

[vutuanlinh2k2]

Goal

Every Tangle AI app (gtm, tax, legal, creative, and future apps) runs its chat + vault functionality on the agent-app chat vertical instead of per-app forks. Produced by a five-repo audit (2026-07-23): the vertical (#191–#220) is shipped and published, gtm/tax/legal have adopted it to varying depth, creative has not, and a handful of generic pieces still live only in gtm.

Definition of done: every non-➖ cell in the tracking matrix below is ✅ — all chat features, in all four apps.

Work is split into two tracks: Track A is fully under our control; Track B is finished or well-understood work blocked on agent-dev-container releases — each item has an explicit trigger event and must never stall Track A.

Feature × app tracking matrix

Verified against each repo's live remote default branch on 2026-07-25 (agent-app 4457f41, gtm 14ea919, tax f4b9875, legal 60f1915, creative 0b8b536). Legend: ✅ complete · 🟡 partial/local fork/upgrade needed · ❌ missing · ➖ N/A by design. Missing cells name the covering issue; untracked means no implementation issue currently exists.

Feature	gtm	tax	legal	creative
Chat route orchestration (createChatTurnRoutes)	✅	✅	✅	✅
Shared chat store + canonical persisted parts	✅	✅ encrypted adapter	✅	✅ adapter
Hardened shared sandbox producer	✅ tangle-network/gtm-agent#629	✅ tangle-network/tax-agent#393	✅ tangle-network/legal-agent#281	❌ tangle-network/creative-agent#436
Shared browser stream/reconnect primitives	🟡 local gateway+D1 hook; untracked convergence	✅	🟡 shared dispatcher, manual reader/reload-only; untracked	✅ tangle-network/creative-agent#428
Live agent questions (shared route/card)	✅	✅	✅	✅
Durable interaction command/effect journal (createDurableInteractionRoutes)	❌ untracked	❌ untracked	❌ untracked	❌ untracked
Plan-mode behavior + shared UI	✅	✅ tangle-network/tax-agent#392	✅	❌ tangle-network/creative-agent#435
Shared durable plan route/journal (createDurablePlanRoutes)	❌ untracked	❌ untracked	❌ untracked	❌ tangle-network/creative-agent#435 should consume it
Durable/detached turns + running/replay	✅ tangle-network/gtm-agent#627	✅	✅ tangle-network/legal-agent#278	✅ tangle-network/creative-agent#434
Replay authorization scoped to owning workspace	✅	✅	❌ untracked security gap	✅
Durable per-thread single-flight lock	✅	❌ untracked	❌ untracked	❌ untracked
Incremental durable assistant transcript (agent-app ≥0.43.62)	🟡 package bump; untracked	❌ encrypted store adapter + bump; untracked	🟡 package bump; untracked	❌ store adapter + bump; untracked
Persisted user/assistant message IDs exposed to seams	🟡 #236; local workaround	➖ no current consumer need	➖ no current consumer need	🟡 #236; local workaround
File @-mentions	✅	✅ tangle-network/tax-agent#385	✅ tangle-network/legal-agent#277	❌ tangle-network/creative-agent#429
Attachments (shared surface)	✅ tangle-network/gtm-agent#621	➖ encrypted R2 document ingestion by design	✅ tangle-network/legal-agent#271	❌ tangle-network/creative-agent#429
Skills (shared adoptable module/placement)	✅	✅ tangle-network/tax-agent#390	✅ tangle-network/legal-agent#279	🟡 tangle-network/creative-agent#429; bespoke skill-mounts.ts
UI substrate (ui 11 / brand 1.x / sandbox-ui 0.87+)	✅	✅	✅	✅
Shared VaultPane UI	✅	✅ read-only	✅	✅
Writable VaultDataPort	✅	➖ read-only encrypted document product by design	✅	✅
Vault persistence + safety consolidated behind a shared contract	🟡 mature but GTM-local; untracked	🟡 encrypted R2 product path; untracked parity decision	🟡 product-local storage + duplicate chat vault browser; untracked	🟡 product-local persistence; untracked
agent-app version	^0.43.60	^0.43.56	^0.43.56	^0.43.56

Important distinctions found by the 2026-07-25 audit:

• The shared producer is now hardened and published; gtm, tax, and legal consume it. tangle-network/creative-agent#436 is the remaining producer adoption.
• Green question/plan UI does not mean the durable server workflow is shared: no app currently imports createDurableInteractionRoutes or createDurablePlanRoutes.
• Only gtm supplies the shared vertical a durable turnLock; the session gateway is not a distributed single-flight replacement.
• Agent-app 0.43.62 added incremental in-flight assistant-row persistence. No app has adopted that release yet; tax and creative also need their store wrappers to preserve updateMessage/deleteMessage.
• Legal's detached/replay behavior exists, but replay authorization currently authenticates the user without resolving the turn back to its owning workspace.
• The prior matrix tracked only VaultPane UI. The new Vault rows make the unresolved backend, write, storage, and safety consolidation visible instead of treating UI adoption as whole-Vault completion.

Currently tracked remaining Creative chain: tangle-network/creative-agent#436 → tangle-network/creative-agent#435 → tangle-network/creative-agent#429. The bold untracked cells are additional gaps found by the latest code audit; no new issues have been created.

Track A — dependency waves (everything within a phase runs in parallel)

Phases are dependency waves, not project groupings. Every item in a phase is mutually independent. Phases are not barriers: an item may start as soon as its own listed prerequisite lands, even if the rest of the previous phase is still in flight.

Phase 1 — independent today, start all in parallel:

• [FEAT] Shared durable turn replay/broadcast — graduate turnStore from no-op to a real implementation #221 — Shared durable turn replay/broadcast (real turnStore implementation)
• [FEAT] Uplift gtm's stream-normalizer helpers — dangling tool-part terminalization + attachment-aware part merge #222 — Uplift stream-normalizer helpers (dangling tool-part terminalization)
• [FEAT] InteractionPlanCard: add a re-request seam #223 — InteractionPlanCard re-request seam
• [FEAT] Uplift the attachment client half — structured dispatch + eager file-part promotion #224 — Uplift the attachment client half (dispatch + file-part promotion)
• streamChatTurn/consumeChatStream: surface sidecar interactions via an onInteraction seam (unblock product live agent-questions) #175 — onInteraction seam for streamChatTurn/consumeChatStream consumers
• tangle-network/tax-agent#383 — P1 bug: sandbox producer drops interaction/tool/reasoning events
• tangle-network/tax-agent#386 — UI substrate cascade
• tangle-network/legal-agent#270 — plan mode (/plans + /durable-chat)
• tangle-network/legal-agent#272 — UI substrate cascade
• tangle-network/creative-agent#425 — substrate bump (agent-app + ui + brand + sandbox-ui)

Phase 2 — each unblocked by the named Phase-1 item(s):

• [DOCS] Document the chat vertical as the integration contract (README modules + quickstart) #225 — Document the vertical (after [FEAT] Shared durable turn replay/broadcast — graduate turnStore from no-op to a real implementation #221–[FEAT] Uplift the attachment client half — structured dispatch + eager file-part promotion #224 + streamChatTurn/consumeChatStream: surface sidecar interactions via an onInteraction seam (unblock product live agent-questions) #175 settle the API surface)
• tangle-network/gtm-agent#618 — Drop the SESSION_STREAM_DO fork + local helpers (after [FEAT] Shared durable turn replay/broadcast — graduate turnStore from no-op to a real implementation #221–[FEAT] Uplift the attachment client half — structured dispatch + eager file-part promotion #224 publish)
• tangle-network/tax-agent#384 — agent-app bump + durable detached turns — verified green on tax master b82bdfa: detach: true, running-turn discovery, client reattach, and e2e coverage are present
• [FEAT] Graduate the shared chat-attachment surface — upload-route factory + composer hook + transcript renderer #234 — Graduate the shared chat-attachment surface: upload-route factory + composer hook + transcript renderer (after [FEAT] Uplift the attachment client half — structured dispatch + eager file-part promotion #224; lifts GTM's proven route/hook/renderer). Published; legal#271 consumes it in Phase 5 and gtm#621 is complete.
• tangle-network/creative-agent#426 — wave 1: server turn path onto createChatTurnRoutes (after creative#425)

Completed prerequisites for the remaining waves (record only — do not schedule):

• Creative wave 2: tangle-network/creative-agent#427 merged via PR #433.
• GTM dependency baseline and shared attachments: agent-app ^0.43.54, sandbox ^0.12.0, tangle-network/gtm-agent#621.
• Tax dependency baseline: agent-app ^0.43.54 + agent-interface ≥0.31.
• Legal dependency baseline: agent-app ^0.43.54 + agent-interface ≥0.31.
• [FEAT] Graduate the shared chat-attachment surface — upload-route factory + composer hook + transcript renderer #234 shared attachment surface published.

Phase 3 — ready now; all eight tasks run in parallel:

• [FEAT] Harden the shared sandbox producer with gtm's terminal robustness + reconcile the wire vocabulary #242 — harden createSandboxChatProducer up to GTM's proven terminal behavior and settle the wire vocabulary.
• tangle-network/gtm-agent#628 — remove the router backend; first of the three strictly sequenced gtm-chat-vertical.ts changes.
• tangle-network/tax-agent#385 — file @-mentions.
• tangle-network/tax-agent#390 — shared skills module.
• tangle-network/tax-agent#392 — chat plan mode.
• tangle-network/legal-agent#277 — file @-mentions; first of legal's sequenced chat/composer cluster.
• tangle-network/legal-agent#279 — shared skills module; separate profile/knowledge path from #277.
• tangle-network/creative-agent#434 — durable turns and reconnect; do before #428 because both modify app.workspace.chat.tsx.

Phase 4 — unblocked by Phase 3; all five tasks run in parallel:

• tangle-network/gtm-agent#627 — adopt shared turn-stream replay after #628; second gtm-chat-vertical.ts change.
• tangle-network/tax-agent#393 — bump to inherit the hardened producer after [FEAT] Harden the shared sandbox producer with gtm's terminal robustness + reconcile the wire vocabulary #242.
• tangle-network/legal-agent#278 — durable/detached turns after #277; second legal chat-vertical change.
• tangle-network/legal-agent#281 — bump to inherit the hardened producer after [FEAT] Harden the shared sandbox producer with gtm's terminal robustness + reconcile the wire vocabulary #242.
• tangle-network/creative-agent#428 — migrate the client onto shared stream primitives after #434 (and completed #427).

Phase 5 — second-order adoptions; all three tasks run in parallel:

• tangle-network/gtm-agent#629 — adopt the hardened producer after [FEAT] Harden the shared sandbox producer with gtm's terminal robustness + reconcile the wire vocabulary #242 → #628 → #627; final gtm-chat-vertical.ts change.
• tangle-network/legal-agent#271 — shared attachments after #277 → #278; final legal chat/composer rewrite.
• tangle-network/creative-agent#436 — adopt the hardened producer after [FEAT] Harden the shared sandbox producer with gtm's terminal robustness + reconcile the wire vocabulary #242 + #428 + #434; preserve durable detach/reconnect while deleting the fork.

Phase 6 — Creative plan mode:

• tangle-network/creative-agent#435 — adopt chat plan mode after #428 and #436; sequence separately because it overlaps the chat page, producer, and interaction paths.

Phase 7 — Creative feature bundle:

• tangle-network/creative-agent#429 — mentions + attachments + shared skills after #428 and #435; keep last in Creative because it overlaps the chat page/composer and producer seams.

Phase 8 — graduate shared seams after adoption evidence exists:

• [REFACTOR] Graduate the @experimental single-consumer turn-lifecycle seams #227 — graduate the @experimental seams only after the app adoptions above provide the required second consumers.

Track B — upstream-gated (blocked on agent-dev-container; act on the trigger, never schedule)

Gate 1 — adc#3853 publishes agent-profile-materialize ≥0.6.0 to npm:

• [FEAT] Make the shared skills module adoptable — one loader, both delivery modes, harness-aware placement #216 — adoptable skills module (PR feat(skills): adoptable skills module — one parser, both delivery modes, harness-aware placement #218 is ready, blocked on the publish)
• tangle-network/gtm-agent#609 — gtm skills pipeline (work done in worktree, blocked on [FEAT] Make the shared skills module adoptable — one loader, both delivery modes, harness-aware placement #216 publishing)

Gate 2 — ✅ DONE 2026-07-24 (was: open): @tangle-network/sandbox 0.12.0 published stable (via adc#3982 merge → release train), tarball-verified to carry filesystemIncarnationId AND splitInlineProfileSkills. Both vault fixes shipped:

• tangle-network/gtm-agent#612 — vault mass-deletion fix — MERGED (PR #623, sandbox ^0.12.0)
• tangle-network/gtm-agent#616 — chat-path vault self-heal — MERGED (PR #623); same-incarnation in-place wipe repaired by a cheap emptiness probe (incarnation identity only catches filesystem replacement)
• gtm skills-payload split via splitInlineProfileSkills — superseded: traced 2026-07-24, that utility cannot fix the per-turn case (create-only); the real fix is Gate 4 below (gtm#625 + adc#4031)

Gate 4 — adc#4031 (public primeProfile/attachProfileReference) merges + ships in a stable @tangle-network/sandbox release (PR adc#4033 open):

• tangle-network/gtm-agent#625 — defer inline skills from the per-turn payload: persist {skillsCorpusHash, profileSha256} per sandbox, attach/prime on each turn (gtm wiring half; blocked on the SDK publish)

Gate 3 — ✅ CLOSED 2026-07-24, collapsed to a one-line fix. The execution-roots architecture proved unnecessary: the serialization was a GTM-side workspace-scoped turn lock, and vault safety already lives in gtm's persistence layer (per-path revision CAS, conflict retention, the #612 blast-radius guard). adc#3801 and #208 closed as not-planned; gtm#604 rescoped and shipped as gtm PR #622 (thread-scoped lock). Residual watch item: box-lifecycle races under concurrent turns are untraced.

• [FEAT] Propagate isolated execution roots through sandbox chat orchestration #208 — closed not-planned (superseded)
• tangle-network/gtm-agent#604 — shipped via gtm#622 (one-line lock-scope flip)

Dependency notes

• tax#383 is a live production defect — it can merge before anything else.
• The three UI-cascade issues (tax#386, legal#272, creative#425) are one recipe applied three times; sequence one, copy to the rest. They gate the sandbox-ui 0.84+/0.87 client components — composer-attach UX and the mention UI (gtm needed sandbox-ui 0.87 for mentions in gtm#614). They do not gate any server-side vertical work.
• Creative's remaining chain is intentionally serialized around overlapping files: completed #427 → #434 → #428 → #436 → #435 → #429. [FEAT] Harden the shared sandbox producer with gtm's terminal robustness + reconcile the wire vocabulary #242 runs in parallel with #434 but must land before #436.
• gtm#612 fail-closes on missing incarnation fields — merging before the stable SDK publish would break sandbox provisioning; the develop-prerelease pin must not ship to master.
• App feature issues state their own agent-app bump requirements; they consume whatever version includes the Phase-1 uplifts they need.
• Tax and legal dependency baselines are complete at agent-app ^0.43.54; their remaining ordering is now driven by code overlap, not package versions. Tax's three feature tasks are parallel-safe. Legal must sequence #277 → #278 → #271, while #279 runs independently.
• Skills adoption required an agent-interface bump. Tax and legal baselines now include agent-interface ≥0.31; creative (^0.32) was already clear. Keep those floors while implementing tax#390, legal#279, and creative#429.
• Attachments = consolidate-first. [FEAT] Uplift the attachment client half — structured dispatch + eager file-part promotion #224 uplifted only the attachment data half; the route + React surface were still forked in gtm. Rather than let legal#271 write a second bespoke copy, [FEAT] Graduate the shared chat-attachment surface — upload-route factory + composer hook + transcript renderer #234 graduates that surface into agent-app first (sourced from gtm's proven code), legal#271 consumes it as the first consumer, and gtm#621 migrates onto it as the second — the ≥2-consumer graduation [REFACTOR] Graduate the @experimental single-consumer turn-lifecycle seams #227 tracks. legal#271 is functionally gated on [FEAT] Graduate the shared chat-attachment surface — upload-route factory + composer hook + transcript renderer #234 publishing; the storage difference (legal's R2 is not sandbox-mounted, unlike gtm's KV vault) stays in legal's turn seams, never in the shared surface. legal#271's clean switch drops the chat→vault write path; restoring a deliberate user→vault upload is spawned as legal#275 — a vault-page (document-management) feature, not a chat-vertical item and outside this epic. legal#271's e2e coverage lives inline (in-memory through createChatTurnRoutes + manual recipe); no separate browser-e2e ticket.
• Track B is fully parallel to Track A — nothing in Track A waits on it.

Non-goals / open decisions

• Shell consolidation (sandbox provisioning, AgentProfile assembly, system-prompt assembly, per-turn model resolution — docs/agent-shell-consolidation.md, still a proposal) is out of scope: it is a second epic-sized effort. This epic covers the chat vertical only; each app keeps its provisioning layer for now.
• creative Missions engine: remains its own autonomous-run concept, out of this epic. Chat plan mode for creative IS now in scope (creative#435), which embeds the small Missions-relationship decision as its first task.
• tax attachments + vault-write stay out by design: tax's encrypted R2 document vault (AES-256-GCM, integrity trail) serves its need; the shared upload/object-store path is not a gap there (documented in tax#379).
• Fleet-wide nightly e2e matrix + version-skew policy: [INFRA] Ship the Phase-2 CI gates + nightly live-e2e from the #188 roadmap #226 lands the agent-app nightly; extending it to a per-app matrix and adopting a drift policy is process work, tracked outside this epic.

Safety rules

• No app ships a -develop.* prerelease pin of @tangle-network/sandbox to its default branch.
• Migration waves follow the proven gtm pattern: net-negative LOC, no-mocks e2e per wave, product-specific rendering preserved via seams/slots — never re-forked.

Ideal end state

agent-app documents and owns the entire generic chat vertical (turns, replay, interactions, plans, mentions, attachments, skills); each app's chat is a thin set of product seams; a new app can build chat from the README quickstart alone; nightly live-e2e guards the contract fleet-wide.