Skip to content

fix(execution-context): narrow the vouched population to create-capable callers - #14737

Merged
iamwhatever merged 1 commit into
mainfrom
fix/narrow-vouched-population-12611
Sep 28, 2026
Merged

iamwhatever merged 1 commit into
mainfrom
fix/narrow-vouched-population-12611

Conversation

@chenmingwei23

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Stop the execution-context vouching helper from retaining entries for callers that can never exercise them, so the vouched map holds only the population it exists to serve.

Follow-up refactor deferred by PR #12467's fence (issue #12611). _vouch retained an entry for every member-bearing vouch=True bind, gated only on member_id (execution_context.py bind_session_execution), with no restriction to callers whose session keys can ever reach create_session. Teardown-less / per-request binders therefore filled the capped _VOUCHED_EXECUTIONS map and were exactly what the cap, LRU refresh, overflow tally and re-arm machinery existed to absorb.

Why it matters

The vouched map is one of the two sources create_session's own-store admission requires to agree, and it is capacity-bounded (_MAX_VOUCHED_EXECUTIONS = 4096). Every entry that can never be read as a caller's vouch is dead weight that spends a slot, drives eviction of live member sessions under cap pressure, and enlarges the security-relevant "who is vouched" surface for no benefit. Narrowing the population is the smaller, safer default the parent PR deliberately left for a reviewed change of its own.

Not a goal

  • No change to the cap value, the LRU/eviction policy, the overflow tally, the re-arm throttle, or the withdraw-only-shrinks invariant — they remain correct for the reduced population.
  • No change to the durable record path: narrowed sites still publish their execution record, so the affected turns run unchanged.
  • Not touching _LIVE_EXECUTIONS (main's map) — explicitly out of scope per the parent PR.

What changed (motivation → approach → change)

Root cause → approach → change:

  • Root cause. Vouching was gated only on member_id, so it absorbed callers whose session key can never be the caller_slot that create_session's own-store admission reads (session_control.py caller_vouched). That admission is the only reader of the vouched map, so a vouched entry is useful iff its session key can reach create_session — i.e. it is a real dashboard slot that caller_slot_key resolves.

  • Approach (issues-conductor ruling, option a). Restrict vouching to callers whose session key can reach create_session. The predicate is applied at the call sites rather than inside _vouch, because _vouch is a pure primitive below the dashboard/ layer and cannot see DashboardState; the three vouch=True sites were each classified against the predicate.

  • Change. Classification of the three sites:

    • session_control._persist_birth — binds the freshly created child slot, a real create-capable slot. Keeps vouch.
    • member_memory_auth.bind_private_session_store — establishes own-store dispatch authority for a member's dashboard slot from a trusted store argument (never from the session's own record); its callers pass create-capable dashboard: keys and rely on the vouch for own-store dispatch (test_private_creator_keeps_its_memory). Keeps vouch.
    • hooks.bind_captured — runs on a hook: synthetic key in an ephemeral session that _run_hook_agent destroys after the turn; it is never registered as a dashboard slot, so caller_slot_key never resolves it and it can never be the caller whose vouch create_session reads. Dropped to vouch=False — one call-site flip.

    Deviation from the issue's two alternatives, recorded per the analyst's note that the implementer is closer to the code: only the hook binder unambiguously binds a non-create-capable key. bind_private_session_store was found load-bearing for real create-capable member callers, so option (a)'s predicate keeps its vouch rather than removing it.

Backwards compatibility

Compatible: the only behavioral change is that a hook session is no longer vouched. Hook sessions are ephemeral (hook: prefix, torn down after the turn) and are never a create_session caller, so no reachable code read their vouch — test_teardown_withdraws_the_vouched_execution_identity (which manually vouches a hook key to test teardown) still passes, and every member-memory-runtime / session-control / session-capabilities suite that relies on real slot vouching is green. The durable record is still published, so hook turns run unchanged.

