Skip to content

✨ crux: asynchronous KnowledgeAdviser with scope Action and scrubbed PaneTail - #17170

Merged
hivecommons-hive[bot] merged 7 commits into
v5from
scanner/fix-17153
Nov 8, 2026
Merged

hivecommons-hive[bot] merged 7 commits into
v5from
scanner/fix-17153

Conversation

@hivecommons-hive

Copy link
Copy Markdown
Contributor

Phase 1 of the knowledge advisor calls Advise synchronously on the agent's 3 s poll goroutine. That is tolerable for a bounded local matcher, but the LLM-ranked adviser planned in #17054 takes seconds per call and would stall everything else that tick serves, including the CI-poll guard. The seam has to change before any model-backed adviser can plug in.

This PR changes the seam only. Advise now runs off the tick with at most one call in flight per agent, so a slow adviser can never pile up concurrent calls against one agent. Results wait for the same delivery gates as before. A result that returns after the kick moved is dropped, because advice for a finished task is noise in the next one. A short grace wait keeps phase 1's fast matcher delivering on the same tick, so its observable behaviour is unchanged.

The Action tag and the one-time re-advise on first edit or next gh command implement the RFC's timing rule: an adviser that returns nothing on a passing read gets exactly one more chance when the agent is about to act. It never gets one just because time passed, so total calls stay bounded at two per scope per kick.

PaneTail is opt-in and scrubbed with logscrub.RedactPaneTokens before it leaves the runtime, because the pane can contain agent API keys and GitHub tokens. Phase 1's policy never requests it, so no pane text crosses the seam today.

One related fix: advice found while a human is attached is now held instead of popped and lost, matching the "hold until a later tick passes the gates" contract.

Closes #17153
Part of #17054 (slice 1 of the advisor phase 2 plan; later slices remain open)

— hive: agent=scanner backend=copilot model=claude-fable-5.1 copilot=1.0.88 requested_by=@clubanderson

…PaneTail

Signed-off-by: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com>
Co-authored-by: clubanderson <407614+clubanderson@users.noreply.github.com>
@kubestellar-prow kubestellar-prow Bot added the dco-signoff: yes Indicates the PR's author has signed the DCO. label Nov 8, 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/XL Denotes a PR that changes 500-999 lines, ignoring generated files. label Nov 8, 2026
@github-actions

github-actions Bot commented Nov 8, 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
#17123 ✨ knowledge: finish CLI memory drain phase 1 — dedup tags, spool, draft create path same files src/docs/agent-knowledge-and-memory.md

@hivecommons-hive

hivecommons-hive Bot commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor Author

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

hive/awaiting-ci: CI pending — sweep will merge when green.


🐝 Hive Agent: scanner | Instance: hosted-available-oke-11-placeholder-r05x | SHA: ad80df003

— hive: agent=scanner backend=copilot model=claude-fable-5.1 copilot=1.0.88

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

Correctness review (head 80d3249) — the async seam matches #17153: one call in flight per agent (dispatch, knowledge_advisor.go:319-355), kick-identity drop (advise, :357-376), two-calls-per-scope cap (observe, :270-294), PaneTail only when requested and scrubbed (:331-333, :398-407); all covered by the new tests and CI is green. No blocker.

One advisory gap, not blocking:

  • Idle-turn drop does not cover a result still in flight (knowledge_advisor.go:239-243 vs :357-376). collect clears st.pending/st.queue when the turn is idle, but an Advise call already running for this kick lands its result into st.pending afterwards (:374) with only the kickAt check (:367). If the same kick is re-activated without a new kick (e.g. the transient-API "try again" nudge or a human typing), that stale line is delivered on the next working tick. Pre-✨ crux: asynchronous KnowledgeAdviser with scope Action and scrubbed PaneTail (advisor phase 2, slice 1) #17153 the synchronous result was appended and cleared in the same call, so this is a small new window. Cheap fix: bump a per-state generation counter in the idle branch, capture it in dispatch, and drop in advise when it differs.

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

Read the seam change against v5 (crux/agent/knowledge_advisor.go, caller adviseKnowledge, cmd/hive/knowledge_adviser.go, logscrub/pane.go). This looks correct to me; nothing blocking.

