feat(coding-agents): add per_source observation scoping

[shauneccles]

Closes #3871.

The problem

On a repo worked by a coding agent, this plugin writes documents from genuinely different origins into one bank: commit diffs (source:git), the commit-message seed (source:git + source:git-log), session transcripts (source:chat), uploads (source:upload).

A commit diff records what the code actually does. A transcript records what someone intended, argued for, or discarded. Under the shared default these consolidate into one undifferentiated belief set, so:

• an idea floated in chat and never implemented is indistinguishable from a belief derived from the diffs;
• "what does the codebase actually do" cannot be answered from commit-derived knowledge alone;
• when the two conflict, consolidation reconciles them into a single belief rather than keeping both claims with their origin intact.

Why this cannot be done with configuration

This is the crux, and it is why the change is code rather than a docs note.

observationScopes already accepts an explicit string[][], so the obvious answer is "just configure [[], ["source:git"], ["source:chat"]]". That does not work. The server treats an explicit list as unconditional — it is never filtered against the memory's own tags. In hindsight-api-slim/hindsight_api/engine/consolidation/consolidator.py, both resolvers end the same way:

def _resolve_obs_tags_list(memory): ...
    return parsed  # explicit list[list[str]]

def _resolve_write_scopes(memory): ...
    return [frozenset(s) for s in parsed]  # explicit list[list[str]]

parsed comes back verbatim. So that configuration writes every document into all three scopes: the source:git scope fills with observations built from chat transcripts and vice versa. The scopes exist but mean nothing, which is worse than not having them.

Every scalar mode the server offers derives its scopes from the memory's own tags, but none derives from part of the tag set. Only a per-document decision, made where the tags are known, separates these.

The change

"per_source" becomes an accepted observationScopes value. It is resolved client-side, per document, in a new exported resolveRetainScopes(tags, configured) in src/core/hindsight.ts, and never reaches the server. It expands to the global scope plus one per distinct source: tag the document carries, sorted:

document	tags	resolved scopes
session transcript	source:chat	[[], ["source:chat"]]
commit diff	source:git	[[], ["source:git"]]
commit-message seed	source:git, source:git-log	[[], ["source:git"], ["source:git-log"]]
no source tag	knowledge:convention	[[]]

A document may legitimately carry more than one source tag — the commit-message seed keeps source:git alongside source:git-log so the cold-repo check (listDocumentIds("source:git")) still sees it — so every distinct one gets a scope. Taking all of them, sorted, is the only rule that needs no arbitrary tie-break and does not silently depend on the order git.ts happens to emit its tags in.

this.observationScopes still flows to the single call site that sets the field; only the value it resolves to is now per document.

On "double the consolidation cost"

That is the explicit rationale of #3575, so it deserves a direct answer rather than a footnote.

Yes: per_source costs one extra consolidation pass per document (two for the commit-message seed). The difference from the case #3575 was right to refuse is what the extra pass buys. Splitting on harness:<id> is provenance — which agent typed it — and the extra pass buys two copies of the same belief, each blind to the other. Splitting on source: is semantic: the origin changes what kind of claim the document is making, and once a commit-derived belief and a chat-derived belief merge into one observation, no read-side filter can separate them again, because the merged observation has a single origin-free identity.

So the cost is real, it is the price of the axis, and it is why this is opt-in.

Why not per_tag

per_tag splits on the right axis but also on every other one — _resolve_obs_tags_list maps it to [[t] for t in tags], unconditionally. It would reinstate the per-agent harness: fork that #3564 and #3575 removed, and any volatile tag (a session id added through retainTags) would become its own scope, which is the fragmentation bug itself. Reading only source: is what keeps the split safe: a small, closed, meaningful set of values the plugin itself controls.

What is deliberately unchanged

• The default. DEFAULT_OBSERVATION_SCOPES is still "shared". A user who never sets this sees no behavior change.
• Knowledge pages. The empty scope is always emitted first and unchanged, so the untagged observations the seeded pages read (tags_match: "all", per fix(coding-agents): let knowledge pages see the observations they ask for, and stop tagging initiative markers with a page id #3664) keep being written exactly as under shared.
• Nothing repurposed. fix(consolidation): separate tags from observation scopes #2853 asked that changes here be "ideally additively (a new, clearly-named field)". This is a new accepted value on an existing field — no existing value changes meaning.

One test was widened — deliberately

The source-text guard in hindsight.test.ts ("keeps that call site inside retain(), with the scoping on the item it posts") went from

expect(body).toContain("observation_scopes: this.observationScopes");

to

// The scoping may be derived per document (see `per_source`), but it must still be set on the
// item here and still come from the configured value — not from a server default.
expect(body).toMatch(/observation_scopes: .*this\.observationScopes/);

Flagging it explicitly so it does not read as weakening a test. The guard's intent is intact: the field must still be set inside retain(), on the item it posts, and still derive from this.observationScopes rather than being left to the server default. The regex only allows the value to be wrapped in a resolver. A call site that dropped the scoping, moved it out of retain(), or hardcoded a value still fails.

Lineage

• coding-agents: the always-on harness:<id> tag splits observations per agent, undoing the harness-neutral bank — please make it optional #3564 — the harness:<id> tag splitting observations per agent
• fix(coding-agents): consolidate one set of observations per bank #3575 — introduced observationScopes and the "shared" default
• fix(coding-agents): let knowledge pages see the observations they ask for, and stop tagging initiative markers with a page id #3664 — knowledge pages read untagged observations with tags_match: "all"
• fix(consolidation): separate tags from observation scopes #2853 — asked for changes here to be additive

Test plan

• npx tsc --noEmit — clean
• npx vitest run — 55 files passed, 665 passed / 23 skipped
• npm run build — succeeds
• npm run skill:build and node hindsight-docs/scripts/sync-coding-agents-doc.mjs re-run, generated output committed
• prettier 3 with the repo's root .prettierrc.json over every changed file (matching the prettier-int-coding-agents task in scripts/hooks/lint.sh) — clean. Three files under this package (src/core/retain-cursor.ts, src/dsh.ts, src/install-ui.ts) are flagged by that task on main as well; they are untouched here and left alone.
• src/docs-freshness.test.ts — 12 tests pass

Six new tests cover per_source end to end at the wire level (the global-plus-source expansion, git vs chat separation, the untagged fallback, the two-source-tag seed, order independence, and a volatile provenance tag never becoming a scope), plus one covering config acceptance.

I could not run ./scripts/hooks/lint.sh in full — it starts with uv sync for the whole monorepo and my checkout is sparse — so the Python and control-plane tasks are unverified, though nothing here touches them.

[strix-security]

Strix Security Review

Warning

This pull request has 2 commits after the last Strix review (a9a729f). Strix has not reviewed these changes.
Automatic review on push is off for this repository. To review the latest changes, tag @strix-security in a comment, or turn on re-review on push.

No security issues found.

_{Updated for a9a729f.}

---

Reviewed by Strix
_{Re-run review · Configure security review settings}

[koriyoshi2041]

The per-document resolution keeps the existing shared scope while separating only the controlled source axis, and it avoids sending the plugin-only mode to the server. I also checked the multi-source and no-source cases at a9a729f: 85 focused tests pass, along with typecheck and the package build.

[shauneccles]

Sorry for the noisy last two commits - I missed the root cause of another issue (#3874) and got a bit confused. It's been a big day 😅

[koriyoshi2041]

The two follow-up commits leave the implementation unchanged and make the multi-tag intent clearer: the git-log seed and per-commit diffs answer different questions, so retaining both controlled source scopes is correct. Re-reviewed at 1a98249.