Tests

  • test_every_binder_declares_whether_it_vouches — updated: hooks.bind_captured is pinned to vouch=False; the two establishing sites stay True. This AST enumeration reddens if any binder's vouch disposition drifts.
  • test_a_hook_session_publishes_but_is_never_vouched (new) — observable acceptance for execution_context: narrow the vouched population instead of absorbing entries that never needed vouching #12611: a hook: key binding publishes its record (read_session_execution non-None) but is not vouched (read_vouched_session_execution is None), while a create-capable dashboard: slot binding still vouches. Not asserted in prose.
  • Regression coverage confirmed green: full test_execution_context.py, test_webhooks_api.py, test_member_memory_runtime.py, test_session_capabilities.py, test_session_control.py private-creator/worker-start paths, test_chat_hooks.py, test_hooks.py.

Manual verification

N/A — unit coverage sufficient: the narrowing is a call-site vouch-disposition change with an observable map-level assertion and an AST enumeration test that pins every binder's disposition.

Related Issues

Fixes #12611

Pattern harvest

Rule candidate: review-prompt
Pattern: an entry admitted to a capped/shared map on a broad gate (here member_id) when its only reader keys on a narrower identity (a create-capable caller slot) — admit on the reader's predicate, not the writer's convenience.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable) — N/A, no user-facing docs affected
  • No secrets, credentials, or internal references in the diff

@chenmingwei23
chenmingwei23 requested a review from a team as a code owner September 28, 2026 16:11
@github-actions github-actions Bot added the readiness: action required A blocking check or review needs attention label Sep 28, 2026
@github-actions

github-actions Bot commented Sep 28, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of 8fd3da38e6a52f49525d90a4cb221ad75f3102c3 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 8fd3da3

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 8fd3da38e6a52f49525d90a4cb221ad75f3102c3: <one-sentence reason>

@github-actions

github-actions Bot commented Sep 28, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

Design-level review of 8fd3da38e6a52f49525d90a4cb221ad75f3102c3 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Teardown comment at hooks.py:1510 now lies — "the bind leaves a vouched entry… always there to withdraw" — update it in this PR.

[DESIGN-REVIEWED] 8fd3da3

@github-actions

github-actions Bot commented Sep 28, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — ✅ PASS

Premise-level review of 8fd3da38e6a52f49525d90a4cb221ad75f3102c3 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: PASS

Verify the now-stale comment at hooks.py:1509-1514 — it still says "the bind leaves a vouched entry rather than a live carrier", which this flip makes false.

The narrowing is a pure subtraction with checkable provenance: issue #12611, deferred by parent PR #12467. I counted the vouched map's production readers — exactly one, read_vouched_session_execution at session_control.py:1739, keyed on a slot resolved through caller_slot_key, which walks state._slots; grep for hook: in session_control.py finds nothing, and the hooks handler runs on state.sessions, never registering a dashboard slot — so a hook key can never be the caller that read serves. The pin reversal (bind_captured: "True" → "False") is openly declared with the linked issue as evidence the prior classification was wrong, so lens 8 is satisfied. Note the description's harm ("filled the capped map") is overstated — hooks.py:1520 already withdrew each entry in its finally — but the entry was still dead weight while in flight, and the change deletes rather than adds.

What this change ships

Inventory (3 items) — 3 justified

Intent: FIX (deferred narrowing) — stop vouching hook sessions whose keys can never reach create_session.

  1. A hook turn still publishes its execution record but no longer occupies a vouched-map slot — justified
  2. The binder-disposition pin for hooks.bind_captured reversed True→False, declared with linked issue execution_context: narrow the vouched population instead of absorbing entries that never needed vouching #12611 — justified
  3. New test pins the observable effect: hook keys publish, never vouch; dashboard slots still vouch — justified

[FIRST-PRINCIPLES-REVIEWED] 8fd3da3

…le callers

Issue #12611 (follow-up to PR #12467's fence): `_vouch` retained an entry
for every member-bearing `vouch=True` bind, including callers whose session
key can never reach `create_session`, so those entries filled the capped
`_VOUCHED_EXECUTIONS` map and were what the cap/LRU/overflow-tally/re-arm
machinery existed to absorb.

