Skip to content

✨ Session taint: observe-only recorder for what a session has read - #19099

Merged
hivecommons-hive[bot] merged 11 commits into
v5from
feat/session-taint-phase0
Nov 18, 2026
Merged

hivecommons-hive[bot] merged 11 commits into
v5from
feat/session-taint-phase0

Conversation

@clubanderson

@clubanderson clubanderson commented Nov 18, 2026 •

Copy link
Copy Markdown
Member

What this is

The smallest OBSERVE-ONLY slice of session taint from src/docs/design/session-taint.md. Off by default (session_taint.enabled), it keeps a bounded in-memory record of coarse labels per agent session and logs and audits the would-be verdict of the fixed rule table for later relay writes. It never blocks, holds, restricts or changes any request or action, and stores labels, counts and ids only (no credential or content).

Refs #18987 (the RFC stays open until the enforcement phases are decided).

What changed

  • src/crux/sessiontaint (new, stdlib only): label and sink types, the pure Evaluate rule table (the four v1 rules), a bounded LRU session store, and the Observer. The observer entry points return nothing, there is no deny verdict in the type, panics inside them are absorbed, and an unattributed or malformed agent is not recorded. Origins are shape-checked per label (category slug, owner/repo, host), so free text or a credential-shaped string is stored as invalid.
  • pkg/config/session_taint.go plus one field in config.go: session_taint.enabled (default false), max_sessions, max_labels_per_session, max_decisions.
  • Source S3 only: the existing canary leak handler sets a secret label (origin hive-canary) via recordCanaryTaint in cmd/hive. No proxy file is touched.
  • Sinks: the issue, comment, PR and review relay watchers call observeSessionTaint once per relay write that completed, after every existing gate, retry and dedupe step (a reused issue, comment or PR is skipped), so the data never describes an action the hive refused or retried. The enforcement phases move the check before the write. A clean session costs a map lookup; a labelled one triggers one cached destination visibility lookup (a failed lookup counts as public and is not cached).
  • Docs: phase status in the design doc (status column, "Phase status" section) and security-model.md (control entry plus a "does not do yet" line). Changelog fragment added.
  • Tests (synthetic data only): observe-only guarantee (entry points return nothing, verdicts are only hold, evaluator purity), nothing recorded when off (nil observer, no lookup, no log, no audit), clean session costs no lookup, bounded store (sessions, labels, decision ring, per-session audit), restart starts clean and invents nothing, no content or credential-shaped input stored, lookup panic absorbed, concurrency, config defaults match the observer's.

Not in this PR

S0, S1 and S2 sources; the proxy and push-broker sinks (waiting on the proxy PRs in flight, none of which this PR touches); the sandbox PR step; the read-only API and hivectl view; operator release and clear; persistence; any hold or deny behaviour.

Decision record for the 12 open questions

Each row is the recommended answer with one line of reasoning grounded in the code. Overrule any row at review; rows marked "affects code" would change this PR.

# Question Decision Reasoning (code) Affects this PR
1 Scope for long-lived agents Epoch advances on process restart or operator clear, plus a maximum age added with enforcement; never per kick A CLI agent's context survives kicks, so a per-kick reset would claim a forgetting that did not happen; sandboxed kicks get their own boundary through S0 later Epoch is process lifetime only; max age is not built
2 Partial coverage acceptable? Yes, if every agent view states "not covered" per source The translator only sees rerouted routes (translateAnthropicMessage, translatorAgentName), so S1 is partial by construction; which backends reroute depends on per-hive config and stays unverified until phase 2b measures it No
3 Git over the opaque host Assume S2 is blind to clone and fetch; make S0 (kick target) the primary private-repo source for sandboxed kicks NeedsMITM returns true only for the forge API host and the tracker host, so git smart-HTTP to the main forge host is tunnelled opaquely No (S0 is a later phase)
4 False-positive budget Keep 14 days, 50 events, 10 percent, 2 false holds per agent per week; first enforced rules only on hives where the desk is watched, otherwise stay observe The desk is documented default-off, so a hold on an unwatched hive would stall work with nobody to release it No
5 Audience model Equality plus operator-supplied groups; no real audience resolution The only visibility signal the code uses today is the boolean Private field (sentinelRepoPrivate); teams and forks are not modelled anywhere Equality (case-insensitive) is built; groups are not
6 Laundering across agents Out of v1; session key is (agent, epoch) The canary registry already scans other agents' tokens, but a hit would only label the token owner's session; a cross-agent key needs its own design (repo, task or issue) Canary hit labels the token owner's session only
7 State In memory only for phases 0 to 4; on a restart, observe records nothing and enforce treats the session as unknown-tainted; a pruned file copy is phase 5 The canary registry file never evicts (no delete, Remove or Prune in pkg/ioscan/canary.go), so copying its pattern would grow without bound; one process owns the proxy, relays and executor, so memory needs no consistency layer Memory only; restart starts clean and invents no unknown label
8 Runtime guardrails and the authorization RFCs Separate small rule table for v1; the evaluator takes only labels and a sink descriptor so labels can later become attributes in whatever language #12815 or #17091 produce Neither RFC has landed a language yet, and the table is four rules Evaluator is a pure function of (labels, sink)
9 Latency budget Observe scans off the request path; no synchronous scan until phase 4; target p99 under 5 ms added, to be replaced by the phase 2b measurement The translator converts every message in a request each turn (translateAnthropicToOpenAI), so naive scanning is quadratic; dedupe by block id and a byte cap are needed before any synchronous use No (no scanning in this PR; sinks do a map lookup)
10 Canary registry growth Yes, add eviction, as its own change before phase 5 persistence CanaryRegistry has no removal path and grows per kick; taint adds a second per-kick store and must not copy that shape No (taint store is bounded; registry untouched)
11 Egress Do not ship destination-only control on the opaque path in v1 tunnelDirect carries builds and package fetches to many hosts; a destination list would be wrong more often than right, and the existing destination-class guard already covers the dangerous classes No
12 Commit messages and branch names Yes, include them in the push-broker gate in phase 3b as a separate small fix outgoingDiff runs git diff or git show --format= only, so message and branch text never reach FindSecret No (broker untouched)

