feat: chat-context memory ACL — per-team/channel/user agent memory with fail-closed scoping

[Weegy]

Agent memory is isolated per agent today, but not per chat context. What an agent learns in Teams team A lands in one agent-global tree and is quotable in team B on the next turn. This wave partitions that tree by chat context, fail-closed, and ships it off by default.

Refs #871 #872 #873, part of #860. Design: #870 (comment 5412545550) plus the coordinator decisions (comment 5422379504).

---

What this is

scope = axes.isContextFree
  ? ['core', `orchestrator:${slug}:*`]                        // exactly today
  : ['ro:core', `ro:orchestrator:${slug}:*`, …axes.patterns]  // enforce
  : ['ro:core', …axes.patterns]                               // enforce-strict

• Scope grammar — ScopedMemoryStore gains team:<ctxKey>:*, channel:<ctxKey>:*, user:<ctxKey>:* and an ro:<pattern> access modifier. The context trees live under a new top-level segment /memories/contexts/, deliberately not under /memories/orchestrators/<slug>/: orchestrator:<slug>:* matches only the agent tree, so no legacy scope reaches a context tree and no context scope reaches the agent tree. That placement is the structural collision-freedom argument — please don't "tidy" the two trees together.
• Context key — memoryContextKey(channelType, nativeId) is the single sanitiser behind every <ctxKey>, every physical path, every purge selector and the promote route.
• Per-turn binding — MemoryBinder.forOrigin() resolves one stack per chat context (LRU, cap 256) once at the start of each turn; the orchestrator threads the result to dispatchTool as an explicit parameter.
• Operator surfaces — the Danger-Zone purge axes user/team/channel get a scratch footprint for the first time; POST|GET /api/v1/admin/memory/promotions/:slug is the one way knowledge crosses a context boundary, on the same auth gate as purge; the memory browser gains a context dimension, a promote dialog and an audit tab.
• No flag day — agents.context_memory (off | enforce | enforce-strict, migration 0050) defaults to off, and ChatTurnInput.origin is optional. Every combination of old/new middleware and old/new channel plugin behaves exactly as today until an operator switches an agent over.

Security properties, and how each is tested

Every assertion below is store-level. Nothing here depends on LLM output, and per the repo's documented cross-file pollution bug every test builds its own InMemoryMemoryStore + binder per test — no module-level fixtures.