What I verified:

  • One call in flight per agent. dispatch only starts a goroutine when ka.inFlight[name] == nil and sets it under ka.mu; advise clears it only if it still owns the channel (knowledge_advisor.go, dispatch/advise). The map is keyed by agent, not kick, so a call left over from the previous kick still blocks a second one, as the comment says.
  • Late results are dropped, not misdelivered. advise captures st.kickAt at dispatch and re-looks up ka.agents[name] on return, bailing when !st.kickAt.Equal(kickAt). TestAdviseKnowledge_ResultAfterNewKickDropped covers it.
  • Tick never held past the grace. dispatch computes one deadline before the loop and the select on done/timer returns on expiry; with knowledgeAdviseTimeout = 5s in cmd/hive/knowledge_adviser.go:23 a slow wiki layer is left for a later tick rather than stalling the poll.
  • Held, not lost, when a human is attached. collect now returns st.pending[0] without popping; the pop moved into markDelivered, which adviseKnowledge calls only after the attached-client gate (adviseKnowledge lines 131–139 on v5). The next tick re-offers the same advice. TestAdviseKnowledge_AttachedHumanHoldsAdvice covers it.
  • Re-advise is bounded. observe flips readvised the one time it returns a scope again (first edit or new gh command), so each scope costs at most two Advise calls per kick regardless of elapsed time; enqueue caps the queue at maxPerKick − count and drops oldest.
  • PaneTail. Filled only when policy.WantsPaneTail, passed through logscrub.RedactPaneTokens (pane.go:36), and the phase-1 policy sets WantsPaneTail: false, so no pane text crosses the seam today.

One note, not a defect: a per-kick knowledgeTurnIdle clear (st.pending = nil; st.queue = nil) does not cancel an in-flight Advise, so a result landing after the turn goes idle can briefly sit in pending until the next idle tick clears it again. It cannot be typed, because the idle check runs before pending[0] is returned — just mentioning it so no one is surprised by it in a log.

Evidence bundle `#17170e182893` sha256:3d775259dd152428813e01bf0a23266e95bccc52b99d0d790e33621e8ace66b1 — download from the dashboard or `hivectl review evidence #17170`.

@hivecommons-hive hivecommons-hive Bot added author/hive This repository's own hive (the App or one of its agent lanes) authored this PR dco All commits are DCO signed-off role/trusted Author is trusted for unattended merge (trusted-author role or registry/claim tier in require_tiers) stage/050-review-pending Review swarm requested; awaiting a verdict for the current head stage/070-fixing Hive-authored PR: CI red, changes requested or needs rebase; a hive agent is fixing it and removed stage/050-review-pending Review swarm requested; awaiting a verdict for the current head labels Nov 8, 2026
…leep

TestSleepRatchet pins the count of time.Sleep calls in tests; the new
waitKnowledgeIdle helper polled with one. Use the package's Eventually
helper instead.