Review notes

  • Phase 0 here is the implementation slice; the design doc's own phase 0 (the record) already merged. The status column maps what this PR built onto phases 1, 2a and 3a.
  • ObserveSink is the only place a destination lookup can happen, and only for a session that already holds a label, so a hive with the feature on but no labels makes no extra API calls.
  • Tests were not run locally by instruction; CI is the gate.

Adds the smallest observe-only slice of the session taint design: a
config-gated, bounded, in-memory recorder (crux/sessiontaint) that keeps
coarse per-session labels and logs the would-be verdict of a fixed rule
table for later relay writes. Off by default; it never blocks, holds,
restricts or changes any request or action, and stores labels, counts and
ids only.

Refs #18987

Signed-off-by: Andrew Anderson <andy@clubanderson.com>
@kubestellar-prow kubestellar-prow Bot added the dco-signoff: yes Indicates the PR's author has signed the DCO. label Nov 18, 2026
@kubestellar-prow

Copy link
Copy Markdown
Contributor

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign hanthor for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@kubestellar-prow kubestellar-prow Bot added the size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. label Nov 18, 2026
@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Open PR overlap check

Base branch: v5

Conflicts are checked with every PR merged onto the current tip of v5, so a PR that only needs a rebase is not reported as conflicting with its siblings.

PR Title Relation Files
#19143 🐛 Reviewer-stated rules: ignore quotes and questions, match more future phrasings, and give the preferences a Settings card same files src/pkg/config/config.go
#19110 🐛 Filter em-dashes on every outbound path, agent proxy writes included same files src/docs/design/session-taint.md
#19156 ✨ inference translator: opt-in timeouts and bounded 429/5xx retry (default off) same files src/pkg/dashboard/settings_parity_allowlist.txt

@hivecommons-hive

hivecommons-hive Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Hive status — updated in place; edits do not notify. Full history is in the Activity Monitor.

@clubanderson this PR is held at stage/071-needs-author and the hive will not merge it yet.

Failing checks:

  • build-and-test

Next: the hive does not push to your branch. Push a new head (or reply here); CI and the review swarm re-run automatically and the PR returns to the normal path.

Review follow-ups: 1 open of 1 (below review.backlog.min_severity: P2)

Non-blocking findings below the backlog filing line, listed here instead of as issues. Tick them off as they are fixed; set review.backlog.min_severity: P3 to file every finding.

  • P3 info security — LRU session eviction would drop taint labels once enforcement lands (src/crux/sessiontaint/store.go:78): touch() evicts the least-recently-used session at maxSessions, so a tainted session's labels can be lost when many other agents are active. Harmless in observe-only mode; before enforcement phases, e…

Review findings from adjudicator-5 (folded here because this head already carries its hive review):

Docs-currency: the changelog, design-doc status table/"Phase status", and security-model entries match the observe-only behavior and say plainly that it is not a control. One advisory gap: session_taint is yaml-only (allowlist lines added) but src/hive.yaml.example (which documents sentinel, line 108) is not updated, so operators have no discoverable example. Suggested addition to hive.yaml.example:

+# session_taint:            # observe-only recorder (#18987); never blocks anything
+#   enabled: false
+#   max_sessions: 256
+#   max_labels_per_session: 32
+#   max_decisions: 128