Property	Proof
Team A ↮ Team B	memoryContextIsolation.test.ts — A writes, B's view says "does not exist", B's list('/memories') shows only B's own notes, and an explicit read of A's physical path from B's compiled scope raises MemoryScopeViolation (soft-deny on the model surface, hard at the store)
Channel ↮ Channel	same file — two channels of one team stay apart while both reach the shared team tier
User ↮ User	same file — two personal chats, isolated
Agent ↮ Agent	memoryBinder.cache.test.ts — two binders, one root store, same origin: neither sees the other's tree
ro: blocks writes	memoryContextIsolation.test.ts + scopedMemoryStore.contexts.test.ts — read/list/exists pass; write/create/delete/rename raise MemoryScopeViolation, including rename across the boundary in both directions
The shared trees are not a side channel	memoryContextIsolation.test.ts — A cannot write /memories/core/* or /memories/_x/*, and cannot rename a private note out into core; B sees neither
The audit log is tamper-evident	same file — every agent can read /memories/core/audit/…, none can write or delete it
Two structurally different scopes never share a tier	memoryAxesForOrigin.test.ts — three pairs that all collapse to the same formatSessionScope string resolve to different tiers
A digest-shaped id cannot pre-image a context	memoryContextKey.test.ts + memoryContextIsolation.test.ts
Fail-closed	effectiveMemoryScope.test.ts — missing origin, unscoped, system, unknown channel type, unusable patterns and malformed axes all return exactly orchestratorMemoryScope(slug), golden-compared against the real function rather than a re-spelled literal
off is byte-identical to today	memoryContextIsolation.test.ts — for every origin, with the flag off and with it defaulted, and the note lands in the agent tree with no /memories/contexts created at all
enforce-strict quarantines legacy knowledge	same file — a context turn cannot even read the agent tier
Migration applies twice	verified against a scratch postgres:16-alpine: all 50 files applied twice cleanly, one agents_context_memory_check constraint, existing rows default to off, and the CHECK actually refuses an unknown mode

Review findings and their resolutions

Blockers

Finding	Fix
memoryContextKey not injective: the passthrough and digest branches shared one output space, so an already-safe id spelled x-<16 hex> pre-imaged a hashed context's key	The two output spaces are now disjoint — a raw id matching the digest shape is itself hashed
memoryAxesForOrigin keyed on formatSessionScope, injective only over the strings parseSessionScope emits while §4 has adapters build scopes directly: group 'x' and conversation 'group:x' shared one tier, as did channelId+id and the unescaped concatenation	Keys derive from an injective JSON tuple of the structural scope parts
The shared trees (core, sessions, chat-sessions, _*) were read-write from a context turn, so /memories/core/notes.md was a one-line bypass of the whole ACL	Context turns get ro:core; writing the shared trees stays a context-free privilege
memoryBinder.ts contained raw NUL bytes — git classified the wave's most security-critical file as binary, unreviewable in the PR	Separator is '�'; the file is text
promoteMemory on move deleted dotfiles it had never copied (list() skips .-names in both backends, the recursive delete does not), reporting success	move deletes only the exact paths it wrote; an emptied source directory survives, which is the safe direction
promoteMemory accepted a target nested inside the source, which move then wiped along with it — net knowledge destroyed, success receipt	Either root being a path-prefix of the other is refused (target_overlaps_source)
A purge selector without a ~ matched nothing but returned 200 with a warning claiming the scratch trees were affected — and the shipped placeholder invited exactly that spelling	400 invalid_selector; both hints and placeholders now say "never a bare id"
web-ui danger-zone copy asserted purge semantics the backend did not implement	The backend lands in this same PR, and the copy was corrected to the selector format actually accepted

Majors

Finding	Fix
ro: was a weak grant, not a deny — any overlapping non-ro: pattern silently re-granted write	ro: is a veto, evaluated before the positive check
The promotion audit log was writable by every agent (it sits under core, which every agent holds read-write)	/memories/core/audit/ is an agent-unwritable deny prefix
effectiveMemoryScope audited a broken axes object only in enforce-strict — the mode production does not run — while its JSDoc promised otherwise	axes-missing and no-usable-context-pattern audit in both modes; context-free stays quiet, which is what the original rationale actually covered
The purge warning claimed an effect on zero-target selectors	The resolved target count is passed in; zero says so
The user axis fed its two legs incompatible selector spellings and half-executed silently	A warning names which leg was a no-op (no KG filter invented — §7 rules that out)
The promote route documented an atomicity the service does not provide	Any failure outside the pre-write validation set answers partial: true
ContextMemoryNamespacer aliased the private root to ~team on org turns, breaking its own bijection	The shared root is published under its plain name
The namespacer's doc and test claimed context-free construction "reproduces the legacy namespacer exactly" — false for ~team/~agent	Doc qualified; the divergence is now asserted in its own test
web-ui: promote client pointed at an unmounted path; response envelopes were unchecked casts (entries.length on undefined white-screens the page); the tree's error path was unreachable so every failure rendered as "no data"; decodeContextKey called a digest a nativeId, inviting an operator to paste it into a destructive selector	All four fixed; the tree now shows the verbatim channelType~safeKey, which is the form the selector accepts
teams-origin-producer does not typecheck in a clean tree (its @omadia/channel-sdk maps to the main checkout, which has no TurnOrigin)	Merge-order gate, not a code defect — recorded under "what is deliberately not here"
telegram-origin-producer was committed straight onto local main of its own repo, no branch, never pushed	Same — out of this repo's scope

What came from the unit branches vs. what was built here

Merged from unit branches (12): context-key, turn-origin-contract, scope-grammar-contexts-tree, effective-scope-fail-closed, context-namespacer, memory-binder, purge-context-axes, promote-service, promote-route, web-ui-context-browser-promote, plus the SDK barrel export carried on teams-origin-producer. Two conflicts were resolved by content, not by -X ours: the two independently-written contexts test suites were split into scopedMemoryStore.contexts.test.ts (grammar) and effectiveMemoryScope.test.ts (resolver), and the two independent re-implementations of the grammar in scopedMemoryStore.ts were collapsed onto one.

Reconciled here. Three units re-implemented the same primitives while working in parallel. Collapsed onto one definition each: harness-orchestrator/src/turnOrigin.ts deleted in favour of the channel SDK's; the standalone contextMemoryNamespacer.ts deleted in favour of the MemoryNamespacerBase version; the binder's second copy of effectiveMemoryScope dropped in favour of the one with the pattern allowlist; scopedMemoryStore no longer structurally mirrors MemoryAxes, it imports it; and contextTierRoot() became the single source of truth for a tier's physical root.

Built here (the three units whose agents died mid-run):

• turn-threading — MemoryBinder.forOrigin() runs once at turn start in runTurnCore and in the streaming mirror, and the result travels as an explicit parameter through executeDirectLine → chatInContext(Inner) / chatStreamInner → prepareStreamSlot → dispatchTool → dispatchToolDeadlined → dispatchToolInner. Deliberately not turnContext (AsyncLocalStorage): a generator is resumed in its caller's async context, which is exactly how turnContext.enter was silently losing the turn context on every streaming turn before W3-A. A binding lost that way would not fail — it would quietly fall back to the agent-global tree. The system prompt gains the ~team/~agent convention on context-bound turns only, so a non-context turn's prompt (and its cache key) stays byte-identical.
• http-api-origin-fail-closed (coordinator decision 1) — orchestratorDispatcher forwards metadata.origin through a validating reader; a shape it does not recognise is dropped, which resolves context-free. routes/chat.ts and harness-channel-api/chatRouter.ts emit no origin at all, with the reasoning recorded in both: their scope strings are caller-supplied transcript labels ('http-default' is shared), so deriving a memory partition from one would let any caller name another's tier.
• wiring-rollout-flag — migration 0050 (CHECK guarded by a pg_constraint probe so the file applies twice), a deny-default parser in configStore (unknown/NULL → off), buildOrchestrator building the binder unconditionally and gating it by mode so off and today's stack are one code path, both barrels, and the promote-router mount.

The three coordinator decisions, as implemented

1. HTTP/API turns without a resolvable origin get the agent-private scope only — byte-identical to today, no implicit team or channel access for API callers. The HTTP dev route and the API channel emit no origin; both files carry the reasoning.
2. The team tier is read-write from a matching team-context turn; the agent tier stays read-only from context turns (ro:orchestrator:<slug>:*), so "note this globally" cannot become a permanent leak channel from team A into team B. Cross-tier sharing is the operator promote action, nothing else.
3. enforce-strict is settled, not an open question — an unknown or unparseable origin resolves to the agent-private scope and logs loudly; never a throw on the message path, never a wider scope. In strict mode a context turn cannot even read the agent tier.

Deviations from the spec, and why

• Promote mount — the spec asks for /api/agents/:slug/memory/promotions, the real purge router lives at /api/v1/admin/memory/purge behind requireAuth, and the spec also says "same gate as purge". Mounted at /api/v1/admin/memory/promotions/:slug rather than introducing a third auth surface for a Danger-Zone-class action.
• Migration number — the coordinator note says 0049/0050 are taken; middleware/migrations/ actually tops out at 0049_agent_teams_identities.sql on current main, so this is 0050.
• agentGraphStore column — the spec names it, but that module has no DDL and no agents access. The column is a core migration read by registry/configStore.ts and lifted into AgentRuntimeConfig, matching how every other per-agent flag works.
• memoryContextKey idempotence — the spec's purge selector relies on it. Kept for ordinary safe ids, dropped for the digest shape, because idempotence there is the pre-image hole. The purge selector resolves both readings and acts on the union of the trees that actually exist.
• web-ui — §9 lists the operator UI as an explicit non-goal while the wave brief covers "operator surface". It is included, its findings are fixed, and its one real limitation is recorded below rather than hidden.

Gates

Gate	Result
middleware npm run typecheck	clean
middleware npm test	7666 tests, 7650 pass, 0 fail (rest skipped: PG-dependent cases)
test-typecheck ratchet	passes, and the debt drops 371 → 370
Migration double-apply	verified twice against a throwaway postgres:16-alpine; container removed
web-ui npm run lint	exit 0, zero errors
web-ui npm run typecheck	clean
web-ui npm test	886 tests, 886 pass
web-ui npm run i18n:check	OK — 3914 keys, en + de

Known limitations / follow-ups

• The memory browser's context tree is dev-only today. It reads GET /bot-api/dev/memory/list, which is unauthenticated and never mounted in production, so the panel is inert there. §9 puts the operator UI outside this wave, so no operator-gated listing endpoint exists yet. What this PR guarantees is that the absence is now visible — a non-404 failure reaches the error state instead of rendering as an empty tree. Backing it with an operator-gated listing (matching the purge gate) is the follow-up.
• The channel plugins are not in this PR. omadia-channel-teams and omadia-channel-telegram build the TurnOrigin in their own repos and cannot compile until @omadia/channel-sdk ships TurnOrigin. That is a merge-order gate: land this, release the SDK, then their PRs. Until an operator also flips context_memory, the flag stays off and nothing changes either way.
• promoteMemory is not atomic. The write loop has no rollback and move deletes after it. This PR makes the ambiguity honest (partial: true) rather than pretending otherwise; attaching a partial receipt to a mid-flight failure is the durable fix.
• Promoted files land in the target tier but the KG is untouched for the team/channel axes — §7 rules out inventing a KG filter, and the purge route now says so instead of implying coverage it does not have.

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}