fix(security): scope the entity-id resource handlers by user_id (#2093)

[markmhendrickson]

Closes #2093

Design basis: no design applies — localized MCP entity-id resource handler user_id scoping bug (#2093); no new work-model or gate declaration. Kernel path docs/foundation/principles.md is not present on main (404), so a foundation citation would itself fail the “named document must exist” check.

What was wrong

Three MCP resource handlers reachable by entity id queried the database with no ownership filter:

Handler	Tables read unscoped
handleIndividualEntity	entities, entity_snapshots
handleEntityObservations	observations (rows and count)
handleEntityRelationships	relationship_snapshots (both directions)

Six queries. #2093 named the first; the other two carry the same defect through the same door, and are fixed here rather than left for a second report — the id is the whole key, and nothing about the attack depends on which suffix follows it.

The fix

Each handler resolves the caller through getAuthenticatedUserId() — which throws when unauthenticated, so the restrictive branch is the default — and adds .eq("user_id", userId) to every query.

This is the convention the file already follows rather than a new one: 21 other queries against relationship_snapshots scope this way, and the entity_snapshots and observations paths in the query layer do the same. The handlers were the outliers.

Tests

tests/security/mcp_resource_tenant_isolation.test.ts, a companion to tenant_isolation_matrix.test.ts — which covers the HTTP query endpoints and states the obligation these handlers were missing from:

Every authenticated query endpoint that touches user-owned data (entities, observations, sources, relationship_snapshots, timeline_events, entity_snapshots) MUST be covered here.

Eight cases. Each resource is an owner-reads-own paired with a second authenticated user reading the same id and getting nothing. Two are worth calling out:

• The inbound relationship direction has its own case. A fix applied only to the outbound query would pass every other assertion in the file, because the outbound tests never touch the target entity. That is the partial fix that looks complete, so it gets its own planted negative.
• An unauthenticated caller is refused before any query runs. This pins the fail-closed property to the handler rather than to the database.

Verified as evidence, not decoration

With src/server.ts reverted to the pre-fix state and the server rebuilt, 5 of the 8 fail — every cross-user case plus the unauthenticated one. With the fix, 8 pass.

Full security suite: 96 passed, 1 skipped, across all 8 files.

One test was wrong on the first run and the system was right: I asserted a seeded snapshot literal that the recomputation pipeline legitimately overwrites with the value derived from the owner's observation. Corrected to assert the owner's actual marker.

Scope

Read-path scoping only. No schema change, no migration, no change to the write path or to any HTTP endpoint. handleEntityCollection and the timeline handlers are untouched — they route through the scoped query layer already.

🤖 Generated with Claude Code

[neotoma-agent]

🤖 Lanius — Ateles swarm, PR gate inheritance
BLOCKED

Prior-art check: parent #2093 / PR #2362; existing Lanius comment 5623709964 — editing in place. Authoritative gate_status from Neotoma issue entity (not GitHub body).

Triage & Gate-Status Board

Gate	State	Owner	Source
pm	pending	Pavo	Neotoma ent_202c6e99028c54c376716332.gate_status
ux	not_required	Accipiter	same (bug fast path)
arch	pending	Waxwing	same
impl	pending	Cicada	same
pr_review	changes_requested	Vanellus	same (Vanellus REQUEST_CHANGES artifact)
qa	pending	Phoenicurus	same
legal	not_required	Buteo	same

Unsigned pre-impl gates (blocking inheritance):

• pm — owned by Pavo
• arch — owned by Waxwing

ux is not_required (workflow_type bug).

Owner: issue current_owner = cicada. Next after pre-impl clear: Vanellus (pr_review).
Labels: none on this PR inheritance pass.

• Parent issue from PR body: Closes #2093
• Live Neotoma gate_status retrieved before decision
• Canonical owners from agent_definition (pavo, waxwing)
• pm signed_off / waived
• ux not_required
• arch signed_off / waived

Normal resolution: gate owner sets gate_status.<gate> → signed_off in Neotoma, or operator waives that gate.

Operator override: /confirm-gates-clear — only @markmhendrickson may issue this command; it waives all unsigned pre-impl gates and re-triggers the PR pipeline. No other commenter can clear gates.

---

📎 Neotoma: issue ent_202c6e99028c54c376716332

[neotoma-agent]

review:security
🤖 Falco — Ateles swarm, security lens panelist
COMMENT

Prior-art check: searched issues/PRs for 2093 entity resource user_id tenant isolation; found parent #2093, this PR #2362, policy umbrella #2361, sibling count-scope #2041/#1889. No duplicate PR already lands the entity-id handler fix; #2361 says #2093 should land independently first. Editing prior Falco comment 5623784291 in place (not duplicating).

Diff-only note: no PR checkout/execution this run. Reviewed the PR diff plus PR-head src/server.ts / src/services/entity_queries.ts via GitHub raw. Runtime claims remain PLAUSIBLE unless closed by static path alone; per the dispatch evidence bar I will not [BLOCKING] adjacent sinks outside this PR's six queries.

Sinks Enumerated

Pattern: MCP ReadResourceRequestSchema → parseResourceUri → handlers that read user-owned tables (entities, entity_snapshots, observations, relationship_snapshots, sources, timeline_events) where the safety field is user_id.

Covered by this PR (six queries):

• handleIndividualEntity — entities + entity_snapshots: now id/entity_id and getAuthenticatedUserId() → .eq("user_id", userId)
• handleEntityObservations — observation rows + count: same
• handleEntityRelationships — outbound (source_entity_id) and inbound (target_entity_id): same

Adjacent sinks NOT covered (same resource door; out of #2093's narrow id-suffix scope):

Handler	Scope source	Fail-open when
handleEntityCollectionAll / handleEntityCollection	queryParams?.user_id → queryEntities	userId omitted → no .eq("user_id") (entity_queries.ts); valid foreign UUID scopes to that UUID
handleRelationshipCollectionAll / handleRelationshipCollection	optional URI user_id	absent → unscoped relationship_snapshots read
handleSource	none	id-only sources + observations by source_id
handleSourceCollection	optional URI user_id	absent → unscoped sources
handleTimelineYear	none used (param accepted, never applied)	always unscoped timeline_events
handleTimelineMonth	optional URI user_id via source ids	absent → unscoped timeline rows
ListResourcesRequestSchema counts	none	unscoped entity/relationship/source counts (#2041/#1889)

PR body correctly notes collection/timeline handlers are untouched; that is accurate and is why these stay NON-BLOCKING on this PR.

Encodings Tested (static)

Against the fixed entity-id path:

• Canonical foreign entity id → reaches guarded sinks; auth user_id predicate applies.
• ?user_id=<victim> on neotoma://entity/{id} → query params ignored for entity-id types (parser returns no queryParams for those branches).
• Percent- / double-encoding of path id → parseResourceUri does not decode path segments; literal id ≠ DB id (no canonicalize-to-victim path found).
• Unicode / case folding / trailing dots / whitespace on entity id → no normalization before .eq("id", …).
• Extra path segment (…/observations/extra) → still routes via first-three-segment destructure; lands on guarded handler, not a bypass.
• IPv4-mapped / DNS / redirects → N/A (DB equality sinks, no network guard).

Against collection user_id input (adjacent):

• Invalid / non-UUID / whitespace-padded user_id silently dropped (parseResourceUri UUID regex) → treated as absent → unscoped collection read (fail-open).
• Valid victim UUID → selects victim scope (caller-chosen tenant).

Fail-Open Branches

Fixed handlers: none found. getAuthenticatedUserId() throws if unauthenticated; all six queries carry returned userId. DB errors throw MCP errors (no foreign data). Cross-tenant id collapses to Entity not found (no ownership oracle beyond id existence-as-not-found).

Adjacent (explicit ALLOW-unscoped defaults):

• Optional URI user_id absent or malformed → collection/source/relationship handlers omit tenant filter.
• handleTimelineYear never applies user_id at all.
• Collection catch-blocks return empty/error payloads (not cross-tenant allow by themselves; can mask instrumentation).
• listResources without auth returns {resources:[]} (no data fail-open).

Cites docs/foundation/principles.md §5 Fail closed on the field that carries the safety meaning for the adjacent optional-user_id pattern — systemic, not opinion. Not a blocker for this narrow PR.

Findings

[NON-BLOCKING] PLAUSIBLE tenant isolation: MCP collection / relationship / source resource handlers still optional-URI-user_id or unscoped.

Detail: static path ReadResourceRequestSchema → parseResourceUri → handleEntityCollectionAll/handleEntityCollection (src/server.ts ~7647–7811), relationship collections (~8277–8508), handleSource/handleSourceCollection (~8161–8261). queryEntities only applies .eq("user_id", userId) when provided (entity_queries.ts ~395–401). Same isolation class as #2093; different URI shape. Tracked as security_finding ent_aef9efd90da8c4b540bc3066.

What would confirm: authenticated MCP read_resource as user A on neotoma://entities, neotoma://entities?user_id=<B>, neotoma://relationships, neotoma://source/{id}, malformed user_id. Confirm if B rows appear; refute if transport injects authenticated scope before these handlers.

[NON-BLOCKING] PLAUSIBLE tenant isolation: handleTimelineYear reads timeline_events with no user_id filter; handleTimelineMonth only scopes when URI user_id is present.

Detail: src/server.ts ~7962–8020 (year: user_id in signature unused); ~8039–8137 (month: optional). Outside #2093 entity-id scope.

What would confirm: seed timeline events for user B; read neotoma://timeline/{year} and {year}-{month} as user A with/without ?user_id=.

Narrowed Protection Check

Diff only adds getAuthenticatedUserId() + .eq("user_id", userId) on the six entity-id queries. No shared helper made more permissive. Guard helper itself still denies mismatched providedUserId and throws when unauthenticated.

Verdict

COMMENT. The six #2093 sinks are closed in the diff; no encoding bypass of those sinks found statically; no fail-open on the fixed path. Remaining concerns are adjacent resource-family handlers — do not treat the MCP resource isolation class as closed until those are confirmed or filed. Under the evidence bar: no [BLOCKING] / no REQUEST_CHANGES for unverified runtime adjacent paths.

📎 Neotoma: security_finding ent_aef9efd90da8c4b540bc3066 (not yet guest-readable; id in prose per visibility rule) · issue neotoma#2093

[neotoma-agent]

review:pm
🤖 Pavo — Ateles swarm, pm lens panelist
SIGNED_OFF

Prior-art check: re-checked #2093 / #2362 / neighbours #2361/#2041/#1889. No duplicate fix PR; operator note on #2093 still says this lands independent of #2361. Re-review against HEAD d2c31b0fd (post design-basis body fix + empty re-triggers).

Diff-only PM lens (no checkout/exec). Standing criteria: match to #2093 intent, no unrequested product scope, user-visible behaviour matches the issue. Parent gate_status.pm = signed_off on ent_202c6e99028c54c376716332 (last_observation_at ~2026-09-10T20:31Z); judged against issue body + PR scope (swarm-spec section still empty — standing lens, not a pre-registered DoD artifact).

Scope vs intent

Issue asked	PR delivers	Fit
Scope handleIndividualEntity (entities + entity_snapshots) by authenticated user_id	Done in src/server.ts	Match
Same defect on observations / relationships resource suffixes	Also scoped (six queries)	Same-door security close — not product creep
Cross-tenant read blocked; owner still reads own	Test pairs assert both halves	Match (effect, not contract-only)
Cover the MCP resource door	tests/security/mcp_resource_tenant_isolation.test.ts	Intent met (companion to HTTP matrix; issue asked for a matrix row — companion file is acceptable same-obligation coverage)
Read-path only	No schema/API contract/write-path change	Match
Design basis named	Design basis: no design applies + reason (principles.md 404 on main)	Resolved — prior [BLOCKING] cleared

• Change matches #2093 problem (cross-tenant entity-id resource read)
• No unrequested product/feature scope
• User-visible denial for foreign entity id aligns with issue (“Entity not found” / empty sets) — static from diff; runtime verified by QA lens revert-red, not re-run here
• Design basis present in PR body
• Effect-verified acceptance (owner positive + cross-user negative + unauth fail-closed) — policy fixed_means_behavior_verified_not_contract_accepted
• Cross-surface parity for this capability: MCP resource door covered here; HTTP query door already in tenant_isolation_matrix.test.ts — policy cross_surface_contract_parity_tested_all_surfaces

Findings

[NON-BLOCKING] scope: Extending the fix from the named handler to handleEntityObservations / handleEntityRelationships remains the right sequencing call (same id door). Leave adjacent collection/?user_id= and source-resource sinks to #2361 / #2041 — do not widen this PR.

[NON-BLOCKING] acceptance-artifact: Issue swarm-spec section still empty. Panel acceptance is the issue body + this checklist; recording DoD on the issue body remains optional follow-up, not a merge blocker for this security close.

Verdict

SIGNED_OFF — design-basis blocker cleared; scope and user-visible intent fit #2093. No [BLOCKING] findings from the pm lens. Parent gate_status.pm already signed_off (no further writeback this pass).

Interface-surface routing note: bug-labelled; change is handler .eq("user_id") scoping only — not schema/OpenAPI/MCP tool/CLI/relationship-type/agent-instruction surfaces — so arch fast-path skip remains appropriate for this fix; arch is independently signed_off.

Reviewed commit: d2c31b0

---

📎 Neotoma: neotoma#2093

[neotoma-agent]

review:ux
🤖 Accipiter — Ateles swarm, ux lens panelist
APPROVE

Prior-art check: re-searched #2093 / entity-id MCP resource tenant isolation / neotoma://entity/{id} docs against HEAD d2c31b0fd. Found parent #2093, this PR #2362, policy neighbour #2361, count-scoping sibling #2041, denial-shape sibling #1588. No duplicate PR; no new agent-facing URI or action name. Editing prior Accipiter comment in place (not duplicating).

Diff-only UX review (no checkout/exec). Standing lens: agent/developer experience — discoverable naming, actionable errors, docs/examples. User goal under test: read one known entity (and its observations/relationships) under the authenticated tenant without ambiguity or silent wrong conclusions.

Design Spec (ux)

User-facing surface

• Existing MCP resources only: neotoma://entity/{id}, …/observations, …/relationships.
• No rename, no new template, no new action. Discoverability of the URI family is unchanged and already catalogued in docs/specs/MCP_SPEC.md (Individual Entity / Observations / Relationships rows).

Interaction / flow

1. Authenticated caller reads entity-id resource → scoped by getAuthenticatedUserId() + .eq("user_id", userId).
2. Unauthenticated → throw before query (Authentication required. Set NEOTOMA_CONNECTION_ID in mcp.json env…) — actionable next step.
3. In-scope entity → payload as before.
4. Out-of-scope / missing entity id on individual handler → Entity not found: {id} (no-oracle; matches #2093 intent).
5. Out-of-scope id on observations / relationships → empty arrays + zero totals (success-shaped empty).

Discoverability & naming

• Naming preserved; agents already know these URIs from MCP_SPEC / resource templates.
• No new surface requiring examples in this PR.

Error & empty states

State	Shape in diff	Agent recovery
Unauthenticated	McpError + setup hint (NEOTOMA_CONNECTION_ID)	Clear next step
Foreign/missing entity (individual)	Entity not found: {id}	Retry with own id / re-auth; no tenant leak
Foreign/missing id (observations/relationships)	Empty success payload	Easy to misread as “entity has no edges/observations yet”
Owner empty observations	Empty success	Correct empty

Accessibility

• N/A (MCP/CLI resource surface; no interactive UI in this diff).

Acceptance checklist (ux lens)

• No new ambiguous names or URI patterns
• Unauthenticated path keeps an actionable hint (existing getAuthenticatedUserId copy)
• Individual-entity denial stays explicit (Entity not found) rather than leaking foreign snapshots
• Observations/relationships denial is distinguishable from a true empty set (not required for Cross-tenant entity read: handleIndividualEntity does not scope by user_id #2093 security close; tracked below as non-blocking)
• MCP_SPEC denial contract for scoped entity-id reads documented (pre-existing gap; not introduced by this PR)

Findings

[NON-BLOCKING] silent-empty: handleEntityObservations / handleEntityRelationships return success-with-empty for out-of-scope ids while handleIndividualEntity throws Entity not found.

Detail (diff-evident): after scoping, a cross-tenant (or unknown) id on /observations or /relationships yields observations: [] / empty relationship arrays with total: 0 (src/server.ts handlers; tests assert empty for the foreign reader). An agent that deep-links to a suffix without first reading the entity can conclude “no data yet” and take the wrong next step (re-store, invent, or abandon). Prefer a follow-up (not this PR): if the entity row is absent under the authenticated user_id, throw the same Entity not found before returning empty collections — owner-true-empty stays empty; out-of-scope becomes an explicit error. Related standing pattern: #1588 (misleading “Entity not found” / denial shapes). Unverified at runtime this pass; confirm by acting as user B on user A’s id via MCP read_resource on both the entity URI and the /observations suffix and comparing agent-visible messages.

[NON-BLOCKING] docs: MCP_SPEC still says “User context is respected where applicable” and still teaches collection browse via ?user_id={uuid} without stating the entity-id denial contract this fix now enforces.

Detail: no docs/examples change in the PR (only generated test-catalog churn). For a security scoping fix with no new surface, that is acceptable under this lens. When #2361 / collection scoping lands, Paradisaea/docs should replace the vague line with: entity-id resources are always auth-scoped; foreign/missing id → not found (entity) / not found-or-empty policy as decided; do not pass user_id to select another tenant. Cite docs/specs/MCP_SPEC.md resource table + “When to Use Resources vs. Actions”.

Verdict

APPROVE — no UX merge blockers on this diff (HEAD d2c31b0fd, post design-basis body fix). No new agent surface; auth errors stay actionable; individual-entity denial is explicit. Asymmetric empty on observation/relationship suffixes is real agent friction but security-compatible and better as a follow-up than a blocker on #2093. Parent gate_status.ux remains not_required (bug fast path) — panel lens only; no gate writeback.

---

📎 Neotoma: neotoma#2093

[neotoma-agent]

review:qa
🤖 Phoenicurus — Ateles swarm, qa lens panelist
APPROVE

Prior-art check: searched #2093 / entity-id resource user_id scoping — parent #2093, this PR #2362, HTTP companion tests/security/tenant_isolation_matrix.test.ts, related #2361/#2041/#1889. No duplicate open eval PR; this branch already lands the regression file. Editing prior Phoenicurus comment in place.

Eval / regression coverage

Surface	Eval	Asserts	Result
handleIndividualEntity (neotoma://entity/{id})	tests/security/mcp_resource_tenant_isolation.test.ts	owner gets own snapshot marker; cross-user throws Entity not found	pass
handleEntityObservations	same file	owner total===1; cross-user empty observations + total===0	pass
handleEntityRelationships outbound+inbound	same file	owner sees outbound key; cross-user both directions []; inbound-only planted negative on target id	pass
Unauthenticated fail-closed	same file (+ probe)	authenticatedUserId=null → Authentication required before query	pass

Agent-facing surface: MCP resource handlers agents read via neotoma://entity/{id}[/observations|/relationships]. Assertions are deterministic isolation effects.

Evidence (ran this session)

Local green (fix present):

npx vitest run tests/security/mcp_resource_tenant_isolation.test.ts
✓ tests/security/mcp_resource_tenant_isolation.test.ts (8 tests) 22ms
Tests  8 passed (8)

Unauth probe — all three handlers refuse (not only the one planted in the suite):

handleIndividualEntity: MCP error -32600: Authentication required…
handleEntityObservations: MCP error -32600: Authentication required…
handleEntityRelationships: MCP error -32600: Authentication required…

CI (this head): baseline ✓ tests/security/mcp_resource_tenant_isolation.test.ts (8 tests) — run 34526830233. agentic_evals / security_gates also green. Isolation is covered by the security unit eval (test:unit → baseline); no separate agentic_eval fixture required for this auth-scoping fix.

Standing rules: docs/foundation/principles.md invariants 4–5 (test must be able to fail on the watched property; fail closed on user_id); change-guardrails MUST 5; GHSA-wrr4-782v-jhwh / tenant_isolation_matrix obligation met via companion MCP-resource file (handlers are not HTTP endpoints).

Checklist

• Regression for the fixed bug (cross-tenant entity-id resource read)
• Edge: inbound relationship direction has its own planted negative
• Edge: unauthenticated refused fail-closed (suite + all-three probe)
• Owner positive controls present (instrument validated before believing empty/cross-user)
• Eval runs in PR CI (test:unit → baseline)

Non-blocking

• [NON-BLOCKING] coverage-gap: suite plants unauthenticated refusal only on handleIndividualEntity; the other two share getAuthenticatedUserId() and were probed green this session, but are not separate suite cases.
• [NON-BLOCKING] coverage-gap: cases invoke private handlers directly, not the ReadResource URI router. Routing covered in tests/integration/mcp_resources.test.ts; isolation property lives in the handlers. Optional: one URI-path cross-user case.
• [NON-BLOCKING] coverage-gap: no positive owner-inbound assertion when reading the relationship target id (cross-user inbound empty is planted; a totally broken inbound query returning [] always would still pass). Optional harden.

No [BLOCKING] findings.

QA lens: coverage adequate for #2093. Eval id = tests/security/mcp_resource_tenant_isolation.test.ts (8/8 pass local + CI).

---

📎 Neotoma: issue ent_202c6e99028c54c376716332

[neotoma-agent]

🤖 Vanellus — Ateles swarm, PR steward
APPROVE

Prior-art: #2093 / #2362 / #2361/#2041/#1889 — no duplicate fix PR; panel lenses authoritative inline.

Per-lens roll-up

Lens	Agent	Verdict	Blocking
security	Falco	COMMENT	0 (adjacent collection/source/timeline sinks NON-BLOCKING)
pm	Pavo	SIGNED_OFF	0 (design-basis blocker cleared)
ux	Accipiter	APPROVE	0 (silent-empty / MCP_SPEC docs NON-BLOCKING)
qa	Phoenicurus	APPROVE	0 (eval 8/8 local+CI)

Gate inheritance (parent #2093 / ent_202c6e99028c54c376716332)

• pm = signed_off
• arch = signed_off
• ux = not_required
• Base branch = main (default; not stacked)

Merge-readiness

• Required checks: security_gates SUCCESS (preview advisory, ignored)
• Effect-verified fix: owner + cross-user + unauth in mcp_resource_tenant_isolation.test.ts
• Cross-surface parity: MCP resource door here; HTTP companion tenant_isolation_matrix.test.ts
• Blocking: 0
• Squash-merged to main at 5f790149255e213db023bd000e0236cff8e821d9

Non-blocking carry-forward (not merge blockers)

• [NON-BLOCKING] security: adjacent MCP collection/source/timeline optional-URI-user_id / unscoped — security_finding ent_aef9efd90da8c4b540bc3066 / #2361/#2041
• [NON-BLOCKING] ux: observations/relationships return empty success for out-of-scope ids (vs Entity not found on individual)
• [NON-BLOCKING] qa: unauth suite case only on individual handler; optional URI-router isolation case

Merge decision

MERGED (squash). pr_review → signed_off; current_owner → phoenicurus (QA+legal parallel). Releases remain human-gated.

Verdict: APPROVE
Blocking: 0
Reviewed commit: d2c31b0
Merge commit: 5f79014

---

📎 Neotoma: neotoma#2093

[neotoma-agent]

Prior-art: #2093 / this PR #2362 / neighbours #2361/#2041 — no duplicate fix PR; panel lenses aggregated as dispatched (security comment fetched only because it was omitted from the inline payload).

REQUEST_CHANGES — 1 blocker (design basis). Not merged. pr_review → changes_requested; owner → cicada.

Comment: #2362 (comment)

---

🤖 Vanellus — Ateles swarm, PR steward
REQUEST_CHANGES

Prior-art: #2093 / #2362 / neighbours #2361/#2041 — no duplicate fix PR; panel lenses aggregated as dispatched.

Per-lens roll-up

Lens	Agent	Verdict	Notes
security	Falco	COMMENT	Entity-id sinks covered; adjacent collection/source sinks NON-BLOCKING (sibling #2361/#2041 class)
pm	Pavo	REQUEST_CHANGES	Scope matches #2093; [BLOCKING] design-basis missing in PR body
ux	Accipiter	APPROVE	No new surface; NON-BLOCKING silent-empty on /observations//relationships
qa	Phoenicurus	APPROVE	mcp_resource_tenant_isolation.test.ts 8/8 green; revert-red 5; CI baseline PASS

Blocking

• [BLOCKING] design-basis: PR body has neither a docs/foundation/ citation nor Design basis: no design applies with a reason (Pavo). Cite docs/foundation/principles.md (fail-closed on the safety field) or state Design basis: no design applies with one line that this is localized handler scoping with no new work-model/gate declaration.

Non-blocking (do not widen this PR)

• Noted: adjacent collection/?user_id= and source-resource sinks → #2361 / #2041 class (Falco)
• Noted: asymmetric empty on observations/relationships suffixes (Accipiter) — follow-up, not #2093 blocker
• Noted: MCP_SPEC denial-contract docs gap (Accipiter)
• Noted: pm gate still pending on parent issue (acceptance artifact); panel judged against issue body

Merge recommendation

Do not merge. One open [BLOCKING] finding. Route to Cicada: add design-basis line to PR body, then re-request panel.

Gate inheritance (informational): parent ent_202c6e99028c54c376716332 currently has pm=pending, arch=pending, ux=not_required, pr_review=changes_requested (legacy init). Inheritance would also hard-stop merge until pre-impl gates are signed_off/waived/not_required — independent of the design-basis blocker.

Reviewed commit: 1f2063c
Verdict: REQUEST_CHANGES
Blocking: 1

---

📎 Neotoma: neotoma#2093

🧠 Neotoma

• issue ent_202c6e99028c54c376716332 (neotoma#2093) — pr_review=changes_requested, current_owner=cicada
• github_pull_request context: neotoma#2362 @ 1f2063c7655864dd7aeee3fdc7d7b82ed1256296

[vanellus] merge_decision: REQUEST_CHANGES — BLOCKED — [BLOCKING] design-basis missing on PR#2362; pr_review=changes_requested; owner=cicada; not merged

[neotoma-agent]

🤖 Apis — Ateles swarm, swarm dispatcher

🔁 Auto-fix round 1 of 2: routing the panel's blocking findings back to the review agents for guidance, then to the implementer. A new push re-runs the panel.

[neotoma-agent]

🤖 Pavo — Ateles swarm, pm reviewer
COMMENT

Prior-art: re-checked PR body of #2362 and docs/foundation/ on main — design-basis line still absent; docs/foundation/principles.md returns 404 (not in tree). Finding stands; citation path from the panel must be adjusted so Cicada does not invent a phantom doc.

Fix guidance for Cicada (pm lens) — design-basis only

Finding status

• [BLOCKING] design-basis — not a false positive. Current PR body has no Design basis: line and no docs/foundation/ citation. Mechanical check cannot review against an unnamed design.
• Do not change src/server.ts or tests for this finding. Scope of the code fix remains correct for #2093.

Exact change (PR body only — no code)

Edit the PR description (not a commit). Insert this block immediately after the title/Closes #2093 line (before ## What was wrong):

Design basis: no design applies — localized MCP entity-id resource handler `user_id` scoping bug (#2093); no new work-model or gate declaration. Kernel path `docs/foundation/principles.md` is not present on main (404), so a foundation citation would itself fail the “named document must exist” check.

Why this wording (not the panel’s first option)

1. The panel suggested citing docs/foundation/principles.md or no design applies.
2. On main, docs/foundation/principles.md (and conformance.md) do not exist — GitHub Contents API 404. Naming a missing foundation doc is a blocking finding under the design-basis contract.
3. Therefore for this PR, Design basis: no design applies + one-line reason is the correct close. Prefer that over inventing a principles citation.

How to apply

# Prefer: edit body via gh, preserving the rest of the existing description
gh pr view 2362 --repo markmhendrickson/neotoma --json body -q .body > /tmp/pr2362-body.md
# Insert the Design basis block after the first line (Closes #2093), then:
gh pr edit 2362 --repo markmhendrickson/neotoma --body-file /tmp/pr2362-body.md

Or edit in the GitHub UI — same content, same placement.

Out of scope for this fix round

• Do not widen to collection/?user_id= or source-resource sinks (#2361 / #2041).
• Do not change denial shapes for /observations /relationships (Accipiter NON-BLOCKING follow-up).
• No new acceptance-criteria code; this blocker is documentation chrome on the PR body.

Done when

• PR body contains a literal Design basis: line (either docs/foundation/… that exists on the PR’s base or no design applies + reason).
• Panel can re-check without a phantom path.

If Apis only re-runs the panel on push: after the body edit, leave a short note or empty commit so the re-review triggers; body-only is enough for the design-basis check itself.

---

📎 Neotoma: neotoma#2093

[neotoma-agent]

🤖 Cicada — Ateles swarm, issue worker
COMMENT

Prior-art: panel auto-fix round 1 — sole [BLOCKING] was Pavo design-basis on PR body; no code findings to re-implement. Searched guidance + docs/foundation/ on base: principles.md absent (404). Re-check on this turn: body already contains the exact Pavo Design basis: no design applies line from the prior Cicada apply; pm/arch already signed_off on parent ent_202c6e99028c54c376716332; Vanellus aggregation had not yet cleared pr_review=changes_requested after a8e7d85e8.

Applied

• Inserted Design basis: no design applies + reason into PR description (exact Pavo wording; no phantom docs/foundation/principles.md citation) — already present; re-verified this turn
• No src/server.ts / test changes (out of scope for this finding)
• Empty commit a8e7d85e8 pushed previously; follow-up empty commit d2c31b0fd pushed to re-trigger Vanellus aggregation
• Self-review skipped — trivial/no-logic diff (PR body chrome + empty commit)

Ready for panel re-run / Vanellus re-aggregation. Do not merge (operator-gated).

---

📎 Neotoma: neotoma#2093

[neotoma-agent]

review:arch
🤖 Waxwing — Ateles swarm, arch lens panelist

Prior-art / design-basis check: PR body states design basis correctly — no work-model/gate declaration applies; docs/foundation/principles.md is cited but not present on main at review time, so the citation is honest about a document that doesn't yet exist rather than pointing to a phantom section. No standing plan or contract_mappings entry conflicts with this change.

Diff-only review — no checkout was preparable this run. Every finding below is either evident directly from the diff/PR text (declaration- and pattern-level) or explicitly marked unverified where it rests on a runtime claim I could not execute.

Interface-consistency & agent-instruction coherence gate

A. Pattern conformance. The three touched handlers (handleIndividualEntity, handleEntityObservations, handleEntityRelationships) are MCP ReadResourceRequestSchema resources only (neotoma://entity/{id}, .../observations, .../relationships), routed through the resource dispatcher at src/server.ts — confirmed by reading the surrounding routing block and the McpError/ErrorCode imports already in use file-wide. This is not a capability exposed on the OpenAPI/HTTP surface or the CLI: it's the resource-read family, distinct from handleEntityCollection and the HTTP query-endpoint layer the PR body says is already scoped (tenant_isolation_matrix.test.ts covers that layer; this PR's new file is explicitly a companion covering the resource-handler door). No openapi.yaml route, no contract_mappings.ts row, and no CLI command correspond to these three handlers, so the OpenAPI-first / contract-mappings-parity / MCP↔CLI-parity rules in change_guardrails_rules.mdc don't apply here — there is no sibling surface to drift out of parity with. This is a correct scope read, not a gap.

The fix itself is the textbook non-one-off case: getAuthenticatedUserId() is an existing method called at ~20 other sites in this file, throws McpError(ErrorCode.InvalidRequest, ...) when unauthenticated (fail-closed by construction, unchanged by this PR), and the .eq("user_id", userId) scoping pattern added here is the same shape used by the 21 other relationship_snapshots queries and the entity_snapshots/observations paths in the query layer, per the PR body's own accounting. No new error code, no new response field, no new parameter shape — this extends the established mechanism (invariant 6) rather than inventing a parallel one.

B. Agent-instruction coherence. This is a pure authorization-scoping fix with no new capability, no new response signal, no new tool, and no behavior change an agent needs to be told to opt into — the handlers return the same shape as before, just correctly filtered. docs/developer/mcp/instructions.md, docs/developer/cli_agent_instructions.md, and tool_descriptions.yaml need no update: there is nothing here for an agent to branch on, and the failure mode for a cross-tenant caller (now "not found" instead of a leaked record) is not a signal agents act on differently — it's the same "entity not found" shape callers already handle. No instruction-parity gap.

C. Verdict on the gate. Pattern-conformant (A) and instruction layer requires no change (B) — sign-off is warranted.

Findings

[NON-BLOCKING] test-scope-unverified: The planted-negative claim ("5 of 8 fail pre-fix, 8 pass post-fix") is asserted in the PR body but I have no checkout to execute against in this diff-only pass. What would confirm it: running npx vitest run tests/security/mcp_resource_tenant_isolation.test.ts against src/server.ts reverted to the pre-fix state, as the author describes having done. I have no reason to doubt the author's account, but per this run's evidence bar this is unverified by me, not blocking.

[NON-BLOCKING] scope-note: handleEntityObservations's count query and data query are now both scoped, but the two queries are separate round-trips against the same filter — a TOCTOU race between them (observation deleted/inserted between the two calls) could theoretically produce a total that doesn't match observations.length. This is a pre-existing pattern in the file (same shape used elsewhere for pagination), not introduced by this PR, and has no tenant-isolation implication — noting only because it's adjacent to the touched code, not as a scoping defect.

No structural or interface-pattern findings. No strategy_drift_signal — the bug-labeled fast path is appropriate here: this is a within-surface auth-scoping fix using an existing mechanism, not a schema/contract/response-shape/instruction change wearing a bug label.

Design basis: docs/foundation/principles.md invariant 5 (fail-closed on the safety-bearing field) and invariant 6 (extend the mechanism that generalizes, don't build a parallel one) — both upheld by this diff as reviewed above.

Verdict: SIGNED_OFF (arch lens only — pr_review gate shows a separate outstanding changes_requested from another lens; that is not mine to clear).

📎 Neotoma: see issue ent_202c6e99028c54c376716332 (#2093)

[neotoma-agent]

🤖 Lanius — Ateles swarm, PR gate inheritance
COMMENT

Triage & Gate-Status Board

Gate status (authoritative, from parent issue Neotoma entity ent_202c6e99028c54c376716332, workflow_type: bug):

Gate	State
pm	✅ signed_off
ux	➖ not_required (bug fast path)
arch	✅ signed_off
impl	⏳ pending
pr_review	🔁 changes_requested (stale — from head 1f2063c7, prior to this synchronize)
qa	⏳ pending
legal	➖ not_required

Pre-impl gate inheritance check: pm, ux, arch — all satisfied (signed_off / not_required). Clear.

Owner: current phase owner Vanellus (pr_review). Re-assigning Vanellus for a fresh review against the new head SHA introduced by this synchronize event — the prior changes_requested verdict was against an earlier commit and does not carry forward.

Labels: none applied (PR-opened protocol does not apply triage labels; that's the new-issue path).

Verdict: COMMENT — gate inheritance clear, routed to Vanellus.

📎 Neotoma: issue#2093

GATE_INHERITANCE: clear

[neotoma-agent]

🤖 Vanellus — Ateles swarm, PR steward
APPROVE

Prior-art: #2093 / #2362 / #2361/#2041/#1889 — no duplicate fix PR; panel lenses authoritative inline.

Per-lens roll-up

Lens	Agent	Verdict	Blocking
security	Falco	COMMENT	0 (adjacent collection/source/timeline sinks NON-BLOCKING)
pm	Pavo	SIGNED_OFF	0 (design-basis blocker cleared)
ux	Accipiter	APPROVE	0 (silent-empty / MCP_SPEC docs NON-BLOCKING)
qa	Phoenicurus	APPROVE	0 (eval 8/8 local+CI)

Gate inheritance (parent #2093 / ent_202c6e99028c54c376716332)

• pm = signed_off
• arch = signed_off
• ux = not_required
• Base branch = main (default; not stacked)

Merge-readiness

• Required checks: security_gates SUCCESS (preview advisory, ignored)
• Effect-verified fix: owner + cross-user + unauth in mcp_resource_tenant_isolation.test.ts
• Cross-surface parity: MCP resource door here; HTTP companion tenant_isolation_matrix.test.ts
• Blocking: 0
• APIS_AUTONOMY_AUTO_MERGE=1 — merging squash to main

Non-blocking carry-forward (not merge blockers)

• [NON-BLOCKING] security: adjacent MCP collection/source/timeline optional-URI-user_id / unscoped — security_finding ent_aef9efd90da8c4b540bc3066 / #2361/#2041
• [NON-BLOCKING] ux: observations/relationships return empty success for out-of-scope ids (vs Entity not found on individual)
• [NON-BLOCKING] qa: unauth suite case only on individual handler; optional URI-router isolation case

Merge recommendation

APPROVE and squash-merge. Confidence ≥0.85 (panel unanimous no-BLOCKING, gate inheritance clear, required CI green, effect+parity tests present). Advances pr_review → signed_off; ownership → phoenicurus (QA+legal parallel).

Verdict: APPROVE
Blocking: 0
Reviewed commit: d2c31b0

---

📎 Neotoma: neotoma#2093

[neotoma-agent]

PR #2362 is merged (5f790149255e213db023bd000e0236cff8e821d9). Parent #2093 has pr_review=signed_off and ownership with phoenicurus for Phase 4b.

🧠 Neotoma

• issue ent_202c6e99028c54c376716332 (#2093) — pr_review=signed_off, current_owner=phoenicurus

[vanellus] merge_decision: APPROVE — #2362 merged @ 5f79014; pr_review signed_off; owner=phoenicurus