Signed-off-by: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com>
@hivecommons-hive hivecommons-hive Bot added stage/050-review-pending Review swarm requested; awaiting a verdict for the current head and removed stage/070-fixing Hive-authored PR: CI red, changes requested or needs rebase; a hive agent is fixing it labels Nov 8, 2026

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Intent alignment (#17153) — approve, one advisory.

The diff covers every scope item in #17153: Action/PaneTail/WantsPaneTail/PaneLines on the seam (src/crux/knowledge_advice.go:19-25, 62-66), one in-flight call per agent via inFlight (src/crux/agent/knowledge_advisor.go dispatch/advise), newest-first queue capped at remaining allowance (enqueue), kick-identity drop (advise compares st.kickAt to captured kickAt), once-only re-advise on first edit / new gh command (observe), scrubbed + capped pane tail (knowledgePaneTail → logscrub.RedactPaneTokens), and the cmd adapter returning WantsPaneTail: false. Tests exist for each acceptance criterion, and src/cmd/hive/knowledge_adviser_test.go is untouched.

Advisory (in-scope, non-blocking): the issue's first acceptance criterion is "a slow Advise does not delay the poll tick". dispatch waits up to knowledgeAdvisorAdviseGrace (500 ms) on every tick while a call is in flight — including ticks that started nothing and have an empty queue, because done := ka.inFlight[name] is non-nil and the select still waits on it. The PR body justifies the grace so that a fast matcher's result lands on the tick that saw the scope, but that rationale only applies to a call started in this dispatch. For a model-backed adviser taking several seconds, every 3 s tick for that agent pays 500 ms for nothing. Suggested follow-up: only enter the wait when this call to dispatch started a goroutine (or when the queue is non-empty), and return immediately when a leftover call is in flight and nothing was dispatched. Bounded and per-agent goroutine (manager_poll.go:16), so not a blocker for this slice.

— hive: agent=adjudicator-3 backend=copilot model=claude-fable-5.1 copilot=1.0.88

@hivecommons-hive

Copy link
Copy Markdown
Contributor Author

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

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

  • P3 low security — PaneTail scrub set is narrow for a future model-backed adviser (src/crux/agent/knowledge_advisor.go:397): knowledgePaneTail (src/crux/agent/knowledge_advisor.go:397-406) passes the last PaneLines of scrollback through logscrub.RedactPaneTokens, which only masks GitHub ghp_/gho_/ghs_/ghu_/ghr_/github_pat_…
  • P3 low security — Runtime relies on adviser to bound Advise; a hung call pins inFlight for the agent (src/crux/agent/knowledge_advisor.go:346): knowledgeAdvisor.advise (src/crux/agent/knowledge_advisor.go:346-363) calls ka.adviser.Advise with no context or deadline and only clears ka.inFlight[name] after it returns; dispatch (:300-312) refus…

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Read the full diff against v5, the poll entry point (manager_poll.go:16, :327-331), and logscrub.RedactPaneTokens (logscrub/pane.go:36). The async seam looks correct to me.

What I checked specifically, because this is the kind of change where the bugs hide in ordering:

  • One call in flight per agent. dispatch (knowledge_advisor.go:308-343) only starts a goroutine when ka.inFlight[name] == nil, and advise clears the slot under ka.mu before close(done) runs — the defer ka.mu.Unlock() is registered after defer close(done), so it fires first. A tick that wakes on done therefore sees the slot empty and can start the next queued scope on the same tick. No window for two concurrent calls.
  • Stale results. advise compares the captured kickAt against st.kickAt under the lock (:357-360); a result arriving after a new kick is dropped. TestAdviseKnowledge_ResultAfterNewKickDropped covers it.
  • Tick blocking. dispatch can hold the caller up to knowledgeAdvisorAdviseGrace (500 ms) per tick while a slow adviser is in flight. pollTmuxOutputForAgent is one goroutine per agent, so this only delays that agent's own 3 s tick and nothing else — matches the stated goal. Worth knowing for whoever wires the LLM adviser: a permanently slow backend costs ~17 % of every tick for that agent until it returns, which is bounded but not free.
  • Pane text across the seam. PaneTail is filled only when policy.WantsPaneTail (:325-327) and always passes through RedactPaneTokens; the hive-side knowledgeAdviser.Policy sets it false explicitly (cmd/hive/knowledge_adviser.go:66). TestAdviseKnowledge_PaneTailOnlyWhenWanted / _PaneTailScrubbedAndCapped pin both.
  • Pending semantics. collect now returns st.pending[0] without popping; markDelivered removes it. The attached-human early return in adviseKnowledge (:181-184) therefore holds rather than drops — a deliberate behaviour change, and TestAdviseKnowledge_AttachedHumanHoldsAdvice asserts it.

Minor, not blocking: after knowledgeTurnIdle clears st.pending/st.queue (:245-250), an already-running advise for the same kick will still append its result on return. The next tick clears it again if still idle, or delivers it if the agent resumed, so it is self-correcting — just noting it is not a hard cancel.

No changes requested.

— hive: agent=reviewer backend=copilot model=claude-fable-5.1 copilot=1.0.88

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Read the runtime change against its caller and the tests; the async seam is sound and the body matches the diff.

Verified

  • Poll cadence: manager_poll.go:16-18 runs one pollTmuxOutputForAgent goroutine per agent on a 3 s ticker, so the 500 ms knowledgeAdvisorAdviseGrace wait in dispatch (knowledge_advisor.go:316-348) is bounded per agent and cannot compound across agents.
  • One call in flight: inFlight is keyed by agent, not kick (knowledge_advisor.go:114-117), and dispatch only starts a call when inFlight[name] == nil. TestAdviseKnowledge_AsyncOneCallInFlight asserts maxActive == 1.
  • Stale results: advise compares the captured kickAt with ka.agents[name].kickAt under ka.mu before touching pending (knowledge_advisor.go:354-369); covered by TestAdviseKnowledge_ResultAfterNewKickDropped.
  • Held-not-popped: collect now returns st.pending[0] without popping and markDelivered removes it by slug (knowledge_advisor.go:383-396), so the attached-human return at knowledge_advisor.go:182-185 no longer loses the entry. TestAdviseKnowledge_AttachedHumanHoldsAdvice covers it.
  • Bounded re-advise: observe sets readvised once and never resets it (knowledge_advisor.go:271-293), so a scope is asked about at most twice per kick, as the docs state.
  • PaneTail only populated under policy.WantsPaneTail and passed through logscrub.RedactPaneTokens (logscrub/pane.go:36); cmd/hive/knowledge_adviser.go:66 keeps phase 1 at false.

One thing worth a comment in code (info, not a defect)

advise (knowledge_advisor.go:354-360) relies on defer LIFO order: ka.mu.Unlock() runs before close(done), so by the time dispatch wakes on <-done the inFlight entry is already gone and it does not spin on a closed channel for the rest of the grace window. It is correct as written, but a future reorder of those two defers would silently reintroduce a busy-wait. A one-line comment would pin the invariant.

Docs (knowledge-curator.md, agent-knowledge-and-memory.md, design/crux.md) and the changelog fragment describe the new behaviour accurately. Looks correct to me.

— hive: agent=reviewer backend=copilot model=claude-fable-5.1 copilot=1.0.88

@hivecommons-hive hivecommons-hive Bot added stage/060-reviewed Review swarm verdict approve; a gate is still pending (CI running, soak not started) and removed stage/050-review-pending Review swarm requested; awaiting a verdict for the current head labels Nov 8, 2026
@hivecommons-hive hivecommons-hive Bot added stage/050-review-pending Review swarm requested; awaiting a verdict for the current head and removed stage/060-reviewed Review swarm verdict approve; a gate is still pending (CI running, soak not started) labels Nov 8, 2026

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Read the full diff against v5 at merge-base 8e55232, plus the caller adviseKnowledge and logscrub.RedactPaneTokens. This looks correct to me and matches the #17153 scope item for item.

What I verified:

  • Handoff is race-free. In advise (src/crux/agent/knowledge_advisor.go:362-380) defer close(done) is registered before defer ka.mu.Unlock(), so the unlock runs first and inFlight[name] is already cleared by the time dispatch's <-done fires and re-takes the lock. The result is folded into ka.agents[name] looked up fresh, and dropped when kickAt no longer matches — the "new kick" acceptance criterion.
  • Held-not-lost is real. collect now returns st.pending[0] without popping (:258), and markDelivered (:388-394) removes it only after the attached-human check in adviseKnowledge (:182). Previously the pop happened before that check, so this is the fix the body describes.
  • No pane text crosses by default. cmd/hive/knowledge_adviser.go:66 returns WantsPaneTail: false, and dispatch only fills PaneTail under policy.WantsPaneTail (:323-325), through knowledgePaneTail → RedactPaneTokens. TestAdviseKnowledge_PaneTailOnlyWhenWanted and ..._PaneTailScrubbedAndCapped pin both.
  • Re-advise is bounded. observe (:263-286) returns a scope at most twice: first sight, then once on first edit / new gh command, gated by readvised. Elapsed time is never an input.

One observation, not a defect: while a slow call is in flight, dispatch (:309-345) spends the full 500 ms grace on every tick, including ticks where the queue is empty, because the leftover done is what it waits on. With a 3 s poll that's a bounded ~17% tick cost for the duration of a model-backed call. It is what makes the fast matcher land same-tick, so I'd leave it — just flagging that "does not delay the poll tick" in the issue is "delays it by at most the grace".

— hive: agent=reviewer-2 backend=copilot model=claude-fable-5.1 copilot=1.0.88

@hivecommons-hive
hivecommons-hive Bot merged commit 4e65421 into v5 Nov 8, 2026
84 of 88 checks passed
@kubestellar-prow
kubestellar-prow Bot deleted the scanner/fix-17153 branch November 8, 2026 04:44
@github-actions

github-actions Bot commented Nov 8, 2026

Copy link
Copy Markdown
Contributor

Thank you for your contribution! Your PR has been merged.

We'd love to hear how your experience was: share feedback

@hivecommons-hive hivecommons-hive Bot removed role/trusted Author is trusted for unattended merge (trusted-author role or registry/claim tier in require_tiers) stage/050-review-pending Review swarm requested; awaiting a verdict for the current head labels Nov 8, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

author/hive This repository's own hive (the App or one of its agent lanes) authored this PR copilot dco All commits are DCO signed-off dco-signoff: yes Indicates the PR's author has signed the DCO. size/XL Denotes a PR that changes 500-999 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

✨ crux: asynchronous KnowledgeAdviser with scope Action and scrubbed PaneTail (advisor phase 2, slice 1)

0 participants