Review findings from adjudicator (folded here because this head already carries its hive review):

Correctness review (head d83be9f). The evaluator, bounded store and nil-safe observer look right. One in-scope gap, with a fix below.

Taint is observed before gates that can still refuse or retry the request. The PR body says the call runs "after every existing gate and just before the hive acts". At this head it does not:

  • pr_request_watcher.go:441 runs before invalidHeadReason, validatePRRequestBody and validatePRRequestTargets, which can reject or retry.
  • review_request_watcher.go:436 runs before the sentinel-approval block and the comment-only downgrade.
  • issue_request_watcher.go:604-610 runs before the dedupe-checklist refusal, the prior-art refusal and issueRequestStartTargetBlock.

As a result, would-act audit lines, WouldAct counters and the decision ring describe actions the hive then refused. A request retried through failPRRequest or failIssueRequest is counted again and looked up again on each attempt. The 5s Repositories.Get also runs on requests that are about to be refused. That skews the data this phase exists to gather for the false-positive budget.

Requested change: move each call to just before the first GitHub write, after the last refusal or retry gate. The PR watcher is shown below, and the review and issue watchers need the same move.

-	// Session taint (#18987), observe only; changes nothing here.
-	c.observeSessionTaint(ctx, req.Agent, sessiontaint.SinkRelayPR, req.Repo)
-

and add it after the notifyAgentStart loop that follows validatePRRequestTargets, plus any later PR gates, so only requests that will be acted on are recorded.

Not verified: I did not run the new tests. I read only the PR watcher and review watcher call sites, not their later control flow in full.

Findings not on a changed line

  • src/pkg/github/pr_request_watcher.go:441: Runs before invalidHeadReason, validatePRRequestBody and validatePRRequestTargets, so refused or retried requests are recorded and counted as would-act. Move this to just before the first GitHub write, after the last refusal/retry gate. Same placement problem at review_request_watcher.go:436 (before the sentinel/comment-only handling) and issue_request_watcher.go:604-610 (before the dedupe, prior-art and start-target gates).

Review findings from adjudicator-2 (folded here because this head already carries its hive review):

Style review at 3902c0d. Conventions are followed: stdlib-only package, nil-safe observer, config defaults guarded by a drift test, parity allowlist entries, changelog fragment. One in-scope comment fix.

Comment contradicts the call sites (src/pkg/github/session_taint.go:14). The header says the relay watchers call observeSessionTaint "immediately before the hive acts on it". The call sites in issue_request_watcher.go, pr_request_watcher.go and review_request_watcher.go, and the PR body, all say it runs after the write completed ("Recorded once per relay write that completed"). A later enforcement author reading the header would put the check on the wrong side of the write. Suggested fix:

// The relay watchers call observeSessionTaint once a relay write has completed,
// after every existing gate. The call is

Findings not on a changed line

  • src/pkg/github/session_taint.go:14: Header says the call happens "immediately before the hive acts on it", but every call site runs after the write completed (and the PR body says so). Reword to "once a relay write has completed, after every existing gate".
Evidence bundle `#190991bccb46` sha256:c31d5caf0a762892c9cfea67650675eff861d023097d6ad9c27b4c532ad383f5 — download from the dashboard or `hivectl review evidence #19099`.

merged by Hive trusted-author auto-merge: author clubanderson holds role owner and GitHub permission admin on repo; CI green at 1bccb46.

… settings parity allowlist

Refs #18987

Signed-off-by: Andrew Anderson <andy@clubanderson.com>
Signed-off-by: Andrew Anderson <andy@clubanderson.com>
@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Mutation testing

gremlins found 4 surviving mutant(s) in changed files: the code ran under tests, but changing it did not fail any test.

File Line Mutation
src/crux/sessiontaint/observer.go 117 CONDITIONALS_BOUNDARY
src/crux/sessiontaint/observer.go 197 INCREMENT_DECREMENT
src/crux/sessiontaint/store.go 97 INCREMENT_DECREMENT
src/crux/sessiontaint/store.go 130 CONDITIONALS_BOUNDARY

31 mutant(s) in changed files are not reached by any test (NOT COVERED). A maintainer may apply the mutation/acknowledged label to accept this.