The vouched map's only reader is `create_session`'s own-store admission,
which reads the entry for the CALLER slot (`session_control.py`
`caller_vouched`). So a vouched entry is only ever useful if its session key
can be that caller -- a real dashboard slot `caller_slot_key` resolves.

Per the issues-conductor ruling (option a: restrict `_vouch` to callers whose
session keys can reach `create_session`), the three `vouch=True` sites were
classified against that predicate:

  - session_control `_persist_birth` -- binds the freshly created child slot,
    a real create-capable slot. KEEPS vouch.
  - member_memory_auth `bind_private_session_store` -- establishes own-store
    dispatch authority for a member's dashboard slot from a trusted store
    argument; its callers pass create-capable `dashboard:` slot keys and rely
    on the vouch for own-store dispatch (test_private_creator_keeps_its_memory).
    KEEPS vouch.
  - hooks `bind_captured` -- runs on a `hook:` synthetic key in an EPHEMERAL
    session `_run_hook_agent` destroys after the turn; it is never registered
    as a dashboard slot, so `caller_slot_key` never resolves it and it can
    never be the caller whose vouch `create_session` reads. DROPS to
    vouch=False -- the record is still published, so the hook turn is
    unchanged, but no slot is spent in the capped map.

Tests co-designed with the call site:
  - test_every_binder_declares_whether_it_vouches: bind_captured pinned False.
  - test_a_hook_session_publishes_but_is_never_vouched (new): observable
    acceptance -- a hook key publishes its record but is not vouched, while a
    create-capable dashboard slot still vouches.

Refusal invariants unchanged: a forged record still cannot obtain another
member's store, and the cap/LRU/tally/re-arm and the withdraw-only-shrinks
invariant remain correct for the reduced population.
@chenmingwei23
chenmingwei23 force-pushed the fix/narrow-vouched-population-12611 branch from 1be6c86 to 8fd3da3 Compare September 28, 2026 16:25
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 28, 2026
@github-actions

Copy link
Copy Markdown
Contributor

Opus 5 Review — ✅ no blocking findings

Reviewed 8fd3da38e6a52f49525d90a4cb221ad75f3102c3 — this comment is updated in place on each push.

Review details

Nothing blocks; the hook path's removed vouch leaves its teardown comment and the owning spec stating the opposite.

FINDING — src/kiro_crew/dashboard/handlers/hooks.py:1513 — with vouch=False the persistent branch of bind_session_execution writes neither _LIVE_EXECUTIONS (restricted-only) nor _VOUCHED_EXECUTIONS, so the untouched teardown's "the entry is always there to withdraw … so the bind leaves a vouched entry rather than a live carrier" is now false and its clear_session_execution(session_key) pops nothing on every hook request, while execution_context.py:36 / :483 and the owning spec docs/system-specs/modules/session-control.md:612 still name "a webhook that sends no sessionKey" as the per-request producer that justifies _MAX_VOUCHED_EXECUTIONS and refresh_vouched_session_execution (the other named example, the task-runner refine run at dashboard/handlers/taskrunner.py:1149, binds with no vouch= at all) → Fix: in this commit, correct those sentences to say the hook bind leaves no in-process entry and that the remaining vouching producers (_persist_birth, record_agent_selection) are per-session.

[OPUS-REVIEWED] 8fd3da3

Verdict parsed from the review's SHA-scoped output markers for commit 8fd3da38e6a52f49525d90a4cb221ad75f3102c3.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 8fd3da38e6a52f49525d90a4cb221ad75f3102c3: <one-sentence reason>

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Sep 28, 2026
@iamwhatever
iamwhatever merged commit a756ad3 into main Sep 28, 2026
98 checks passed
@iamwhatever
iamwhatever deleted the fix/narrow-vouched-population-12611 branch September 28, 2026 23:15
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 28, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

execution_context: narrow the vouched population instead of absorbing entries that never needed vouching

2 participants