File Line Mutation
src/crux/sessiontaint/observer.go 300 INCREMENT_DECREMENT
src/crux/sessiontaint/observer.go 382 CONDITIONALS_BOUNDARY
src/crux/sessiontaint/observer.go 382 CONDITIONALS_BOUNDARY
src/crux/sessiontaint/observer.go 382 CONDITIONALS_BOUNDARY
src/crux/sessiontaint/observer.go 382 CONDITIONALS_BOUNDARY
src/crux/sessiontaint/observer.go 382 CONDITIONALS_BOUNDARY
src/crux/sessiontaint/observer.go 382 CONDITIONALS_BOUNDARY
src/crux/sessiontaint/observer.go 382 CONDITIONALS_NEGATION
src/crux/sessiontaint/observer.go 382 CONDITIONALS_NEGATION
src/crux/sessiontaint/observer.go 382 CONDITIONALS_NEGATION
src/crux/sessiontaint/observer.go 382 CONDITIONALS_NEGATION
src/crux/sessiontaint/observer.go 382 CONDITIONALS_NEGATION
src/crux/sessiontaint/observer.go 382 CONDITIONALS_NEGATION
src/crux/sessiontaint/observer.go 420 CONDITIONALS_BOUNDARY
src/crux/sessiontaint/observer.go 420 CONDITIONALS_BOUNDARY
src/crux/sessiontaint/observer.go 420 CONDITIONALS_BOUNDARY
src/crux/sessiontaint/observer.go 420 CONDITIONALS_BOUNDARY
src/crux/sessiontaint/observer.go 420 CONDITIONALS_BOUNDARY
src/crux/sessiontaint/observer.go 420 CONDITIONALS_BOUNDARY
src/crux/sessiontaint/observer.go 420 CONDITIONALS_NEGATION
src/crux/sessiontaint/observer.go 420 CONDITIONALS_NEGATION
src/crux/sessiontaint/observer.go 420 CONDITIONALS_NEGATION
src/crux/sessiontaint/observer.go 420 CONDITIONALS_NEGATION
src/crux/sessiontaint/observer.go 420 CONDITIONALS_NEGATION
src/crux/sessiontaint/observer.go 420 CONDITIONALS_NEGATION
src/pkg/github/session_taint.go 26 ARITHMETIC_BASE
src/pkg/github/session_taint.go 97 CONDITIONALS_NEGATION
src/pkg/github/session_taint.go 97 CONDITIONALS_NEGATION
src/pkg/github/session_taint.go 103 CONDITIONALS_NEGATION
src/pkg/github/session_taint.go 103 CONDITIONALS_NEGATION
src/pkg/github/session_taint.go 103 CONDITIONALS_NEGATION

Verdict: lived (#17349).

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Style review at d83be9f: conventions and readability look good (nil-safe observer, named bounds, settings-parity allowlist and golden updated, changelog fragment present). One advisory, not blocking:

  • src/cmd/hive/session_taint_wire_test.go:46: TestSessionTaintConfigDefaults only tests config.SessionTaintConfig, so it fits better in pkg/config/session_taint_test.go. Keep the cross-package drift guard (...DefaultsMatchObserver) in cmd/hive, since only there are both packages imported.

-- hive: agent=adjudicator-4 backend=claude model=claude-sonnet-5-5 claude=2.1.327

Comment thread src/cmd/hive/session_taint_wire_test.go Outdated
}
}

func TestSessionTaintConfigDefaults(t *testing.T) {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Style (low): this test only covers config.SessionTaintConfig; move it to src/pkg/config/session_taint_test.go beside the type. The cross-package drift guard below can stay here.

…tests and a config example

Refs #18987

Signed-off-by: Andrew Anderson <andy@clubanderson.com>
Signed-off-by: Andrew Anderson <andy@clubanderson.com>

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Intent alignment (head 3902c0d): the diff matches the stated contract, an off-by-default, observe-only recorder. The observer is nil unless session_taint.enabled. Source S3 is wired through handleCanaryLeak (cmd/hive/github_client_config.go), and the sink hooks fire once per completed write in the issue, comment, PR and review watchers, after the existing gates. I found no scope creep: S0/S1/S2, the proxy and enforcement are explicitly deferred.

Advisory, non-blocking:

  • The header comment in src/pkg/github/session_taint.go says the call runs "immediately before the hive acts on it". The call sites run after the write completed (for example issue_request_watcher.go !resp.AlreadyExisted), and the PR body says the same. Reword the comment to "after the write completed".
  • The PR says it never blocks or changes a request. A labelled session does one synchronous Repositories.Get of up to 5s (taintAudienceLookupTimeout) inside the relay handler, and the response is written afterwards. That could delay the relay response, though not alter it. Consider noting this in the docs or running the lookup asynchronously.

-- hive: agent=adjudicator backend=claude model=claude-sonnet-5-5 claude=2.1.327

@hivecommons-hive
hivecommons-hive Bot merged commit 307e896 into v5 Nov 18, 2026
86 of 87 checks passed
@kubestellar-prow
kubestellar-prow Bot deleted the feat/session-taint-phase0 branch November 18, 2026 22:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

dco-signoff: yes Indicates the PR's author has signed the DCO. size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant