diff --git a/.github/release-lines.yml b/.github/release-lines.yml index d696f07749..67009f5b78 100644 --- a/.github/release-lines.yml +++ b/.github/release-lines.yml @@ -32,8 +32,14 @@ # channel rows, default branch, docs) is the checklist in # src/docs/release-line-guard.md. -# The release lines CI is expected to cover. -release_lines: [v4, v5] +# The release lines CI is expected to cover. v6 was cut as a release line on +# 2026-11-07: it mints `v6.x.y` tags, GitHub Releases and SBOMs through +# tagged-release.yml like v5 does. Channel ownership did NOT move with it — +# v5 still publishes `candidate` + `:latest` and owns `stable` (promoted from +# the default branch by promote-stable.yml); v6 publishes `edge` + `v6-latest` +# (its own docker.yml rows). See src/docs/release-line-guard.md, "Cutting a +# new release line", and src/docs/releases.md. +release_lines: [v4, v5, v6] # Workflows whose branch filters are pinned to the release lines. # @@ -52,67 +58,62 @@ pinned: # sunset, and a PR targeting v2 runs the v2 merge-ref's workflows anyway, # where this file does not exist. Same excluded-not-backfilled reasoning as # docs-link-check.yml below. - # v6 is carried as an EXTRA on the workflows below rather than added to - # `release_lines`: it is the #7563 development line and has not been cut as - # a release line — until it is, the release workflows refuse to tag or - # promote from it (#9154). What it DOES need is the same PR - # gating as v4, because feature PRs target it directly (spine, mention - # triggers); without these extras a v6-base PR runs no Go build, test, or - # security lane at all. It is ALSO published — `v6-latest` and, once its own - # docker.yml rows say so, the `edge` channel (#7721 Phase 1) — which is the - # `env_lists` extra below, not a `release_lines` entry: publishing a line's - # image is a narrower commitment than covering it with every pinned lane. - changelog-fragment-guard.yml: [v5, v6] + # v6 used to be carried as an EXTRA on the PR-gating workflows below while + # it was the #7563 development line; since its cut (2026-11-07) it is a + # `release_lines` entry, so the extras are gone and every pinned lane that + # does not write down a `-v6` exclusion covers it. + changelog-fragment-guard.yml: [] # Static analysis and vulnerability scanning for the Go module. Pinned to the # release lines and nothing else: a feature branch gets the same gate through # `pull_request`, and running it on every pushed branch would burn runner # minutes re-scanning code that has not reached a release line. # Added with the docs link checker (#5278), after the v2 line was sunset - # (#5030-era). It gates src/docs/ links on the release lines plus the v6 - # development line (#9476): v6 takes doc changes through feature PRs like - # the other lines, and without this extra a v6-base PR's broken doc links - # and stale code citations landed ungated. v2 was never back-filled: the - # workflow never ran there and the line is retired. - docs-link-check.yml: [v6] - # Post-merge DCO monitor for protected branch history. It intentionally - # watches v4 and v5 only: v4 is the source line whose Tide squash commits - # triggered #6312, and v5 is the sync target that inherits those commits. - dco-post-merge.yml: [v5] - # Push-scoped delta DCO gate (#6756). Same v4/v5 coverage and reasoning as - # dco-post-merge.yml above: v4 is the line whose pushes it audits, v5 the - # sync target inheriting them; v2 is sunset and takes no pushes. - dco-push-delta.yml: [v5] - # FOSSA license scanning runs on the active CNCF onboarding line only; - # v4 is feature-frozen and not being imported as the initial Hive Commons - # CNCF FOSSA project. - fossa.yml: [-v4] - # GitHub Actions Workflow triage compiles only on the active v5 line; older - # release lines do not carry the gh-aw automation surface. - gh-aw-compile.yml: [-v4] + # (#5030-era). It gates src/docs/ links on every release line (#9476): v6 + # takes doc changes through feature PRs like the other lines, and without + # it a v6-base PR's broken doc links and stale code citations landed + # ungated. v2 was never back-filled: the workflow never ran there and the + # line is retired. + docs-link-check.yml: [] + # Post-merge DCO monitor for protected branch history. It watches every + # release line: v4 is the source line whose Tide squash commits triggered + # #6312, and v5 and v6 are the sync targets that inherit those commits. + dco-post-merge.yml: [] + # Push-scoped delta DCO gate (#6756). Same coverage and reasoning as + # dco-post-merge.yml above: v4 is the line whose pushes it audits, v5 and + # v6 the sync targets inheriting them; v2 is sunset and takes no pushes. + dco-push-delta.yml: [] + # FOSSA license scanning runs on the CNCF onboarding line only: the Hive + # Commons FOSSA project is imported from ONE branch, v5. v4 is + # feature-frozen; v6 inherits v5's dependency set through the top-ups and + # is not a second FOSSA project. + fossa.yml: [-v4, -v6] + # GitHub Actions Workflow triage compiles only on the default v5 line, where + # the gh-aw agentic workflows are registered; v4 does not carry the gh-aw + # automation surface and v6 only mirrors v5's compiled lock files. + gh-aw-compile.yml: [-v4, -v6] # Self-test for the hive-action-smoke dispatch workflow (#12964). Its push # trigger names v5 only: the smoke workflow is registered on v5 and does not # exist on the feature-frozen v4 line, so there is nothing there to test. - hive-action-smoke-tests.yml: [-v4] - go-security-analysis.yml: [v5, v6] + # v6 carries its own action unit gate (hive-action-tests.yml, v6 only). + hive-action-smoke-tests.yml: [-v4, -v6] + go-security-analysis.yml: [] # Unit gate for the reusable hive action's app-handle helper (#9707). The - # action and its smoke wiring live only on the v6 development line, so the - # push filter watches v6 alone; v4 is feature-frozen and v5 never carried - # the action, hence the explicit exclusions. - hive-action-tests.yml: [v6, -v4, -v5] + # action and its smoke wiring live only on the v6 line, so the push filter + # watches v6 alone; v4 is feature-frozen and v5 never carried the action, + # hence the explicit exclusions. + hive-action-tests.yml: [-v4, -v5] # Headless phone-viewport sweep of the Hive Chat panel (#11852). The chat - # panel, its chip lists and the sweep script live only on the v6 development - # line, so its pull_request filter watches v6 alone; v4 is feature-frozen and - # v5 never carried the panel, hence the explicit exclusions. - hive-chat-phone-sweep.yml: [v6, -v4, -v5] + # panel, its chip lists and the sweep script live only on the v6 line, so + # its pull_request filter watches v6 alone; v4 is feature-frozen and v5 + # never carried the panel, hence the explicit exclusions. + hive-chat-phone-sweep.yml: [-v4, -v5] # promtool check + unit tests for the monitoring component's PrometheusRule - # (#15438). The component exists only on the v6 development line; v4 is - # feature-frozen and v5 never carried it, hence the explicit exclusions. - prometheusrule-check.yml: [v6, -v4, -v5] + # (#15438). The component exists only on the v6 line; v4 is feature-frozen + # and v5 never carried it, hence the explicit exclusions. + prometheusrule-check.yml: [-v4, -v5] # Renders every kustomize overlay, plus the monitoring component (#15503). - # Same v6-only reasoning as prometheusrule-check.yml: the component exists - # only on the v6 development line; v4 is feature-frozen and v5 never - # carried it, hence the explicit exclusions. - kustomize-render.yml: [v6, -v4, -v5] + # Same v6-only reasoning as prometheusrule-check.yml. + kustomize-render.yml: [-v4, -v5] podman-arm64-lane.yml: [] podman-contract.yml: [] podman-rootful-lane.yml: [] @@ -145,46 +146,48 @@ pinned: # They react to PRs into, and pushes to, the lines that take feature PRs: # v5 (stable + candidate) and v6 (edge). v4 is feature-frozen and takes no # new PRs, so there is nothing there to order or refresh. - pr-overlap.yml: [v6, -v4] - pr-auto-update.yml: [v6, -v4] - pr-auto-update-test.yml: [v6, -v4] + pr-overlap.yml: [-v4] + pr-auto-update.yml: [-v4] + pr-auto-update-test.yml: [-v4] # Native queue admission is available on the active feature lines only. # This is CI coverage, not an opt-in or a queue rule for either branch. - native-queue-policy.yml: [v6, -v4] - testutil-guard.yml: [v5, v6] - v2-ci.yml: [v5, v6] - v2-tests.yml: [v5, v6] + native-queue-policy.yml: [-v4] + testutil-guard.yml: [] + v2-ci.yml: [] + v2-tests.yml: [] # Automated v4 -> v5 forward-merge cadence (#7297). Its only branch filter is # the `workflow_run` trigger, which names the line whose RELEASES it reacts # to — v4, the source of every top-up. v2 is sunset and cuts no releases to # carry forward, and v5 is the merge TARGET rather than a trigger, so it is - # not a branch this workflow watches (on v5, where v5 is itself a release - # line, it must be excluded explicitly for the same reason). - v5-topup.yml: [-v5] + # not a branch this workflow watches (v5 and v6 are release lines too, so + # they must be excluded explicitly for the same reason — v6 reaches v4's + # releases through v5). + v5-topup.yml: [-v5, -v6] # Post-freeze intake gate for v4 (#7693, runbook §2). It watches PRs into # the ONE line the accepted freeze policy (#6346) applies to; v2 is sunset # and takes no PRs, and v5/v6 are exactly where non-critical work is sent. - v4-freeze-gate.yml: [-v5] + v4-freeze-gate.yml: [-v5, -v6] # Automated v5 -> v6 forward-merge cadence (#7563, Track 7). Its only branch # filter is the `push` trigger naming the line whose MOVEMENT it reacts to — - # v5, the source of every v6 top-up. v2 and v4 are excluded for the same - # reason as v5-topup.yml's exclusions: they are not the branch this workflow - # watches (v4 reaches v6 through v5), and v6 is the merge TARGET, not a - # trigger. - v6-topup.yml: [v5, -v4] + # v5, the source of every v6 top-up. v4 is excluded for the same reason as + # v5-topup.yml's exclusions: it is not the branch this workflow watches (v4 + # reaches v6 through v5), and v6 is the merge TARGET, not a trigger. + v6-topup.yml: [-v4, -v6] # Publishes src/crux to hivecommons/crux (#14138). It watches the ONE line # the published module is cut from — v5, where the nested module lives and # where `crux/vX.Y.Z` tags are made. v4 is feature-frozen and has no - # src/crux; publishing from two lines would race on hivecommons/crux main. - crux-sync.yml: [-v4] + # src/crux; v6 carries a copy through the top-ups but publishing from two + # lines would race on hivecommons/crux main. + crux-sync.yml: [-v4, -v6] # Nightly + path-filtered Forgejo smoke (#14116). Its push/pull_request - # filters name v5 only: the forge.Merger it exercises lives on v5, and v4 is - # feature-frozen. - forgejo-smoke.yml: [-v4] + # filters name v5 only: it exercises the forge.Merger against a live Forgejo + # and one line's coverage is enough for a shared package — v6 inherits the + # package through the top-ups, and v4 is feature-frozen. + forgejo-smoke.yml: [-v4, -v6] # Publishes the headless Twitch streamer image (#15594) from v5 only: the - # dashboard's `?kiosk=1` mode it depends on lives on v5 and v4 is - # feature-frozen. The image is operator tooling, not a hive release channel. - stream-image.yml: [-v4] + # image is operator tooling, not a hive release channel, so it follows the + # default branch rather than every release line; v4 is feature-frozen. + stream-image.yml: [-v4, -v6] # Workflows that deliberately do NOT pin to the release lines. Each must keep a # wildcard branch filter; if one is ever narrowed to a fixed list, the guard @@ -212,11 +215,10 @@ env_lists: # docker.yml's gate job: only long-lived branches push to GHCR. `mk` and `dd` # are standing experimental branches — not release lines, but branches a hive # can be assigned to, so they legitimately publish a `-latest` tag. - # `v6` is the #7563 development line, published so the `edge` channel can be - # re-based on it (#7721 Phase 1): `v6-latest` must exist before v6's own - # docker.yml publish rows can point `edge` at it. Every release branch that - # carries this list names v6 here, so the guard agrees across lines. - docker.yml LONG_LIVED: [mk, dd, v6] + # `v6` used to be an extra here while it was the #7563 development line + # (published so the `edge` channel could be re-based on it, #7721 Phase 1); + # since its cut it is a release line and covered without an extra. + docker.yml LONG_LIVED: [mk, dd] # MAINTAINER DECISION (#4405, answered by #8061 on 2026-09-21): `v2` is retired. # It was removed from `release_lines`, from every workflow that named it, and diff --git a/.github/scripts/integration-governance.cjs b/.github/scripts/integration-governance.cjs index 3f61d7362a..1ceebbc26b 100644 --- a/.github/scripts/integration-governance.cjs +++ b/.github/scripts/integration-governance.cjs @@ -9,7 +9,7 @@ const MAX_COMMITS = 1000; const MAX_AUTHOR_BATCH = 50; // This literal is inside the enrolled .github closure. A caller-supplied // preparedBy.sourceSHA must never choose a new executable verifier tree. -const TRUSTED_SCRIPTS_TREE = '267924f87d77a3fa335accce1b0c74d1a5cfdab8'; +const TRUSTED_SCRIPTS_TREE = '23eed03bebbb82deb0128f396b551939326729f2'; const SOURCE = 'https://github.com/kubernetes-sigs/kubebuilder-release-tools/tree/012269a88fa4c034a0acf1ba84c26b195c0dbab4'; const sha = value => crypto.createHash('sha256').update(value).digest('hex'); const git = (args, cwd = process.cwd()) => diff --git a/.github/scripts/native-queue-policy.cjs b/.github/scripts/native-queue-policy.cjs index 5baeb710e0..a54bcab393 100644 --- a/.github/scripts/native-queue-policy.cjs +++ b/.github/scripts/native-queue-policy.cjs @@ -23,6 +23,17 @@ const BLOCKED_LABEL = /^(hold|needs-human|release-in-progress|do-not-merge(?:\/. const MAX_QUEUE_PAGES = 10; const POLICY_CHECK_NAME = 'native-queue-policy'; const POLICY_CHECK_SOURCE = ['native-queue-policy.yml', ['pull_request_target']]; +// Decision B on #17030: a v5→v6 forward-merge opened by v6-topup.yml carries +// commits that already passed v5's DCO gate, and probot DCO cannot be repaired +// PR-side. Only that exact shape may substitute prow's `dco` status. +const FORWARD_MERGE = { + head: 'sync/v5-to-v6', base: 'v6', source: 'v5', + author: { login: 'github-actions[bot]', id: 41898282, type: 'Bot' }, +}; +const PROW = { login: 'kubestellar-prow[bot]', id: 208851060, context: 'dco' }; +// REST pull-request commit listing stops at 250; a longer list is unverifiable. +const MAX_PR_COMMITS = 250; +const PROBOT_DCO_PATH = 'DCO path: probot DCO (App 1861)'; const closedNoop = (pr) => `PR #${pr.number} is closed; nothing to evaluate`; @@ -148,15 +159,83 @@ async function assertActionsProvenance(github, repo, number, head, run, source, } } -async function assertEvidence(github, repo, number, head, checks) { +async function reachableFrom(github, repo, branch, commit) { + const { data } = await github.rest.repos.compareCommitsWithBasehead({ + ...repo, basehead: `${branch}...${commit}`, + }); + return ['behind', 'identical'].includes(data.status); +} + +// Returns null when the PR is not the top-up shape at all, otherwise whether +// the narrow prow path applies and why. Any doubt keeps probot DCO required. +async function forwardMergeDCOPath(github, repo, pr, head) { + const author = FORWARD_MERGE.author; + if (pr?.head?.ref !== FORWARD_MERGE.head || pr.base?.ref !== FORWARD_MERGE.base || + pr.head.repo?.full_name !== `${repo.owner}/${repo.repo}` || + pr.user?.login !== author.login || pr.user.id !== author.id || pr.user.type !== author.type) { + return null; + } + const commits = await github.paginate(github.rest.pulls.listCommits, { + ...repo, pull_number: pr.number, per_page: 100, + }); + const fallback = why => ({ prow: false, path: `${PROBOT_DCO_PATH}; ${FORWARD_MERGE.head} fallback: ${why}` }); + if (commits.length === 0 || commits.length >= MAX_PR_COMMITS) { + return fallback(`commit list unverifiable (${commits.length} commits)`); + } + for (const commit of commits) { + if (!SHA.test(commit.sha)) return fallback('malformed commit list'); + // The tip is v6-topup.yml's own `--no-ff` merge of origin/v5 onto v6, so it + // is never on v5 itself: its parents must be v6 and v5 history exactly. + if (commit.sha === head) { + const [ours, theirs] = (commit.parents || []).map(p => p.sha); + if (commit.parents?.length !== 2 || !SHA.test(ours) || !SHA.test(theirs) || + !await reachableFrom(github, repo, FORWARD_MERGE.base, ours) || + !await reachableFrom(github, repo, FORWARD_MERGE.source, theirs)) { + return fallback(`head ${head} is not a merge of ${FORWARD_MERGE.source} into ${FORWARD_MERGE.base}`); + } + } else if (!await reachableFrom(github, repo, FORWARD_MERGE.source, commit.sha)) { + return fallback(`${commit.sha} is not reachable from ${FORWARD_MERGE.source}`); + } + } + if (!commits.some(c => c.sha === head)) return fallback(`head ${head} is not in the commit list`); + return { + prow: true, + path: `DCO path: prow ${PROW.context} for ${FORWARD_MERGE.source}-reachable ${FORWARD_MERGE.head} forward-merge (#17030)`, + }; +} + +async function assertProwDCO(github, repo, head) { + const statuses = await github.paginate(github.rest.repos.listCommitStatusesForRef, { + ...repo, ref: head, per_page: 100, + }); + // Any workflow token can post a `dco` status; only prow's own is evidence. + const status = statuses + .filter(s => s.context === PROW.context && s.creator?.login === PROW.login && s.creator.id === PROW.id) + .sort((a, b) => b.id - a.id)[0]; + if (!status) throw new PendingEvidence(`Missing prow ${PROW.context} on ${head}`); + if (status.state === 'pending') throw new PendingEvidence(`prow ${PROW.context} is pending`); + if (status.state !== 'success') throw new Error(`prow ${PROW.context}: ${status.state}`); +} + +async function assertEvidence(github, repo, number, head, checks, pr) { + const dco = Object.hasOwn(checks, 'DCO') ? await forwardMergeDCOPath(github, repo, pr, head) : null; + const required = { ...checks }; + if (dco?.prow) delete required.DCO; const runs = await github.paginate(github.rest.checks.listForRef, { ...repo, ref: head, per_page: 100, filter: 'latest', }); const workflows = new Map(); - for (const { run, source } of evidenceForHead(runs, head, checks)) { - if (!source) continue; // Probot DCO is deliberately not impersonated. - await assertActionsProvenance(github, repo, number, head, run, source, workflows); + try { + for (const { run, source } of evidenceForHead(runs, head, required)) { + if (!source) continue; // Probot DCO is deliberately not impersonated. + await assertActionsProvenance(github, repo, number, head, run, source, workflows); + } + if (dco?.prow) await assertProwDCO(github, repo, head); + } catch (error) { + if (dco && !(error instanceof ProviderUnavailable)) error.message += ` [${dco.path}]`; + throw error; } + return dco?.path || PROBOT_DCO_PATH; } async function assertReviews(github, repo, number, head) { @@ -237,10 +316,12 @@ function isCosmeticLabelFlip({ eventName, payload }) { // A cosmetic flip skips the evidence wait but must not mint a fresh passing // required check: replay the latest completed `success` run of this check on // the head (rejecting one not from this workflow) and still read live PR -// eligibility. Returns null when there is nothing to replay — no completed -// run, or the latest one did not succeed (a failed, cancelled or timed-out -// wait) — so the caller falls through to the full evidence wait instead of -// pinning that earlier verdict onto every later stage-label flip. +// eligibility and the POLICY_CHECKS evidence. Returns null when there is +// nothing to replay — no completed run, or the latest one did not succeed (a +// failed, cancelled or timed-out wait), or a policy provider is missing, +// still running or reporting UNKNOWN — so the caller falls through to the +// full evidence wait instead of pinning that earlier verdict onto every later +// stage-label flip. async function replayLastVerdict({ github, context, currentCheckRunId }) { const repo = context.repo; const event = context.payload.pull_request; @@ -259,7 +340,21 @@ async function replayLastVerdict({ github, context, currentCheckRunId }) { // a run of this workflow file on this event may be replayed. await assertActionsProvenance(github, repo, pr.number, pr.head.sha, prior, POLICY_CHECK_SOURCE, new Map()); if (prior.conclusion !== 'success') return null; - return `PR #${pr.number}: replayed ${POLICY_CHECK_NAME} run ${prior.id} (success) on ${pr.head.sha}`; + // The prior success is only valid while the providers it validated are + // still green: one re-run red on this head must not be papered over. A + // provider that is missing or still running is not a verdict either way; + // fall through so the caller runs the full polling wait instead of failing. + // A DCO enumeration UNKNOWN also falls through: the full wait re-raises it + // once and renders the runbook job summary, so operators see the same + // surface whichever event fired. + let path; + try { + path = await assertEvidence(github, repo, pr.number, pr.head.sha, POLICY_CHECKS, pr); + } catch (error) { + if (error instanceof PendingEvidence || error instanceof ProviderUnavailable) return null; + throw error; + } + return `PR #${pr.number}: replayed ${POLICY_CHECK_NAME} run ${prior.id} (success) on ${pr.head.sha}; ${path}`; } async function evaluateOnce({ github, context }) { @@ -270,17 +365,18 @@ async function evaluateOnce({ github, context }) { // Post-merge label/comment edits re-fire this event; a closed PR has nothing to gate. if (pr.state === 'closed') return closedNoop(pr); assertEligible(pr, event.head.sha, event.base.ref); - await assertEvidence(github, repo, pr.number, pr.head.sha, POLICY_CHECKS); + const path = await assertEvidence(github, repo, pr.number, pr.head.sha, POLICY_CHECKS, pr); const { data: current } = await github.rest.pulls.get({ ...repo, pull_number: event.number }); if (current.state === 'closed') return closedNoop(current); assertEligible(current, event.head.sha, event.base.ref); - return `PR #${pr.number}: five existing policy providers succeeded on ${pr.head.sha}`; + return `PR #${pr.number}: five existing policy providers succeeded on ${pr.head.sha}; ${path}`; } if (context.eventName !== 'merge_group' || context.payload.action !== 'checks_requested') { throw new Error('Unsupported policy event'); } const group = context.payload.merge_group; const members = await readQueue(github, repo, group); + const paths = []; for (const entry of members) { const { number, headRefOid: head } = entry.pullRequest; const { data: pr } = await github.rest.pulls.get({ ...repo, pull_number: number }); @@ -292,7 +388,7 @@ async function evaluateOnce({ github, context }) { throw new Error(`#${number}: current PR head is not contained in the tested group`); } await assertReviews(github, repo, number, head); - await assertEvidence(github, repo, number, head, { ...POLICY_CHECKS, ...BUILD_CHECKS }); + paths.push(`#${number} ${await assertEvidence(github, repo, number, head, { ...POLICY_CHECKS, ...BUILD_CHECKS }, pr)}`); } // Re-read both membership and mutable gates after all evidence reads. This // bounds TOCTOU, but GitHub/Hive reconciliation is not an atomic transaction. @@ -309,14 +405,14 @@ async function evaluateOnce({ github, context }) { ...repo, ref: group.head_ref.slice('refs/'.length), }); if (ref.object?.sha !== group.head_sha) throw new Error('Synthetic group ref moved'); - return `Group ${group.head_sha}: validated all ${members.length} member heads`; + return `Group ${group.head_sha}: validated all ${members.length} member heads (${paths.join('; ')})`; } module.exports = { ACTIONS_APP_ID, DCO_APP_ID, POLICY_CHECKS, BUILD_CHECKS, PendingEvidence, membersForGroup, assertEligible, evidenceForHead, closedNoop, evaluate, isTransientAPIError, isCosmeticLabelFlip, replayLastVerdict, BLOCKED_LABEL, - ProviderUnavailable, + ProviderUnavailable, FORWARD_MERGE, PROW, DCO_ENUMERATION_SUMMARY_PREFIX, DCO_ENUMERATION_SUMMARY_FALLBACK, DCO_PROVIDER_UNAVAILABLE_TEXT, DCO_PROVIDER_RUNBOOK, }; diff --git a/.github/scripts/native-queue-policy.test.cjs b/.github/scripts/native-queue-policy.test.cjs index 7a08dfec2f..742d90ffa7 100644 --- a/.github/scripts/native-queue-policy.test.cjs +++ b/.github/scripts/native-queue-policy.test.cjs @@ -5,7 +5,7 @@ const { ACTIONS_APP_ID, DCO_APP_ID, POLICY_CHECKS, BUILD_CHECKS, PendingEvidence, membersForGroup, assertEligible, evidenceForHead, closedNoop, evaluate, isTransientAPIError, isCosmeticLabelFlip, replayLastVerdict, - ProviderUnavailable, + ProviderUnavailable, FORWARD_MERGE, PROW, DCO_ENUMERATION_SUMMARY_PREFIX, DCO_ENUMERATION_SUMMARY_FALLBACK, DCO_PROVIDER_UNAVAILABLE_TEXT, @@ -206,6 +206,99 @@ test('UNKNOWN reporting requires trusted exact-head completed DCO and the specif error => !(error instanceof ProviderUnavailable) && error.message === 'DCO: failure'); }); +// #17030: v6-topup.yml's PR whose probot DCO rejects a commit already on v5. +function forwardMergeFixture() { + const f = fixture('pull_request_target'); + Object.assign(f.state.prs[0], { + head: { sha: sha(11), ref: 'sync/v5-to-v6', repo: { full_name: 'acme/widget' } }, + base: { ref: 'v6' }, user: { ...FORWARD_MERGE.author }, + }); + f.context.payload.pull_request = clone(f.state.prs[0]); + f.state.runs.get(sha(11)).find(r => r.name === 'DCO').conclusion = 'action_required'; + // sha(201) is the v5 commit probot rejects; sha(11) is the top-up merge of + // v5 (sha(201)) onto v6 (sha(300)). + f.state.commits = [ + { sha: sha(201), parents: [{ sha: sha(200) }] }, + { sha: sha(11), parents: [{ sha: sha(300) }, { sha: sha(201) }] }, + ]; + f.state.reachable = new Set([`v5...${sha(201)}`, `v6...${sha(300)}`]); + f.state.statuses = [ + { id: 1, context: 'dco', state: 'success', creator: { login: PROW.login, id: PROW.id } }, + ]; + f.github.rest.pulls.listCommits = 'commits'; + f.github.rest.repos.listCommitStatusesForRef = 'statuses'; + f.github.rest.repos.compareCommitsWithBasehead = async ({ basehead }) => { + f.state.seen.push(basehead); + return { data: { status: f.state.reachable.has(basehead) ? 'behind' : 'diverged' } }; + }; + const basePaginate = f.github.paginate; + f.github.paginate = async (method, args) => { + if (method === 'commits') return clone(f.state.commits); + if (method === 'statuses') return clone(f.state.statuses); + return basePaginate(method, args); + }; + return f; +} + +test('v5-reachable sync/v5-to-v6 forward-merge passes on prow dco without probot DCO', async () => { + const f = forwardMergeFixture(); + assert.match(await evaluate(f), + /five existing policy providers succeeded.*DCO path: prow dco for v5-reachable sync\/v5-to-v6 forward-merge/); + assert.deepEqual(f.state.seen, [`v5...${sha(201)}`, `v6...${sha(300)}`, `v5...${sha(201)}`]); +}); + +test('one commit unreachable from v5 keeps the forward-merge on probot DCO', async () => { + const unreachable = forwardMergeFixture(); + unreachable.state.reachable.delete(`v5...${sha(201)}`); + await assert.rejects(evaluate(unreachable), /DCO: action_required.*probot DCO.*not reachable from v5/); + const extra = forwardMergeFixture(); + extra.state.commits.splice(1, 0, { sha: sha(202), parents: [{ sha: sha(201) }] }); + await assert.rejects(evaluate(extra), new RegExp(`DCO: action_required.*${sha(202)} is not reachable from v5`)); + for (const parents of [[{ sha: sha(201) }], [{ sha: sha(301) }, { sha: sha(201) }], [{ sha: sha(300) }, { sha: sha(202) }]]) { + const notMerge = forwardMergeFixture(); + notMerge.state.commits[1].parents = parents; + await assert.rejects(evaluate(notMerge), /DCO: action_required.*is not a merge of v5 into v6/); + } + const truncated = forwardMergeFixture(); + truncated.state.commits = Array.from({ length: 250 }, (_, i) => ({ sha: sha(1000 + i), parents: [] })); + await assert.rejects(evaluate(truncated), /DCO: action_required.*commit list unverifiable/); + // Probot DCO succeeding still admits through the unchanged path. + unreachable.state.runs.get(sha(11)).find(r => r.name === 'DCO').conclusion = 'success'; + assert.match(await evaluate(unreachable), /DCO path: probot DCO \(App 1861\); sync\/v5-to-v6 fallback/); +}); + +test('another head branch, base, fork or author keeps requiring probot DCO', async () => { + for (const change of [ + pr => { pr.head.ref = 'sync/v5-to-v6-extra'; }, + pr => { pr.head.repo.full_name = 'fork/widget'; }, + pr => { pr.user = { login: 'clubanderson', id: 1, type: 'User' }; }, + pr => { pr.user.id = 1; }, + pr => { pr.user.login = 'hivecommons-hive[bot]'; }, + ]) { + const f = forwardMergeFixture(); + change(f.state.prs[0]); + await assert.rejects(evaluate(f), error => error.message === 'DCO: action_required'); + assert.equal(f.state.seen.length, 0); + } + const v5 = forwardMergeFixture(); + v5.state.prs[0].base.ref = 'v5'; + v5.context.payload.pull_request.base.ref = 'v5'; + await assert.rejects(evaluate(v5), error => error.message === 'DCO: action_required'); +}); + +test('forward-merge path fails without a successful prow-created dco status', async () => { + const failed = forwardMergeFixture(); + failed.state.statuses.push({ id: 2, context: 'dco', state: 'failure', creator: { login: PROW.login, id: PROW.id } }); + await assert.rejects(evaluate(failed), /prow dco: failure.*DCO path: prow dco/); + // Any workflow token can post a `dco` status; it never stands in for prow. + const forged = forwardMergeFixture(); + forged.state.statuses = [{ id: 3, context: 'dco', state: 'success', creator: { login: 'github-actions[bot]', id: 41898282 } }]; + await assert.rejects(evaluate(forged), error => error instanceof PendingEvidence && /Missing prow dco/.test(error.message)); + const pending = forwardMergeFixture(); + pending.state.statuses[0].state = 'pending'; + await assert.rejects(evaluate(pending), error => error instanceof PendingEvidence); +}); + test('draft, closed, held and moved-head/base PRs cannot pass', () => { for (const change of [ { draft: true }, { state: 'closed' }, { head: { sha: sha(99) } }, { base: { ref: 'v6' } }, @@ -409,11 +502,16 @@ function replayFixture(priorRuns, labels = [], workflowOverride = {}) { check_suite: { id: 5000 + r.id }, details_url: `https://github.com/acme/widget/actions/runs/${3000 + r.id}/job/1`, ...r, })); - f.github.rest.actions.getWorkflowRun = async ({ run_id: id }) => ({ data: { + const baseGetWorkflowRun = f.github.rest.actions.getWorkflowRun; + const basePaginate = f.github.paginate; + f.github.rest.actions.getWorkflowRun = async ({ run_id: id }) => (id < 3000 ? baseGetWorkflowRun({ run_id: id }) : { data: { id, check_suite_id: id + 2000, path: '.github/workflows/native-queue-policy.yml', event: 'pull_request_target', head_sha: head, ...workflowOverride, } }); f.github.paginate = async (method, args) => { + // Policy provider evidence comes from the base fixture (all green). + if (method === 'jobs' && args.run_id < 3000) return basePaginate(method, args); + if (method === 'checks' && !args.check_name) return basePaginate(method, args); if (method === 'jobs') { const run = runs.find(r => 3000 + r.id === args.run_id); if (!run) return []; @@ -440,6 +538,39 @@ test('cosmetic flip replays the latest completed success on the same head', asyn assert.equal(f.state.listed[0].ref, sha(11)); }); +test('cosmetic flip does not replay a success when a policy provider re-ran red on the head', async () => { + for (const name of Object.keys(POLICY_CHECKS)) { + const f = replayFixture([{ id: 7, status: 'completed', conclusion: 'success' }]); + f.state.runs.get(sha(11)).find(r => r.name === name).conclusion = 'failure'; + await assert.rejects(replayLastVerdict(f), new RegExp(`${name}: failure`)); + } +}); + +test('cosmetic flip falls through to the full wait while a policy provider is re-running or missing', async () => { + // PendingEvidence is not a verdict: returning null sends the caller to the + // polling wait instead of failing the check with no retry. + for (const name of Object.keys(POLICY_CHECKS)) { + for (const change of [{ status: 'queued', conclusion: null }, { status: 'in_progress', conclusion: null }]) { + const f = replayFixture([{ id: 7, status: 'completed', conclusion: 'success' }]); + Object.assign(f.state.runs.get(sha(11)).find(r => r.name === name), change); + assert.equal(await replayLastVerdict(f), null); + } + const f = replayFixture([{ id: 7, status: 'completed', conclusion: 'success' }]); + const runs = f.state.runs.get(sha(11)); + runs.splice(runs.findIndex(r => r.name === name), 1); + assert.equal(await replayLastVerdict(f), null); + } +}); + +test('cosmetic flip falls through to the full wait when the DCO provider reports UNKNOWN', async () => { + // The full wait re-raises ProviderUnavailable once and renders the runbook + // job summary; failing here would skip that operator-facing surface. + const f = replayFixture([{ id: 7, status: 'completed', conclusion: 'success' }]); + Object.assign(f.state.runs.get(sha(11)).find(r => r.name === 'DCO'), + { conclusion: 'failure', output: { summary: unavailableSummary } }); + assert.equal(await replayLastVerdict(f), null); +}); + test('cosmetic flip has nothing to replay without a prior success and falls through', async () => { // A failed, cancelled (timed-out) or absent prior run must not be pinned // onto every later stage-label flip: null sends the caller to the full wait. diff --git a/.github/scripts/test-native-queue-workflows.py b/.github/scripts/test-native-queue-workflows.py index e598728df9..79c7b094cf 100644 --- a/.github/scripts/test-native-queue-workflows.py +++ b/.github/scripts/test-native-queue-workflows.py @@ -59,7 +59,13 @@ def test_owned_gate_uses_trusted_base_not_member_code(self): "${{ github.event.merge_group.base_sha || format('refs/heads/{0}', github.event.pull_request.base.ref) }}") self.assertFalse(checkout["persist-credentials"]) manifest = yaml.safe_load((ROOT / ".github/release-lines.yml").read_text()) - self.assertEqual(manifest["pinned"]["native-queue-policy.yml"], ["v6", "-v4"]) + # The admission gate covers the active feature lines (v5 and v6) and + # not feature-frozen v4, however the manifest spells that: v6 became a + # `release_lines` entry on 2026-11-07, so it is covered without an extra. + pinned = manifest["pinned"]["native-queue-policy.yml"] + covered = set(manifest["release_lines"]) | {p for p in pinned if not p.startswith("-")} + covered -= {p[1:] for p in pinned if p.startswith("-")} + self.assertEqual(sorted(covered), ["v5", "v6"]) def test_owned_gate_retriggers_never_cancel_the_evidence_wait(self): # Stage-label flips re-fire the PR-target run every few minutes; a diff --git a/.github/workflows/dco-post-merge.yml b/.github/workflows/dco-post-merge.yml index c681aab0ec..8f61fb8bf0 100644 --- a/.github/workflows/dco-post-merge.yml +++ b/.github/workflows/dco-post-merge.yml @@ -5,6 +5,7 @@ on: branches: - v4 - v5 + - v6 # The checker itself is in scope, not just the history it checks. Until this # filter was added, src/scripts/test-check-dco-trailers.sh existed but no # workflow ever ran it — a change to the checker (or to the waiver logic that @@ -368,7 +369,7 @@ jobs: strategy: fail-fast: false matrix: - branch: [v4, v5] + branch: [v4, v5, v6] steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 if: github.event_name != 'push' || github.ref == format('refs/heads/{0}', matrix.branch) diff --git a/.github/workflows/dco-push-delta.yml b/.github/workflows/dco-push-delta.yml index 670d0b7609..16a5189ad2 100644 --- a/.github/workflows/dco-push-delta.yml +++ b/.github/workflows/dco-push-delta.yml @@ -32,6 +32,7 @@ on: branches: - v4 - v5 + - v6 permissions: contents: read diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml index aa0f731df0..f83cfba952 100644 --- a/.github/workflows/docker.yml +++ b/.github/workflows/docker.yml @@ -56,16 +56,22 @@ on: required: false type: string -# Serialize Docker builds per branch so concurrent merges don't race. Do NOT -# cancel in-progress builds: on a fast-merging release branch (v2 saw ~34 merges -# in 2h), cancel-in-progress meant every build was killed by the next merge and -# NONE ever completed, freezing -latest and blocking all deploys. With -# cancel-in-progress:false the builds queue and each runs to completion. Each -# completed build publishes an immutable SHA tag; publish-image-tags.sh uses a -# per-tag workflow generation to advance moving tags without either starving -# during a merge burst or regressing when queued runs execute out of order. +# Concurrency. PR builds share a group per PR with cancel-in-progress, so a +# force-push supersedes the previous build. PUSH builds (release lines and the +# other long-lived branches) get a group of their own per run, i.e. they are +# never cancelled and never queued behind each other. The earlier shape — one +# group per branch with cancel-in-progress:false — was meant to make them +# "queue and each run to completion", but GitHub's concurrency queue holds at +# most ONE pending run per group: when a third push arrives, the pending +# second run is CANCELLED (not queued) in favour of the newest. On a branch +# merging every few minutes that cancelled most builds (runs 42400016149, +# 42401056583, 42403292505 on 2026-11-07), so most commits never published +# images and Tagged Release had nothing to tag. Parallel push builds are safe: +# each completed build publishes an immutable SHA tag, and +# publish-image-tags.sh uses a per-tag workflow generation (run number) to +# advance moving tags without regressing when builds finish out of order. concurrency: - group: ${{ github.workflow }}-${{ github.event_name == 'pull_request' && github.event.pull_request.number || github.ref }} + group: ${{ github.workflow }}-${{ github.event_name == 'pull_request' && github.event.pull_request.number || github.event_name == 'push' && github.run_id || github.ref }} cancel-in-progress: ${{ github.event_name == 'pull_request' }} permissions: diff --git a/.github/workflows/podman-arm64-lane.yml b/.github/workflows/podman-arm64-lane.yml index 33202a3676..31ba339589 100644 --- a/.github/workflows/podman-arm64-lane.yml +++ b/.github/workflows/podman-arm64-lane.yml @@ -92,6 +92,7 @@ on: branches: - v4 - v5 + - v6 pull_request: paths: - '.github/workflows/podman-arm64-lane.yml' @@ -100,6 +101,7 @@ on: branches: - v4 - v5 + - v6 workflow_dispatch: inputs: image: diff --git a/.github/workflows/podman-contract.yml b/.github/workflows/podman-contract.yml index 649b404a6a..4fa12c63d7 100644 --- a/.github/workflows/podman-contract.yml +++ b/.github/workflows/podman-contract.yml @@ -23,6 +23,7 @@ on: branches: - v4 - v5 + - v6 paths: - 'Justfile' - 'src/scripts/check-podman-contract.sh' @@ -32,6 +33,7 @@ on: branches: - v4 - v5 + - v6 paths: - 'Justfile' - 'src/scripts/check-podman-contract.sh' diff --git a/.github/workflows/podman-rootful-lane.yml b/.github/workflows/podman-rootful-lane.yml index 073366d802..ddd8605d3f 100644 --- a/.github/workflows/podman-rootful-lane.yml +++ b/.github/workflows/podman-rootful-lane.yml @@ -70,6 +70,7 @@ on: branches: - v4 - v5 + - v6 pull_request: paths: - '.github/workflows/podman-rootful-lane.yml' @@ -78,6 +79,7 @@ on: branches: - v4 - v5 + - v6 workflow_dispatch: inputs: somark: diff --git a/.github/workflows/podman-rootless-lane.yml b/.github/workflows/podman-rootless-lane.yml index d00c51017b..bfa77f7971 100644 --- a/.github/workflows/podman-rootless-lane.yml +++ b/.github/workflows/podman-rootless-lane.yml @@ -51,6 +51,7 @@ on: branches: - v4 - v5 + - v6 pull_request: paths: - '.github/workflows/podman-rootless-lane.yml' @@ -59,6 +60,7 @@ on: branches: - v4 - v5 + - v6 workflow_dispatch: inputs: bypass: diff --git a/.github/workflows/quadlet-gate.yml b/.github/workflows/quadlet-gate.yml index 27ef5890cb..58f8817c6a 100644 --- a/.github/workflows/quadlet-gate.yml +++ b/.github/workflows/quadlet-gate.yml @@ -62,6 +62,7 @@ on: branches: - v4 - v5 + - v6 pull_request: paths: - '.github/workflows/quadlet-gate.yml' @@ -70,6 +71,7 @@ on: branches: - v4 - v5 + - v6 workflow_dispatch: permissions: diff --git a/.github/workflows/scorecard.yml b/.github/workflows/scorecard.yml index 9612d2a745..acdf52677f 100644 --- a/.github/workflows/scorecard.yml +++ b/.github/workflows/scorecard.yml @@ -4,7 +4,7 @@ on: schedule: - cron: '0 6 * * 1' push: - branches: [ "main", "v4", "v5" ] + branches: [ "main", "v4", "v5", "v6" ] workflow_dispatch: permissions: diff --git a/.github/workflows/suid-contract.yml b/.github/workflows/suid-contract.yml index a13410b915..120e34eb6c 100644 --- a/.github/workflows/suid-contract.yml +++ b/.github/workflows/suid-contract.yml @@ -22,6 +22,7 @@ on: branches: - v4 - v5 + - v6 paths: - 'src/Dockerfile' - 'src/deploy/entrypoint.sh' @@ -39,6 +40,7 @@ on: branches: - v4 - v5 + - v6 paths: - 'src/Dockerfile' - 'src/deploy/entrypoint.sh' diff --git a/.github/workflows/tagged-release.yml b/.github/workflows/tagged-release.yml index fed1258b22..7da7e69216 100644 --- a/.github/workflows/tagged-release.yml +++ b/.github/workflows/tagged-release.yml @@ -14,6 +14,13 @@ name: Tagged Release # published, which is also the digest this workflow retags — it can never # race ahead of or duplicate that build. # +# RELEASE LINE: every branch reference below is `RELEASE_LINE` +# (github.ref_name — the branch this copy of the workflow runs from), guarded +# by `check-release-lines.sh --is-release-line` (#9154). Where the prose +# below says "v5" it is describing the default line as the worked example; +# the same rules apply verbatim to v6 (and any later line under +# release_lines in .github/release-lines.yml). +# # DECISION: src/scripts/derive-release-version.sh reads CHANGELOG.md's # `## Unreleased` section (already the human-curated, PR-time judgment call # for "is this release-worthy", not an emoji-prefix guess — see the script's @@ -33,19 +40,30 @@ name: Tagged Release # fragment deletions. An empty Unreleased with an empty changelog.d/ is still # the release=false no-op, so the IDEMPOTENCY loop below is unchanged. # -# RACES (#5142, #5222): the gate-earning dance below takes minutes, and v5 -# can advance underneath it. Two rules keep that from starving releases or -# painting red runs for normal traffic: -# - SUPERSESSION IS DEFERRAL, NOT FAILURE. If v5 has already advanced past -# this run's commit (precheck job), or advances mid-flight (the final -# step's PR merge becomes non-mergeable because the base moved), this run -# steps aside cleanly: the very merge that won triggered its own -# docker.yml run, whose completion triggers a fresh release run for the -# NEWER tip — and Unreleased is untouched, so that successor derives the -# same release. Retrying here on the old tip could never succeed anyway: -# the images were built from THIS commit, so rebasing the release commit -# onto the new tip would tag content the published images do not -# contain. +# RACES (#5142, #5222, #17015 follow-up): the gate-earning dance below takes +# minutes, and v5 can advance underneath it. Three rules keep that from +# starving releases or painting red runs for normal traffic: +# - THE TAG NAMES THE COMMIT THE IMAGES WERE BUILT FROM, NOT v5's TIP. The +# release commit (compiled CHANGELOG.md + fragment deletions) is parented +# on the exact SHA docker.yml built, and the version tag points at THAT +# commit; the immutable image tags are retags of that SHA's digests. The +# release commit then reaches v5 through a merge-commit PR, which is +# allowed to land on a tip that has moved on — the merge commit is not +# tagged, so commits that arrived after the built SHA are simply "after +# vX.Y.Z" in git terms, exactly as they are in image terms. Until +# 2026-11 the precheck instead DEFERRED whenever v5 had advanced past the +# built SHA, on the theory that the successor run would release. Under a +# sustained merge rate faster than a multi-arch build (~15 min) no run +# ever saw tip == built SHA, every successor deferred again, and v5 went +# from v5.186.4 (2026-10-18) to ~1,700 untagged commits. Deferral is now +# limited to the two cases where releasing really would be wrong: +# (a) the built SHA is NOT an ancestor of v5's tip (force-push, or a +# build of something that never landed) — nothing to tag; +# (b) a release already landed on v5 AFTER the built SHA (the newest +# v5.* tag is not an ancestor of it) — its fragments are already +# released and the derived version would collide. +# Supersession is still deferral, not failure, and Unreleased is +# untouched so nothing is dropped. # - MERGEABILITY SETTLING IS RETRIED. A direct `git push` to v5 (the # pre-#5222 approach) was retried on GH006 under the theory that branch # protection just needed a few seconds to ingest the gate check-run's @@ -114,35 +132,26 @@ name: Tagged Release # outright if it already exists (a re-run after a partial failure is a safe # no-op, not a duplicate release). # BACKSTOP (#5318): the workflow_run trigger alone cannot guarantee that a -# release-worthy commit ever gets a release opportunity. Two ways one is lost -# silently: -# - A docker.yml run that is CANCELLED never fires workflow_run at all. A -# multi-arch build takes ~10 minutes, so when merges arrive faster than -# that, most commits never complete one. -# - A run that DOES fire defers at `precheck` when v5 has already advanced, -# on the reasoning that the successor releases instead. That reasoning is -# sound per-run but has no terminating condition: under sustained merges -# every successor applies the same test and defers again. -# #10863 adds a short post-publish merge hold: once precheck proves v5 is still -# at the SHA whose docker.yml images are published, it posts a pending -# `release-in-progress` status on that tip and temporarily adds -# `do-not-merge/hold` to open v5 PRs. Hive's automerge sweep treats the status -# as a short-lived repo-level hold; Tide and hive both respect the hold label. -# This job clears both signals when the tag is pushed (or in cleanup on failure). -# This keeps the race-safety checks below: -# if v5 still advances during the hold, the release defers rather than tagging -# images from the wrong tree. -# Neither is a bug in the deferral itself — a superseded run genuinely must -# not release, because its images were built from the old tree (see RACES). -# The gap is that nothing ever comes back for the work left behind. The -# schedule below is that "come back": it runs against v5's CURRENT tip. If -# that exact tip's images are not published yet, it explicitly starts docker.yml -# for v5 and exits green; the resulting workflow_run is then allowed to enter -# this workflow and release if v5 is still at that published SHA. When a -# workflow_run still defers because the branch moved, precheck re-arms the same -# backstop by dispatching docker.yml for the new tip if no such run exists, so -# recovery does not depend on GitHub delivering the next hourly cron. On a -# healthy repo it is a no-op (Unreleased is empty => release=false). +# release-worthy commit ever gets a release opportunity: a docker.yml run +# that is CANCELLED never fires workflow_run at all, and GitHub's concurrency +# queue holds at most one pending run per group, so under a merge burst most +# commits never complete a build. The hourly schedule below is the "come +# back" for that work. It considers the NEWEST commit on v5 that is an +# ancestor of the current tip AND has a successful, completed publishing +# docker.yml run — not necessarily the tip itself, which on a busy branch +# is almost never built yet. If no built ancestor exists among the recent +# commits it stands down green and dispatches docker.yml for the tip so the +# next tick has something to release. +# #10863 adds a short post-publish merge hold: once precheck accepts a built +# SHA, it posts a pending `release-in-progress` status on that SHA and +# temporarily adds `do-not-merge/hold` to open v5 PRs. Hive's automerge sweep +# treats the status as a short-lived repo-level hold; Tide and hive both +# respect the hold label. The hold keeps the release PR's merge quick; it is +# no longer a correctness requirement, because a v5 that advances mid-flight +# no longer makes the release defer (see RACES). This job clears both signals +# when the tag is pushed (or in cleanup on failure). +# On a healthy repo the backstop is a no-op (Unreleased is empty => +# release=false). # # DUAL-PUBLISH (kubestellar -> hivecommons org transfer): during the transfer # window every publish targets BOTH ghcr.io/kubestellar and @@ -161,13 +170,20 @@ on: - cron: "37 * * * *" workflow_dispatch: -# RELEASE LINE (#9154): the line is the branch this run was started from — -# the default branch for `workflow_run`/`schedule`, the chosen ref for -# `workflow_dispatch` — never a literal. The `decide` job refuses unless that -# branch is under `release_lines` in .github/release-lines.yml, so the same -# file is correct on every line, a dispatch from a development line (v6 before -# its GA cut) can no longer release another line's tip, and cutting a new line -# needs no edit here. Checklist: src/docs/release-line-guard.md. +# NON-DEFAULT RELEASE LINES: GitHub delivers `workflow_run` and `schedule` +# events ONLY to the default branch's copy of this file, so a docker.yml run +# on another release line (v6 after its cut) never reaches that line's own +# copy by itself. The `relay` job below closes that gap: when the default +# copy sees a successful push/dispatch build of ANOTHER declared release line, +# it dispatches this workflow on that line (`--ref `), and the dispatched +# run takes the backstop path — resolve the line's tip, require its images to +# be published, derive, release — under that line's own `concurrency` group. +# The relay is event-driven only: the hourly schedule stays a default-branch +# backstop, and a non-default line whose build was cancelled is picked up by +# its next completed build or by a manual `gh workflow run tagged-release.yml +# --ref `. The relay reads release_lines from ITS OWN checkout (the +# default branch), never from the line it is relaying to. + concurrency: group: tagged-release-${{ github.ref_name }} cancel-in-progress: false @@ -194,21 +210,62 @@ permissions: issues: write jobs: + # Relay a non-default release line's completed build to that line's own copy + # of this workflow (see NON-DEFAULT RELEASE LINES in the header). Same + # event/conclusion filter as `decide`, with the branch test inverted; the + # release-line test itself needs the manifest, so it happens in the step. + relay: + if: >- + github.event_name == 'workflow_run' && + github.event.workflow_run.conclusion == 'success' && + ( github.event.workflow_run.event == 'push' || github.event.workflow_run.event == 'workflow_dispatch' ) && + github.event.workflow_run.head_branch != github.ref_name + runs-on: ubuntu-latest + timeout-minutes: 5 + permissions: + contents: read + actions: write + steps: + - name: Checkout the release-line manifest from this workflow's ref + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + sparse-checkout: | + .github/release-lines.yml + src/scripts/check-release-lines.sh + sparse-checkout-cone-mode: false + + - name: Dispatch Tagged Release on the built release line + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + LINE: ${{ github.event.workflow_run.head_branch }} + BUILT_SHA: ${{ github.event.workflow_run.head_sha }} + run: | + set -euo pipefail + # head_branch is attacker-free here (push/workflow_dispatch builds + # are always this repository's own branches) but is still a free + # string; refuse anything that is not a plain vN before it reaches + # a --ref argument. + if ! [[ "$LINE" =~ ^v[0-9]+$ ]]; then + echo "docker.yml built '${LINE}', which is not a vN branch; nothing to relay." + exit 0 + fi + if ! src/scripts/check-release-lines.sh --is-release-line "$LINE"; then + echo "docker.yml built '${LINE}', which is not under release_lines in .github/release-lines.yml; nothing to relay." + exit 0 + fi + echo "docker.yml published ${BUILT_SHA} on release line ${LINE}; dispatching Tagged Release on ${LINE} so its own copy can consider it." + gh workflow run tagged-release.yml --repo "${{ github.repository }}" --ref "$LINE" + + decide: - # workflow_run: only a successful docker.yml build of a real push to, or - # a workflow_dispatch on, the release line. The event filter is what makes - # `head_branch` trustworthy: docker.yml also runs on `pull_request` with - # no branch filter, and a fork PR's `head_branch` is whatever the fork - # named its branch — `v5` included — so comparing the name alone would - # admit a fork's commit. Push and workflow_dispatch runs are always on one - # of this repository's own branches. Both count (#10863): post-release - # dispatches are harmless because Unreleased is already empty, and the - # backstop below may need to prime docker.yml manually when a busy line's - # current tip has not yet published images. (The scratch-branch gate - # dance's dispatch runs on release-gate/*, never on the line itself, so the - # head_branch check still keeps us off our own tail.) + # workflow_run: only a successful docker.yml build for v5. Both push and + # workflow_dispatch builds count: post-release dispatches are harmless + # because Unreleased is already empty, and the backstop below may need to + # prime docker.yml manually when a busy branch's current tip has not yet + # published images. # schedule/workflow_dispatch: the #5318 backstop, which has no triggering - # run to qualify and instead resolves the line's current tip below. + # run to qualify and instead resolves v5's current tip below. if: >- github.event_name != 'workflow_run' || ( github.event.workflow_run.conclusion == 'success' && @@ -223,21 +280,51 @@ jobs: sha: ${{ steps.target.outputs.sha }} steps: # workflow_run carries the exact commit docker.yml built. The backstop - # has no such commit, so it resolves the line's tip — whose images are already - # published (its docker.yml run completed long before an hourly tick), - # which is what keeps the retag honest. + # has no such commit, so it walks v5's recent history from the tip and + # picks the NEWEST commit with a successful, completed publishing + # docker.yml run (push, or a v5 workflow_dispatch — #6380). On a busy + # branch the tip itself is almost never built yet; releasing its newest + # built ancestor is what keeps the retag honest without waiting for a + # quiet hour that may never come (see BACKSTOP). If nothing in the + # window is built, the tip is reported so the guard below stands down + # and primes docker.yml for it. - name: Resolve the commit to consider releasing id: target env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + # How far back from the tip the backstop looks for a built commit. + # 100 commits is several hours of the busiest merge rate seen so + # far; a built commit older than that has had many hourly ticks. + BACKSTOP_WINDOW: ${{ vars.RELEASE_BACKSTOP_WINDOW || '100' }} run: | set -euo pipefail if [ "${{ github.event_name }}" = "workflow_run" ]; then sha="${{ github.event.workflow_run.head_sha }}" echo "Triggered by docker.yml on ${sha}." else - sha="$(gh api "repos/${{ github.repository }}/branches/${RELEASE_LINE}" --jq .commit.sha)" - echo "Backstop (${{ github.event_name }}): considering ${RELEASE_LINE} tip ${sha}." + tip="$(gh api "repos/${{ github.repository }}/branches/${RELEASE_LINE}" --jq .commit.sha)" + # Newest 100 successful runs: more than the commit window below + # can need, without paginating through months of history. + built="$(gh api \ + "repos/${{ github.repository }}/actions/workflows/docker.yml/runs?branch=${RELEASE_LINE}&status=success&per_page=100" \ + --jq ".workflow_runs[] | select(.event == \"push\" or (.event == \"workflow_dispatch\" and .head_branch == \"${RELEASE_LINE}\")) | .head_sha" \ + | sort -u)" + sha="" + while IFS= read -r candidate; do + [ -n "$candidate" ] || continue + if grep -qx "$candidate" <<<"$built"; then + sha="$candidate" + break + fi + done < <(gh api "repos/${{ github.repository }}/commits?sha=${tip}&per_page=${BACKSTOP_WINDOW}" --jq '.[].sha') + if [ -z "$sha" ]; then + echo "Backstop (${{ github.event_name }}): none of the newest ${BACKSTOP_WINDOW} commits on ${RELEASE_LINE} has a successful publishing docker.yml run; considering tip ${tip} so the guard below can prime a build." + sha="$tip" + elif [ "$sha" = "$tip" ]; then + echo "Backstop (${{ github.event_name }}): ${RELEASE_LINE} tip ${sha} is built; considering it." + else + echo "Backstop (${{ github.event_name }}): ${RELEASE_LINE} tip is ${tip}; its newest built ancestor is ${sha} — considering that." + fi fi echo "sha=${sha}" >> "$GITHUB_OUTPUT" @@ -295,10 +382,10 @@ jobs: run: | set -euo pipefail sha="${{ steps.target.outputs.sha }}" - # A `push` run is the normal case; a `workflow_dispatch` run on the - # line is the post-release exact-SHA rebuild of a GITHUB_TOKEN merge - # commit (#6380). Both publish the / -latest / channel - # tags, so both count as published for the backstop. + # A `push` run is the normal case; a `workflow_dispatch` run on v5 + # is the post-release exact-SHA rebuild of a GITHUB_TOKEN merge commit + # (#6380). Both publish the / v5-latest / candidate tags, so + # both count as published for the backstop. conclusion="$(gh api \ "repos/${{ github.repository }}/actions/workflows/docker.yml/runs?head_sha=${sha}&status=completed" \ --jq "[.workflow_runs[] | select(.event == \"push\" or (.event == \"workflow_dispatch\" and .head_branch == \"${RELEASE_LINE}\"))] | last | .conclusion // \"\"")" @@ -326,27 +413,28 @@ jobs: if: github.event_name == 'workflow_run' || steps.images.outputs.published == 'true' # The checkout above is a detached SHA, so the script cannot read the # line from the branch name; it reads the workflow-level RELEASE_LINE - # instead (the same value as concurrency, --base, --ref), and refuses - # to run without it. + # (github.ref_name, the branch this workflow runs from) instead. The + # script refuses to run without it. run: src/scripts/derive-release-version.sh - # Cheap supersession check BEFORE the expensive release job (#5142): if the - # line already moved past the commit this run was triggered for, every minute - # spent here is wasted — the final push can only ever be rejected - # non-fast-forward — and worse, the `concurrency` group above serializes - # release runs, so a doomed run delays the successor that CAN release. One - # API call decides in seconds. + # Cheap eligibility check BEFORE the expensive release job (#5142): one or + # two API calls decide in seconds whether this run's built SHA can be + # tagged, so a run that cannot does not burn the `concurrency` slot a + # successor needs. # - # #5318: this job used to claim the successor was GUARANTEED to exist ("the - # merge that advanced the line triggered docker.yml, whose completion triggers - # tagged-release.yml for that newer tip"). That guarantee does not hold — a - # cancelled docker.yml run fires no workflow_run at all, and a successor - # that does fire applies this same test and defers again. Deferring is still - # the right call for THIS run (its images were built from the old tree), so - # the fix is not to stop deferring; it is that the schedule trigger above - # now provides the terminating condition, and the deferral is logged as a - # ::warning:: rather than a ::notice:: so a lost opportunity is visible in - # the run list instead of silently disappearing. + # Until 2026-11 this job deferred whenever v5's tip != the built SHA. That + # rule had no terminating condition under sustained merges (every + # successor saw a moved tip and deferred too — #5318 added the hourly + # backstop, which applied the same test to the tip and stood down for the + # same reason), and it stalled tagging for three weeks. The release now + # names the BUILT commit (see RACES), so a moved tip is not a reason to + # defer. The two remaining deferrals are the cases where tagging the built + # SHA would be wrong: + # (a) the built SHA is not an ancestor of v5's tip — nothing to release; + # (b) a release already landed AFTER the built SHA — the fragments this + # run compiled are already in a dated entry, and its derived version + # would collide with the tag that release pushed. + # Both are logged as ::warning:: so a skipped opportunity stays visible. precheck: needs: decide if: needs.decide.outputs.release == 'true' @@ -357,44 +445,77 @@ jobs: hold_sha: ${{ steps.tip.outputs.hold_sha }} held_prs: ${{ steps.tip.outputs.held_prs }} steps: - - name: Defer to the successor run if the release line already advanced + - name: Confirm the built commit is on the release line and newer than the last release id: tip env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + VERSION: ${{ needs.decide.outputs.version }} run: | set -euo pipefail sha="${{ needs.decide.outputs.sha }}" - tip="$(gh api "repos/${{ github.repository }}/branches/${RELEASE_LINE}" --jq .commit.sha)" + repo="${{ github.repository }}" + tip="$(gh api "repos/${repo}/branches/${RELEASE_LINE}" --jq .commit.sha)" + + defer() { + echo "::warning::Release opportunity skipped for ${sha}: $1 Unreleased is untouched, so nothing is dropped: a later run releases whatever is still pending. See the RACES and BACKSTOP notes in this workflow's header." + echo "proceed=false" >> "$GITHUB_OUTPUT" + exit 0 + } + + # (a) The built SHA must be reachable from v5's tip. compare/A...B + # reports B relative to A: "ahead" (tip has more commits on top of + # the built SHA) or "identical" both mean the built SHA is an + # ancestor; "behind"/"diverged" mean it is not on v5 any more. if [ "$tip" = "$sha" ]; then - echo "${RELEASE_LINE} is still at ${sha} — proceeding with the release." - gh api --method POST "repos/${{ github.repository }}/statuses/${sha}" \ - -f state=pending \ - -f context=release-in-progress \ - -f description="Tagged Release is holding ${RELEASE_LINE} merges for up to ${{ vars.RELEASE_MERGE_HOLD_SECONDS || '300' }}s" - gh label create "do-not-merge/hold" --color bfdadc --description "Temporarily blocks Tide/hive automerge" >/dev/null 2>&1 || true - held_prs="" - while IFS= read -r pr; do - [ -n "$pr" ] || continue - gh pr edit "$pr" --add-label "do-not-merge/hold" - held_prs="${held_prs}${held_prs:+,}${pr}" - done < <(gh pr list --base "$RELEASE_LINE" --state open --limit 200 --json number,labels --jq '.[] | select(([.labels[].name] | index("do-not-merge/hold")) | not) | .number') - echo "Temporarily applied do-not-merge/hold to PRs: ${held_prs:-}." - echo "proceed=true" >> "$GITHUB_OUTPUT" - echo "hold_sha=${sha}" >> "$GITHUB_OUTPUT" - echo "held_prs=${held_prs}" >> "$GITHUB_OUTPUT" + echo "${RELEASE_LINE} is still at the built commit ${sha}." else - echo "::warning::Release opportunity skipped for ${sha}: ${RELEASE_LINE} is already at ${tip}. Deferring — this run's images were built from the older tree, so it must not tag. Unreleased is untouched, so nothing is dropped: either a successor run releases it, or the hourly backstop does. See the RACES note and the BACKSTOP note in this workflow's header (#5142/#5318)." - existing="$(gh api "repos/${{ github.repository }}/actions/workflows/docker.yml/runs?head_sha=${tip}&per_page=20" --jq "[.workflow_runs[] | select(.event == \"push\" or (.event == \"workflow_dispatch\" and .head_branch == \"${RELEASE_LINE}\"))] | length")" - if [ "${existing:-0}" -eq 0 ]; then - gh workflow run docker.yml --ref "$RELEASE_LINE" \ - && echo "Re-armed docker.yml for current ${RELEASE_LINE} tip ${tip}." \ - || echo "::warning::could not dispatch docker.yml for ${tip}; waiting for the next scheduled tick." - else - echo "docker.yml already has ${existing} run(s) for current ${RELEASE_LINE} tip ${tip}; not re-dispatching." - fi - echo "proceed=false" >> "$GITHUB_OUTPUT" + rel="$(gh api "repos/${repo}/compare/${sha}...${tip}" --jq .status)" + case "$rel" in + ahead) echo "${RELEASE_LINE} has advanced to ${tip}; the built commit ${sha} is an ancestor, so it is released as-built and the newer commits follow in the next release." ;; + identical) echo "${RELEASE_LINE} tip ${tip} is the built commit." ;; + *) defer "it is not an ancestor of ${RELEASE_LINE}'s current tip ${tip} (compare status '${rel}'), so there is nothing on ${RELEASE_LINE} to tag." ;; + esac + fi + + # (b) No release may have landed after the built SHA. The newest + # version tag's commit must be an ancestor of the built SHA; if it + # is not, a release was cut from a commit this build never saw and + # the fragments compiled here are already released. The derived + # version is the cheap first signal (the release job refuses an + # existing tag outright), and the ancestry check catches the same + # situation when the colliding release bumped differently. + if gh api "repos/${repo}/git/ref/tags/v${VERSION}" --jq .object.sha >/dev/null 2>&1; then + defer "v${VERSION} already exists — a release landed after this commit was built, so its fragments are already released." + fi + latest_tag="$(gh api --paginate "repos/${repo}/git/matching-refs/tags/${RELEASE_LINE}." --jq '.[].ref' \ + | sed 's#^refs/tags/##' | grep -E "^${RELEASE_LINE}\.[0-9]+\.[0-9]+\$" | sort -V | tail -1 || true)" + if [ -n "$latest_tag" ]; then + rel="$(gh api "repos/${repo}/compare/${latest_tag}...${sha}" --jq .status)" + case "$rel" in + ahead) echo "Newest release ${latest_tag} is an ancestor of ${sha} — this release is newer than the last." ;; + *) defer "the newest release ${latest_tag} is not an ancestor of it (compare status '${rel}'); a release already landed after this commit was built." ;; + esac fi + echo "Proceeding with the release of ${sha} as v${VERSION}." + gh api --method POST "repos/${repo}/statuses/${sha}" \ + -f state=pending \ + -f context=release-in-progress \ + -f description="Tagged Release is holding ${RELEASE_LINE} merges for up to ${{ vars.RELEASE_MERGE_HOLD_SECONDS || '300' }}s" + gh label create "do-not-merge/hold" --color bfdadc --description "Temporarily blocks Tide/hive automerge" >/dev/null 2>&1 || true + held_prs="" + while IFS= read -r pr; do + [ -n "$pr" ] || continue + gh pr edit "$pr" --add-label "do-not-merge/hold" + held_prs="${held_prs}${held_prs:+,}${pr}" + done < <(gh pr list --base "$RELEASE_LINE" --state open --limit 200 --json number,labels --jq '.[] | select(([.labels[].name] | index("do-not-merge/hold")) | not) | .number') + echo "Temporarily applied do-not-merge/hold to PRs: ${held_prs:-}." + { + echo "proceed=true" + echo "hold_sha=${sha}" + echo "held_prs=${held_prs}" + } >> "$GITHUB_OUTPUT" + release: needs: [decide, precheck] if: needs.decide.outputs.release == 'true' && needs.precheck.outputs.proceed == 'true' @@ -584,7 +705,7 @@ jobs: # silently couple a version tag to it. - name: Confirm channel tags were not touched run: | - echo "This workflow only ever writes vX.Y.Z tags. stable/candidate/edge are owned exclusively by docker.yml's merge jobs on every push to a release branch, independent of whether a release was cut here." + echo "This workflow only ever writes vX.Y.Z tags. stable/candidate/edge are owned exclusively by docker.yml's merge jobs on every push to the release line, independent of whether a release was cut here." # SBOM: a standalone release ARTIFACT, not an in-image attestation. # @@ -941,37 +1062,39 @@ jobs: -f context=gate \ -f description="docker.yml gate verified for automated release" - echo "Trying direct ${RELEASE_LINE} push first (#10863); falling back to the release PR path if branch protection rejects it..." + # The release commit is parented on $SHA, the commit the images were + # built from. A direct push can only land it when v5 is still at + # $SHA (fast-forward); otherwise it reaches v5 as a merge commit via + # the PR path below. Either way the version tag names the release + # commit itself (see RACES), so a tip that has moved on is not a + # reason to stand down — it only decides which route the commit + # takes and whether the follow-up image build may self-report the + # tag (a merge commit that also carries newer v5 work must not). git fetch origin "$RELEASE_LINE" current_tip="$(git rev-parse "origin/${RELEASE_LINE}")" - if [ "$current_tip" != "$SHA" ]; then - echo "::warning::Release opportunity skipped for ${SHA}: ${RELEASE_LINE} advanced to ${current_tip} before the direct push. Nothing was pushed; Unreleased is untouched." - echo "pushed=false" >> "$GITHUB_OUTPUT" - exit 0 - fi - if direct_out="$(git push origin "HEAD:refs/heads/${RELEASE_LINE}" 2>&1)"; then - echo "$direct_out" - release_sha="$commit_sha" - merged=true - echo "Direct push landed release commit ${release_sha} on ${RELEASE_LINE}; dispatching docker.yml for the release commit (#6380)..." - GH_TOKEN="$ACTIONS_TOKEN" gh workflow run docker.yml --ref "$RELEASE_LINE" \ - -f "release_sha=${release_sha}" \ - -f "release_version=v${VERSION}" - else - echo "$direct_out" - if grep -qiE 'non-fast-forward|fetch first|stale info' <<<"$direct_out"; then - echo "::warning::Release opportunity skipped for ${SHA}: ${RELEASE_LINE} advanced during the direct push. Nothing was pushed; Unreleased is untouched." - echo "pushed=false" >> "$GITHUB_OUTPUT" - exit 0 - fi - git fetch origin "$RELEASE_LINE" - current_tip="$(git rev-parse "origin/${RELEASE_LINE}")" - if [ "$current_tip" != "$SHA" ]; then - echo "::warning::Release opportunity skipped for ${SHA}: ${RELEASE_LINE} advanced to ${current_tip} while branch protection rejected the direct push. Nothing was pushed; Unreleased is untouched." - echo "pushed=false" >> "$GITHUB_OUTPUT" - exit 0 + tip_is_built=false + if [ "$current_tip" = "$SHA" ]; then + tip_is_built=true + echo "Trying direct ${RELEASE_LINE} push first (#10863); falling back to the release PR path if branch protection rejects it..." + if direct_out="$(git push origin "HEAD:refs/heads/${RELEASE_LINE}" 2>&1)"; then + echo "$direct_out" + release_sha="$commit_sha" + merged=true + echo "Direct push landed release commit ${release_sha} on ${RELEASE_LINE}; dispatching docker.yml for the release commit (#6380)..." + GH_TOKEN="$ACTIONS_TOKEN" gh workflow run docker.yml --ref "$RELEASE_LINE" \ + -f "release_sha=${release_sha}" \ + -f "release_version=v${VERSION}" + else + echo "$direct_out" + if grep -qiE 'non-fast-forward|fetch first|stale info' <<<"$direct_out"; then + echo "${RELEASE_LINE} advanced during the direct push; continuing via the release PR path (merge commit)." + tip_is_built=false + else + echo "Direct push was rejected by branch protection (expected until the GitHub Actions app has a ${RELEASE_LINE} bypass); falling back to the release PR path." + fi fi - echo "Direct push was rejected by branch protection (expected until the GitHub Actions app has a ${RELEASE_LINE} bypass); falling back to the release PR path." + else + echo "${RELEASE_LINE} is at ${current_tip}, past the built commit ${SHA}; landing the release commit through the PR path as a merge commit." fi if [ "$merged" != true ]; then @@ -1026,16 +1149,23 @@ jobs: # or a genuinely-unsatisfied required check that is still # settling): retried for a bounded window. # - # non-fast-forward equivalents (base branch moved, merge - # conflict, 409 head-SHA mismatch): v5 advanced mid-flight. - # Retrying could never succeed — this release commit is parented - # on the old tip, and rebasing it forward would tag source the - # already-published images were not built from. Defer instead: - # exit green with a notice, push nothing (tag included), and let - # the successor run — triggered by the very merge that won — cut - # the release from ITS tip. The `pushed` output gates the - # GitHub-Release step below so a deferred run creates no release - # object either. + # 409 "Base branch was modified": v5 advanced since GitHub last + # computed this PR's mergeability. The PR is a MERGE-COMMIT merge + # (v5 protection does not require an up-to-date head), so the + # release commit still lands and the tag still names the release + # commit, not the merge (see RACES): retried for the same bounded + # window. Until 2026-11 this case deferred green and the tip + # usually moved again before the successor got here. + # + # 409 "Head branch was modified": the `sha=` guard fired — + # something rewrote the scratch branch under this run. Nothing + # legitimate does that; hard-fail rather than tag a tree this run + # did not build. + # + # 405 with the PR reported CONFLICTING: a commit after the built + # SHA touched CHANGELOG.md or a fragment this release deletes. + # Retrying cannot resolve a conflict; hard-fail with the PR + # number so a human can rebase it. # # anything else: hard-fail. # RELEASE_MERGE_WAIT_SECONDS is a production knob (default 5m); @@ -1054,7 +1184,7 @@ jobs: repo="${GITHUB_REPOSITORY#*/}" # shellcheck disable=SC2016 # GraphQL variables are expanded by gh, not by the shell. if ! json="$(gh api graphql \ - -f owner="$owner" -f name="$repo" -F number="$pr" -f branch=v5 -f head="$head_sha" \ + -f owner="$owner" -f name="$repo" -F number="$pr" -f branch="$RELEASE_LINE" -f head="$head_sha" \ -f query=' query($owner:String!,$name:String!,$number:Int!,$branch:String!){ repository(owner:$owner,name:$name){ @@ -1174,25 +1304,49 @@ jobs: # #6380: the GITHUB_TOKEN-authenticated merge cannot emit a push # event to docker.yml. Dispatch immediately after the merge, # before tag work widens the ordering window; pass the API's exact - # SHA because the line's ref can advance before the build starts. + # SHA because the v5 ref can advance before the build starts. echo "Dispatching docker.yml for merged release commit ${release_sha} on ${RELEASE_LINE} (#6380)..." - GH_TOKEN="$ACTIONS_TOKEN" gh workflow run docker.yml --ref "$RELEASE_LINE" \ - -f "release_sha=${release_sha}" \ - -f "release_version=v${VERSION}" + # The merge commit may carry v5 work that arrived after the + # built SHA; only let its image self-report the tag when v5 + # was still at the built SHA, i.e. the merge adds nothing but + # the changelog (otherwise `git describe` yields vX.Y.Z-N-g…). + if [ "$tip_is_built" = true ]; then + GH_TOKEN="$ACTIONS_TOKEN" gh workflow run docker.yml --ref "$RELEASE_LINE" \ + -f "release_sha=${release_sha}" \ + -f "release_version=v${VERSION}" + else + GH_TOKEN="$ACTIONS_TOKEN" gh workflow run docker.yml --ref "$RELEASE_LINE" \ + -f "release_sha=${release_sha}" + fi break fi echo "$out" # 409 Conflict from this endpoint means either "Head branch was # modified" (the sha= guard fired) or "Base branch was modified" — # both are the base-moved case, not something a retry fixes. - if grep -qiE 'base branch was modified|head branch was modified|is out of date|HTTP 409' <<<"$out"; then - echo "::warning::Release opportunity skipped for ${SHA}: ${RELEASE_LINE} advanced while this run was in flight — deferring (see the RACES note, #5142/#5222). Nothing was pushed; Unreleased is untouched, so either a successor run or the hourly backstop (#5318) releases it." - echo "pushed=false" >> "$GITHUB_OUTPUT" - exit 0 + if grep -qiE 'head branch was modified' <<<"$out"; then + echo "::error::the release PR's head ${commit_sha} moved under this run (409 sha= guard) — refusing to merge a scratch branch this run did not build." >&2 + exit 1 + fi + if grep -qiE 'base branch was modified|is out of date|HTTP 409' <<<"$out"; then + # v5 moved since mergeability was computed; the merge-commit + # merge is still valid once GitHub recomputes it. + tip_is_built=false + if [ "$SECONDS" -lt "$deadline" ]; then + echo "${RELEASE_LINE} advanced while this run was in flight; the release lands as a merge commit on the new tip — retrying in ${merge_poll_seconds}s..." + sleep "$merge_poll_seconds" + continue + fi + echo "::error::PR #${pr_number} could not be merged within ${merge_wait_seconds}s: ${RELEASE_LINE} kept advancing and GitHub never settled its mergeability." >&2 + exit 1 fi # 405 Method Not Allowed is GitHub's "not mergeable" for this # endpoint — including a required check that has not landed yet. if grep -qiE 'HTTP 405|not mergeable|required status check' <<<"$out"; then + if [ "$(gh api "repos/${GITHUB_REPOSITORY}/pulls/${pr_number}" --jq '.mergeable_state // ""' 2>/dev/null)" = dirty ]; then + echo "::error::PR #${pr_number} conflicts with ${RELEASE_LINE}: a commit after the built ${SHA} touched CHANGELOG.md or a changelog.d fragment this release consumes. Resolve the conflict on the release PR (or close it and let the next build release), then re-run." >&2 + exit 1 + fi required_state="$(required_checks_state "$pr_number" "$commit_sha")" if [ "$required_state" = failed ]; then echo "::error::PR #${pr_number} has a failed required check on ${commit_sha}; closing the release PR instead of waiting out the deadline." >&2 @@ -1203,7 +1357,7 @@ jobs: sleep "$merge_poll_seconds" continue fi - echo "::error::PR #${pr_number} still not mergeable after ${merge_wait_seconds}s on ${commit_sha}. Required checks did not all report before the release merge deadline, or GitHub still rejected the SHA-keyed merge after they did; compare v5's REQUIRED contexts with the combined status for ${commit_sha}, including the mirrored gate status (#5356)." >&2 + echo "::error::PR #${pr_number} still not mergeable after ${merge_wait_seconds}s on ${commit_sha}. Required checks did not all report before the release merge deadline, or GitHub still rejected the SHA-keyed merge after they did; compare ${RELEASE_LINE}'s REQUIRED contexts with the combined status for ${commit_sha}, including the mirrored gate status (#5356)." >&2 exit 1 fi echo "::error::merging PR #${pr_number} failed for an unrecognized reason (see the API response above) — not retrying." >&2 @@ -1211,17 +1365,23 @@ jobs: done fi - # The merge landed a NEW commit on the line (a merge commit, or the same - # tree via fast-forward depending on PR mergeability). Fetch it so - # the object exists locally, but tag the merge API's exact returned - # SHA rather than re-resolving a branch that another PR can advance - # between our merge and this fetch. + # The merge landed the release commit on v5 (directly, or under a + # merge commit the API returned as release_sha). The TAG names the + # release commit ${commit_sha} itself — parented on the built SHA, + # so its tree is exactly what the retagged images were built from + # plus the changelog (see RACES) — never the merge commit, which + # may also carry v5 work that arrived after the build. Confirm the + # release commit really is reachable from v5 before tagging. git fetch origin "$RELEASE_LINE" if ! git merge-base --is-ancestor "$release_sha" "origin/${RELEASE_LINE}"; then echo "::error::merge API returned ${release_sha}, but it is not contained in fetched origin/${RELEASE_LINE}; refusing to tag or dispatch it." >&2 exit 1 fi - git tag "v${VERSION}" "$release_sha" + if ! git merge-base --is-ancestor "$commit_sha" "origin/${RELEASE_LINE}"; then + echo "::error::release commit ${commit_sha} is not contained in fetched origin/${RELEASE_LINE} after the merge; refusing to tag it." >&2 + exit 1 + fi + git tag "v${VERSION}" "$commit_sha" # Tag pushes have no protection race, only transient transport # failures — a plain bounded retry. for attempt in 1 2 3; do @@ -1266,9 +1426,9 @@ jobs: echo echo "---" echo - echo "**SBOMs:** SPDX JSON, generated by Syft against the linux/amd64 image digest, attached below for \`hive\`, \`hive-contributor\`, and \`hive-hub\`. They cover linux/amd64 only — see [releases.md](https://github.com/${{ github.repository }}/blob/${RELEASE_LINE}/src/docs/releases.md#software-bill-of-materials-sbom) for why linux/arm64 is not scanned separately." + echo "**SBOMs:** SPDX JSON, generated by Syft against the linux/amd64 image digest, attached below for \`hive\`, \`hive-contributor\`, and \`hive-hub\`. They cover linux/amd64 only — see [releases.md](https://github.com/${{ github.repository }}/blob/v5/src/docs/releases.md#software-bill-of-materials-sbom) for why linux/arm64 is not scanned separately." echo - echo "**NOTICE:** third-party license attribution for the Go module dependencies compiled into these images, attached below. Does not cover base-image OS packages or the Node.js/tmux layers built from source — see [releases.md](https://github.com/${{ github.repository }}/blob/${RELEASE_LINE}/src/docs/releases.md#third-party-notices) for the exact boundary." + echo "**NOTICE:** third-party license attribution for the Go module dependencies compiled into these images, attached below. Does not cover base-image OS packages or the Node.js/tmux layers built from source — see [releases.md](https://github.com/${{ github.repository }}/blob/v5/src/docs/releases.md#third-party-notices) for the exact boundary." } >> "$notes_file" gh release create "v${VERSION}" \ --repo "${{ github.repository }}" \ diff --git a/AGENTS.md b/AGENTS.md index 04b51dc66b..40acf5c113 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,16 +4,17 @@ These rules apply to every AI agent (hive agents, Copilot CLI, Claude Code, Code ## Testing: CI runs the tests, you do not -- **Do not run `go test`, `go build ./...`, `go vet`, `golangci-lint`, or the docs/citation guards locally.** Commit, push, open the PR, and read the CI results (`gh pr checks `, then the failing job log). CI runs the full matrix with the right toolchain, caches and coverage gates; a local run duplicates it and burns tokens and pod CPU/disk. Inside the hive pod, `go test` and `go vet` are blocked for agents by the Go shim; use CI for the verdict. -- If CI fails, fix from the job log and push again. Do not "reproduce locally first". The hive opens requested PRs; CI is the sole verdict and records failures for agents to iterate on. +- **Do not run `go test`, `go build ./...`, `go vet`, `golangci-lint`, or the docs/citation guards locally.** Commit, push, open the PR and read `gh pr checks ` plus the failing job log. If CI fails, fix from the log and push again; do not "reproduce locally first". CI is the sole verdict. - The only local check worth running is `gofmt -l` on files you changed. -- `src/` is a two-module Go workspace (`src/go.work`): the root module and the Crux agent runtime at `src/crux/` (`github.com/hivecommons/hive/crux`, packages `crux`, `crux/agent`, `crux/inference`, …). From `src/`, `./...` is the root module only; the Crux module is `./crux/...`. CI covers both; see [src/docs/design/crux.md](src/docs/design/crux.md). -- **Never run this repository's test suite from inside an agent pane.** Parts of `crux/agent` and `pkg/dashboard` exercise real process management (tmux, `/proc` sweeps, SIGKILL by uid). Run as an agent user they can kill the agent's own tmux server, CLI and terminal — this is how the scanner lost its session repeatedly (hivecommons/hive#9416). +- **Never run this repository's test suite from inside an agent pane.** Parts of it manage real processes and can kill your own session. ## Working style - Keep changes surgical and PR-sized; one concern per PR. -- Every PR with a user-visible `src/` code change needs a `changelog.d/-.md` fragment (`added|changed|deprecated|fixed|security`) whose body is a single `- ` bullet. Changes outside `src/` (root-level docs, `changelog.d/`, `.github/`), plus `src/docs/`, `*_test.go` files, and `src/{deploy,scripts}/test[-_]*.sh` scripts, are exempt automatically (`src/scripts/check-changelog-fragment.sh` is the source of truth for the exact set); other test-adjacent changes (e.g., `testdata/` fixtures, non-`_test.go` test helpers) and non-user-visible `src/` code changes (refactors, dependency bumps) need the `no-changelog` label instead. `changelog.d/` is at the repository root, not under `src/` — `src/changelog.d/` is never compiled and the guard rejects it. -- Sign commits (`git commit -s`); PR titles start with an emoji (`✨` feature, `🐛` fix, `📖` docs, `📝` proposal, `🌱` chore, `⚠️` breaking) — `📝` is for proposals only; a docs PR is `📖 docs: …`. -- Do not hand-edit `src/docs` file:line citations (including `src/docs/api-reference.md` and `src/docs/api-reference/*.md`); when CI's citation guard reports drift, run `python3 src/scripts/check-docs-citations.py --fix` first — it runs `check-api-reference-citations.sh --fix` for `api-reference.md` and re-anchors other `.go` citations by their backticked Go declaration anchor. Only fall back to a manual edit for citations it still reports as `DRIFT`/`UNRESOLVED`, and run it only when CI tells you citations drifted. The required `changelog-fragment-guard` check runs it (non-fix) when a PR edits a hub or dashboard `server.go` or their `static/` pages, so the PR that causes drift goes red. -- A PR that edits anything under `src/scripts/` must re-pin `TRUSTED_SCRIPTS_TREE` in `.github/scripts/integration-governance.cjs` to `git rev-parse HEAD:src/scripts` (of the post-merge tree); otherwise `build-and-test` fails. +- Sign commits (`git commit -s`); PR titles start with an emoji (`✨` feature, `🐛` fix, `📖` docs, `📝` proposal, `🌱` chore, `⚠️` breaking); `📝` is for proposals only. +- Every PR with a user-visible `src/` code change needs a `changelog.d/-.md` fragment at the repository root whose body is a single `- ` bullet. +- Do not hand-edit `src/docs` file:line citations; when CI's citation guard reports drift, run `python3 src/scripts/check-docs-citations.py --fix`. + +## Project knowledge is scoped, not global + +This file is tone and working style only. Repository facts (module layout, CI guards, exact changelog exemptions, gotchas) each live in one entry under [src/docs/knowledge/](src/docs/knowledge/) with a `scope:` block naming the paths, labels and lanes it applies to. Hive injects matching entries into a kick; from a plain checkout, read the entries whose `scope.paths` match the files you are about to touch. Format: [src/docs/knowledge-entries.md](src/docs/knowledge-entries.md); injection: `src/docs/agent-knowledge-and-memory.md`. diff --git a/CHANGELOG.md b/CHANGELOG.md index 4f5972d60b..9585396fb1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,1457 @@ Hive did not historically maintain a complete changelog. This file starts a prag ## Unreleased +## 2026-11-07 (v5.189.0) + +### Added + +- An agent whose `knowledge.agent_scopes..include_states` lists `draft` is now primed with the draft knowledge entries it authored (`author:`/`owner:` frontmatter matching the agent, its base agent or a hive owner login), each marked `(draft)` in the kick; every other kick stays approved-only ([#17076](https://github.com/hivecommons/hive/issues/17076)). + +### Fixed + +- `docs/crux-serve.md` and `docs/env-vars.md` now document `crux serve --runs-config` / `CRUX_RUNS_CONFIG` and the `/v1/runs` routes, and the work-services design doc reflects that S2 and S7 shipped (#17027, #17028). +- A claim's GitHub side effect (label, stage or ledger write) that kept timing out after its bounded retries logged `issue-claims: GitHub side effect failed` with no matching class, so the hive filed it as `unclassified_error_repeated`. It now lands under its own `issue_claim_effect_failed` class, with the underlying error still in the log line (hivecommons/hive#17069). + +## 2026-11-07 (v5.188.0) + +### Added + +- New `agents.cli_memory` block (per-agent `cli_memory:` override): `auto_memory` (default false) pins Claude Code / Codex / Copilot CLI auto-memory off via `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1`, `[features] memories = false` and `"memory": false`; `clear_on_kick` wipes that agent's `~/.claude/projects/*/memory`, `$CODEX_HOME/memories*` and `~/.gemini/GEMINI.md` before each non-resume kick (hivecommons/hive#17032). +- Mid-task knowledge advisor (opt-in `knowledge.advisor`, default off): when a running agent's work enters a scope that was not on screen at kick time, the matching knowledge entries the kick did not already carry are typed into its session as one `📚 Knowledge:` line each, capped per kick (`knowledge.advisor_max_per_kick`), never during a tool call, with per-agent opt-out (`knowledge.advisor_exclude_agents`) and a `knowledge-advisor` prompt-history trigger for measurement (#17052) +- Knowledge entries can carry a `scope:` frontmatter block (`paths`, `labels`, `lanes`); the kick primer surfaces a scoped entry only when the kick's lane, issue labels or known file paths match, so repository facts are injected on demand instead of on every kick (#17045). + +### Changed + +- Review backlog: findings below the new `review.backlog.min_severity` (default `P2`) are no longer filed as issues but collected in one upserted `hive:review-followups` comment on the PR; the issue cap `review.backlog.max_per_pr` (default 3) now applies over the PR's lifetime instead of per day (`max_per_pr_per_day` is a retired alias); and new findings sharing a perspective are filed as one checklist item. Set `min_severity: P3` to file every finding as before (hivecommons/hive#17065). + +### Fixed + +- Hosted spokes now inject the primary repo's `AGENTS.md` into kicks: when neither `project.checkouts_dir` nor a matching `policies.local_dir` names a local checkout, the scheduler fetches `AGENTS.md` from the repo's default branch through the hive's GitHub client (15-minute cache, last-known-good on API failure, same injection cap) and materialises it under `/data/agentsmd-cache///` so the log shows `agentsmd: injecting repo instructions into kick` with that root ([#17090](https://github.com/hivecommons/hive/issues/17090)). +- Tagged Release no longer stands down when `v5` advances past the commit `docker.yml` built. The version tag now names the release commit parented on that built SHA (the retagged images' exact tree plus the changelog), the release lands on `v5` as a merge commit even when the tip has moved, and the hourly backstop releases the newest built ancestor of the tip instead of requiring the tip itself; `docker.yml` push builds also get their own concurrency slot so a merge burst no longer cancels them. Under merges faster than a multi-arch build the old "defer to the successor" rule had no terminating condition and left `v5` untagged from `v5.186.4` (2026-10-18) onward. + +## 2026-11-07 (v5.187.0) + +### Added + +- `governor.labels.stage.engine.mode` (`off` / `shadow` / `enforce`, default `shadow`; Settings → Labels) switches the ADR-0025 central stage engine at runtime ([#13010](https://github.com/hivecommons/hive/issues/13010), part of [#12999](https://github.com/hivecommons/hive/issues/12999)): one reconciler is shared by the issue and PR sweeps, `off` is legacy pass-through, `shadow` counts every legacy/engine disagreement, `enforce` lets the engine write. `/api/status.stageEngine`, the activity tracker's status strip and the `hive_stage_*` series on `/metrics` report mode, derivations, mismatches and anomalies; the shadow → enforce rollout runbook is in `operator-reference.md`. +- Sidebar x/y count pills for Overview and Governor (#13148) +- `hivectl hives`, the TUI's Hives pane and the Commons web UI (`hivectl hives web`) now commit `profiles.yml` under a shared cross-process lock (`profiles.yml.lock`, mode 0600) and only if the file is still the revision they loaded. An edit made from one surface while another changed the hives is refused with nothing written — the CLI/TUI ask you to re-run, the web UI returns 409 "requires renewed review" — instead of one writer silently overwriting the other. ([#13179](https://github.com/hivecommons/hive/issues/13179)) +- Contributor relays now publish local scope adoption, subscription readiness, and draining task status for truthful contribution UI acknowledgements ([#13290](https://github.com/hivecommons/hive/issues/13290)). +- A `blocked` issue whose body carries `` (and no blocked-on PR) is now listed as `blocked until `, the activity monitor's blocked chip shows `re-check at `, and once the deadline passes the blocked sweep lifts `blocked` with one `deadline passed; re-triaging` note so the scanner re-triages it; issues that also carry `` stay blocked (#13310). +- `crux/api` gains a Go client (`api.NewClient`) for `crux serve`: every verb, SSE log following and the runtime event stream, over a unix socket or TCP with a bearer token (#13536). +- The `crux` CLI gains a remote mode: `--server ADDR` (or `CRUX_SERVER`) with `--token` (or `CRUX_TOKEN`) makes `run`, `ps`, `logs`, `kick` and `stop` drive a `crux serve` over the API instead of an in-process runtime; `logs -f` follows the agent's output (#13536). +- `crux serve` exposes the agent runtime over a local HTTP+JSON API (Crux Stage 3, [#13536](https://github.com/hivecommons/hive/issues/13536)): a unix socket (`$CRUX_SOCKET`, default `$XDG_RUNTIME_DIR/crux/crux.sock`, created 0600) and optionally TCP with `--listen`, which is refused without a bearer token (`--token` / `$CRUX_TOKEN`). The routes under `/v1` mirror the CLI verbs — list, get, run from a definition, logs (pane, buffer, full, or followed as SSE), kick, stop — plus an SSE event stream of starts, stops, kicks and observed state changes. The wire contract is the stdlib-only `crux/api`; the server is `crux/serve`. +- Review heads now end in one agreed verdict ([#13542](https://github.com/hivecommons/hive/issues/13542), part 2). Once every head has answered every perspective, the base reviewer gets one decision kick per PR carrying every head's full report. It checks each head finding against the code, gives it a disposition (confirmed, not reproducible or out of scope) with a reason, sets the final severity of each confirmed finding, records one decided verdict per perspective, and posts the PR's only review comment, tagging findings with the heads that raised them. Routing (`severity.block_at`, backlog filing, fix kicks, human holds) runs on the decided reports; the heads' raw reports never route on their own. When every head approved with no findings, no decision session runs and, with `acknowledge_no_findings` on, the hive posts a single acknowledgement. `review.head_max_retries` is now enforced per head: a head that never answers is named in the decision and the comment instead of stalling the PR, unless no head answered, where `max_redispatch` applies as before. `/api/reviewer/accuracy` adds `review_heads`, scoring each review model's head reports against the decision. +- `agents..review_heads` lets the review swarm judge every perspective with several models independently ([#13542](https://github.com/hivecommons/hive/issues/13542), part 1). Each head (`{backend, model, alias, replicas}`) is materialized like `replicas` as `--` agents that copy the base reviewer with their own backend and model, are stripped on save and provisioned at boot by the entrypoint; `review.reviewer_agents` naming the base admits them. With `combined_perspectives: false` each perspective is dispatched once per head to that head's least-loaded replica, as a blind, record-only kick (`hive-review --record-verdict`, nothing posted on the PR), and the relay keeps one verdict per perspective per head. A decision step reconciles the heads into one verdict per perspective (see the part 2 entry); `review.head_max_retries` (Settings → Review gate) bounds per-head re-dispatch. Hives without `review_heads` dispatch exactly as before. +- The ACMM L2 pack now includes the `reviewer` agent in COMMENT-only mode (no fixer, no auto-merge) as the review-first entry point; review is part of L2 proper and no L2.5 level was added. L5/L6 reviewer behaviour is unchanged (#13574). +- Triage can now comment once on new RFC/feature issues with the existing settings that may already cover the request, each linked to Settings with the search pre-filled (`issues.rfc_existing_check.enabled`, default off; never labels or closes). Settings also accepts `#config/governor//` deep links that open with the search box filled in. +- `runs.triage.clarity_gate` (default off; `enabled`, `threshold` 0-100, default 60; Settings → Features → Incoming issue triage) scores each human-filed, unclaimed issue for goal, acceptance criteria, scope and detail before an agent is kicked on it. An issue under the threshold gets one `` comment with concise questions for its author and the `needs-spec` label (stage/045) instead of a claim, and a park label write that failed is retried on the next kick even across a hive restart; removing `needs-spec` resumes the normal pipeline ([#13577](https://github.com/hivecommons/hive/issues/13577)). +- The clarity gate (`runs.triage.clarity_gate`) now resumes a parked issue on its own: while the gate is on, a periodic sweep removes the hive's own `needs-spec` once the issue author, or a non-hive commenter with write/maintain/admin, replies after the gate's `` question, and records the un-park so the issue re-derives `stage/010-actionable`; a `needs-spec` a person added is never lifted ([#13588](https://github.com/hivecommons/hive/issues/13588)). +- Extend the FedRAMP Moderate and ISO 27001 Annex A profiles with more baseline controls (listed `not_covered` where Hive cannot evidence them) and rename the non-NIST `AC-2.ELIG` row to `ELIG-1` ([#13585](https://github.com/hivecommons/hive/issues/13585)). +- Show rolling 30-day issue reopen rates per repository and clarity-gate cohort in Evidence and Prometheus, with captured closure counts and explicit unknown/empty-cohort handling ([#13589](https://github.com/hivecommons/hive/issues/13589)). +- Automerge can require a PR head to contain the current base before merging: repos listed in `auto_merge.require_current_base` get a green-but-stale head updated and re-tested instead of merged untested against newer base commits. +- Automerge can merge the base forward into a trusted human PR that only conflicts because the base moved: repos listed in `auto_merge.merge_forward_trusted_human` get one App-authored, signed-off merge commit on the PR branch (no human commit rewritten); a real conflict pushes nothing and posts one note naming the files both sides changed ([#13636](https://github.com/hivecommons/hive/issues/13636)) +- Add a reusable offline index for tracked code identifiers, config keys, flags and documentation across registered checkouts, with bounded input, deterministic results and per-repository coverage errors; prior-art gate and issue-filing integration remain follow-up work after #13773 lands. +- The review swarm's outcome now shows on the PR, and its follow-up work is tied to the PR it came from ([#13833](https://github.com/hivecommons/hive/issues/13833)). The new `review.verdict_labels` block maps the current head's review state to one label each: `reviewing`, `approve`, `changes_requested`, `requires_human` (`reject` counts as `requires_human`). It works independently of the auto-merge engine's stage labels, so a hive with auto-merge off still shows "in progress / approved / changes requested / needs human" on every PR. Like `human_decision_label`, the labels are never created and never block. With `review_heads`, backlog items are now filed only from the decision step's reconciled findings, never from each head's raw report. That had produced near-duplicate items whose wording defeated the fingerprint check and spent the PR's daily cap. The items are also listed in a "Follow-ups filed" section of the decided review itself, on every head, rather than in a once-per-PR summary comment. Every review-backlog item, in every destination including Linear, is now parked on the PR it was filed from with the `blocked` label and the blocked-on marker, not only when the cited file is missing on the base branch. A new sweep lifts the block with a one-line note when the PR merges. When the PR closes unmerged it also lifts the block and comments "source PR #N closed unmerged — re-triage against current base", leaving the item open for normal triage: a closed PR is often superseded by one that lands the same lines, so backlog items are never closed or cancelled automatically. +- v5: the semantic prompt-injection classifier can run through the Claude CLI, launched with no tools, no MCP servers, no GitHub token and an empty working directory, on hives without a model endpoint: set `ioscan.classifier.backend: claude` (or pick it in Settings → Security → Input Defense). A CLI backend makes at most `ioscan.classifier.cli_budget_per_eval` calls per scheduler pass (default 8) and `ioscan.classifier.cli_daily_quota` calls per UTC day (default 500); backends that cannot run without tools (copilot, codex, gemini) are refused at boot. Port of [#14060](https://github.com/hivecommons/hive/pull/14060) and [#14070](https://github.com/hivecommons/hive/pull/14070) from v6 ([#14059](https://github.com/hivecommons/hive/issues/14059), part of [#14037](https://github.com/hivecommons/hive/issues/14037)). +- **`omnigent` contributor backend (T3 experimental).** Registered the Omnigent meta-harness CLI ([omnigent-ai/omnigent](https://github.com/omnigent-ai/omnigent), Apache-2.0) across `KNOWN_BACKENDS`, `CLIBackends`, local confinement matrix tests, and contributor preflights. Omnigent orchestrates Claude Code, Codex, Cursor, Pi, and custom agent harnesses; on the local CLI path it exposes no OS-level sandbox wired by Hive and requires explicit opt-in via `HIVE_OMNIGENT_DANGEROUSLY_RUN_UNCONFINED=1`. Every launch is `omnigent run --server local [--model ]` (`run` opens the agent REPL; `--server local` pins a local Omnigent server, so remote-server mode is unsupported), and container mode stages only `auth_tokens.json` and `config.yaml` from `~/.omnigent`, never session history. Omnigent's internal policy engine and sandboxing compose additively, while Hive's proxy remains strictly authoritative for all GitHub writes and push operations. +- The GitHub forge adapter implements `forge.Merger` and passes the shared merge contract (#14107): the hold gate refuses with `ErrHoldActive` and a head that is not the pinned commit with `ErrConflict`, both before the merge call; an already-merged change reports `ErrAlreadyMerged`, GitHub's 405/422 map to `ErrNotMergeable`, and `MergeOptions.DeleteBranch` removes the merged head branch. The merge delegates to `pkg/github.MergePR`, so it keeps the mutation boundary, forward-merge guard and merge audit. +- forge(gitlab): implement `Forge.Merge` for GitLab with strategy mapping, head-SHA guard, hold label enforcement, and 405/406/409 error mapping, verified by shared contract tests. +- Gitea and Forgejo merge implementation on the forge adapter (`POST /repos/{owner}/{repo}/pulls/{number}/merge`), with merge style mapping, head commit guard, and shared merge contract test coverage ([#14110](https://github.com/hivecommons/hive/issues/14110)). +- `project.repo_policies[].forge` and `forge_url` put one repo on GitLab or Gitea/Forgejo while the rest of the project stays on `project.forge` ([#14112](https://github.com/hivecommons/hive/issues/14112), part of [#14096](https://github.com/hivecommons/hive/issues/14096)). Both keys are validated at load. The governor's escalation writes go to each repo's own forge, and a repo-scoped kick carries the forge kind and names a non-GitHub forge in its text. Unset keys behave exactly as before. +- A merge requested through the hive-merge relay for a repo on GitLab or Gitea/Forgejo (`project.repo_policies[].forge`) now lands through that forge's merge API, after the same merge-eligible check pinned to the reviewed head. GitHub repos merge exactly as before. Authorship detection also recognises GitLab access-token bots and Gitea/Forgejo Actions as bots ([#14113](https://github.com/hivecommons/hive/issues/14113), part of [#14096](https://github.com/hivecommons/hive/issues/14096)). +- Projects cards on the dashboard now name their forge: each repo in `/api/status` carries `forge` (`github`, `gitlab` or `gitea`) and, for GitLab and Gitea/Forgejo, `forgeUrl`, so a hive with `project.forge: gitlab` or `gitea` shows its own host (for example `🦊 GitLab · gitlab.example.com`) and links to it instead of claiming github.com. A repo moved to another forge by `project.repo_policies[].forge` gets its own card label and links ([#14115](https://github.com/hivecommons/hive/issues/14115)). The new [Forges](src/docs/integrations/forges.md) page documents what the GitLab and Gitea/Forgejo adapters support today. +- Nightly Forgejo smoke workflow (`.github/workflows/forgejo-smoke.yml`) that starts a digest-pinned Forgejo container, seeds a repo, issue and pull request, and runs the minimal governor loop (read issue → kick → merge via `forge.Merger`) against it; also runs on pushes and PRs touching `src/pkg/forge/**` or `src/pkg/apiproxy/**` ([#14116](https://github.com/hivecommons/hive/issues/14116)). +- The Crux module ships its own `crux` binary, `src/crux/cmd/crux`, buildable from the nested module alone (`cd src/crux && make build`, or `GOWORK=off go build ./cmd/crux`) with the same `run`, `ps`, `logs`, `kick`, `stop` and `serve` verbs, `--server` / `CRUX_SERVER` remote mode and a `--version` flag. It loads agent definitions from plain YAML files with the new `crux/defs` package (`--defs ` / `CRUX_DEFS`: portable `kind: AgentDefinition` documents or bare per-agent overlays); the root `cmd/crux` stays as a thin host that reads `hive.yaml`. `src/crux/Makefile` adds `build`, `test`, `vet` and `smoke` (starts `crux serve` on a private socket and drives it over the API), which CI runs; `src/crux/README.md` documents the module ([#14138](https://github.com/hivecommons/hive/issues/14138)). +- `src/crux` is now published to `hivecommons/crux` as module `github.com/hivecommons/crux`: `.github/workflows/crux-sync.yml` runs `src/scripts/crux-publish.sh` on every v5 push touching `src/crux/**`, rewrites the module path, refuses to publish a tree that does not build with `GOWORK=off`, commits fast-forward on `hivecommons/crux` `main`, and turns a hive tag `crux/vX.Y.Z` into tag `vX.Y.Z` there so releases are cut from hive (#14138). +- **Dashboard activity monitor: blocked rows show their age in the since column too.** A blocked issue without `stage_since` now falls back to `created_at` there, matching the Open chevron (#14316). +- Hive Chat `/prs` now lists the actual open pull requests instead of a per-repo count: one row per PR under each repo (`owner/repo#N — title (@author · stage labels · age · ✅/❌/⏳ CI · approved/changes requested · needs decision · hold · mergeable)`), read from the status snapshot's cached PR rows — no extra GitHub call — and capped at 25 with an "… and N more" footer. The command remainder is now honoured as filters: `waiting on review`, `needs decision`, `hold`, `failing ci`, `mine` / `by `, `repo `, `stale` / `older than Nd`; unrecognised words are reported and the hint lists the filters. `/prs waiting on review` used to answer only "hivecommons/hive: 12 open PR(s)" (hivecommons/hive#14408). +- The ioscan semantic classifier can now run through Copilot CLI tool-less (`ioscan.classifier.backend: copilot`), alongside `claude`: copilot is launched with `--available-tools` set to a sentinel that names no tool, `--disable-builtin-mcps`, `--no-custom-instructions` and `--no-ask-user`, in an empty working directory with no hive token in its environment, and the prompt is passed as the `-p` value since copilot does not read stdin. When `classifier.backend` is empty and no model endpoint is configured, boot now falls back to the tool-less CLI the hive's own agents run on, so a Copilot-only hive at ACMM L5–L6 gets a classifier without extra configuration instead of silently withholding every kick that carries untrusted text. When the classifier is required at the current level but still cannot run, the dashboard shows a persistent `ioscan-classifier-blocked` alert saying kicks are being blocked and how to fix it (set an endpoint, set `ioscan.classifier.backend`, or `ioscan.classifier.fail_mode: open`); the fail-closed default is unchanged. `codex` and `gemini` remain refused (hivecommons/hive#14499). +- Every kick now opens with a **house style** section, identical across agents and backends: a managed repo's root `HIVE_STYLE.md` overrides the hive-wide `project.style` / `project.style_file`, which overrides the built-in text. Candidates are capped at `project.style_max_bytes` (4096); the repo file is untrusted and refused whole on an ioscan block with a `house_style_skip` audit line. Agent card and detail pane show a **style** field naming the source; `/api/status` exposes `agents[].styleSource` (#14582) +- **Weekly competitor and SWOT report to Discord `#related-research`.** A new GitHub Agentic Workflow, `.github/workflows/weekly-competitor-report.md` (compiled to `.lock.yml` with the pinned gh-aw `v0.89.21`, Copilot engine, `copilot-requests: write`), runs every Monday at 13:00 UTC and on manual dispatch. It researches projects adjacent to Hive (OpenHands, SWE-agent, Devin, Copilot coding agent, Codex, Claude Code, Sweep, Factory, Jules, Gastown, Dagger, Kilo, Cline/Roo, Mentat, Aider, GPT-Engineer, Potpie, Agentless, public fleet-orchestrator write-ups) with read-only GitHub tools and proxy-aware `curl` inside a network allowlist, then writes a 600-900 word plain-language report with "What changed this week", a "Who does what" table, a cited SWOT for Hive, and "One thing to watch". The report is appended as a comment to tracking issue [#14613](https://github.com/hivecommons/hive/issues/14613) and posted to Discord in 2000-character chunks through a custom safe-output job that reads the `DISCORD_RELATED_RESEARCH_WEBHOOK` repository secret. The workflow commits nothing and has no repository write permission ([#14612](https://github.com/hivecommons/hive/issues/14612)). +- **Docs: Hive trust levels vs GitHub Copilot assisted permissions.** New page `src/docs/copilot-permissions-comparison.md` explains Copilot's assisted permissions (GA 2026-10-26, from GitHub's changelog and docs) next to Hive's ACMM levels, lanes, policy proxy with measured refusal counts from the hosted hives, review gates, hold flow and record-only shadow gates, with a dimension table and what each does that the other does not. Linked from the docs index and documentation map (#14613). +- RFC lifecycle notices to Discord: with `notifications.discord.rfc_channel_id` set (env `HIVE_DISCORD_RFC_CHANNEL_ID`; default empty, off) and a bot token, the hive posts one line to that channel when an RFC issue in a managed repo is opened (`RFC opened: #N - <url> (by @author)`), closed (`RFC closed (completed|not planned): ...`), or taken off hold so it can be implemented (`RFC ready to implement (hold removed): ...`, on `hold` coming off an open RFC or a held RFC reaching `stage/010-actionable`, once per hold episode). An RFC is an issue with the `rfc` label or an `RFC`-prefixed title. The detector (`pkg/rfcnotify`) polls issues updated since its last pass and keeps per-issue records in `/data/rfc-notify.json`, so restarts never re-post and the first pass only records the baseline. Operators see each post in the audit log as `rfc-notify` (#14616). +- `review.delta_rereview` (default on), `review.delta_trivial_lines` (default 20) and `review.delta_max_age` (default 72h): a PR already judged at an earlier head is re-reviewed by its diff since that head, with the previous verdict and findings in the kick; an empty or trivial delta in files the previous verdict passed re-stamps that verdict onto the new head without a model call. Aggregates record `delta.previous_head` / `delta.trivial` so the cost dashboard can split delta reviews from full ones ([#14621](https://github.com/hivecommons/hive/issues/14621)). +- `review.bot_author_model` (default empty = off), `review.bot_authors` (default `dependabot[bot]`, `renovate[bot]`, `github-actions[bot]`, `*[bot]`; the hive's own App never matches) and `review.bot_author_full_review_paths` (default `.github/workflows/**`, `Dockerfile*`): reviews of PRs opened by other bots run on a configured cheaper model unless the PR touches a full-review path or its files could not be listed ([#14625](https://github.com/hivecommons/hive/issues/14625)). +- `python3 src/scripts/check-docs-citations.py --fix` now repairs drifted `src/docs` line-range citations into `.go` files instead of only delegating to the `api-reference.md` route fixer: it resolves the first backticked symbol anchor on the citing line to a single top-level Go declaration (`func X(`, `func (recv) X(`, `type X`, `const X`, `var X`) and rewrites the range to start at that declaration and end at the first line that covers every anchor. It fails closed — zero or several matching declarations, an anchor outside the declaration, a non-`.go` target, or a line without anchors leaves the citation untouched and still reported as `DRIFT` with a non-zero exit — and a second `--fix` run is a no-op. This ends the hand-typed docs PRs for moved functions (#14713). +- `GET /api/launch-cost/history` returns a persisted daily per-ref rollup (`share_usd`, `launches` per UTC day) of launch attribution, so cost per merged PR can be measured over 14+ days instead of the ~1-day `/api/launch-cost` window ([#14762](https://github.com/hivecommons/hive/issues/14762)). +- crux: detect Copilot assisted-approval denials as a blocked/approval_denied state with the judge's feedback (#14796) +- The dashboard's **▶ terminal** now works for agents with `sandbox.runtime: job` ([#14798](https://github.com/hivecommons/hive/issues/14798)). Those kicks run as a Kubernetes Job in another pod, so there was no tmux session to attach and the pane waited forever. For a job-runtime agent the link now opens a read-only viewer at `/terminal/job/<agent>` that streams the newest Job pod's log through the launcher's existing in-cluster client and `pods/log` RBAC: it follows the pod while the kick runs (waiting while it is `Pending`), prints the container exit code when it ends, and between kicks shows the last run's persisted sandbox transcript — which now ends with an `exit code: N` line — or a clear "no sandbox run yet" state. Podman-sandboxed and tmux agents are unchanged. +- A sandboxed reviewer can now post reviews ([#14986](https://github.com/hivecommons/hive/issues/14986)). Every sandbox kick (Podman or `sandbox.runtime: job`) gets a review spool at `.hive/review-requests` in its workspace, and `hive-review` inside the sandbox writes there via `HIVE_REVIEW_REQUEST_DIR`. The review relay picks spooled requests up through the same policy path as the pod-local drop box, attributing each one to the kick's agent from a hive-owned manifest under `<work_dir>/sandbox-review-spools`, never from the file's contents. Because the spool is group-writable, each kick also gets its own random spool key (`HIVE_REVIEW_SPOOL_KEY`, passed only through the sandbox environment), and the relay accepts only requests that carry a valid HMAC under that key and haven't been accepted before, so another agent can't post a review as the sandboxed reviewer by dropping a file into its spool. A reviewer on an accelerator spoke can now run the change on the card node and post its verdict from there. +- Activity Monitor: the waiting-on pill carries a presence indicator for the person the hive waits on ([#15051](https://github.com/hivecommons/hive/issues/15051)) — a filled dot when their clanker is online (the hive waits), a filled square when it is offline (adoption is next; the tooltip says when: "@hanthor's clanker: offline 26h — hive will adopt at 15:10 (in 38m)"), a hollow ring when no clanker is registered ("waiting for a human reply"). Every PR row waiting on a named person (071 / 072 / 017) now carries `presence{login, state, kind, since, last_seen, next, adopt_at}` from the same hub lookup and clock adoption uses; the Needs-human popover and per-PR sub-rows show the same indicator. Shape, not colour alone, carries the state; nothing moves under `prefers-reduced-motion`. +- Review heads (`agents.<name>.review_heads`) now work with `review.combined_perspectives: true`: each head reviews every perspective in one record-only kick per PR head instead of one kick per perspective. A combined-mode reviewer set mixing lanes with and without heads still loads, with a boot warning that the plain lanes receive no combined perspectives. +- The hub's per-hive dropdown menu now has a **⏸ Pause hive** / **▶ Resume hive** item for the hive's owner (or a hub admin) ([#15092](https://github.com/hivecommons/hive/issues/15092)). It drives the same fleet breaker as the spoke's own top-bar ⏸ button: `POST /api/saas/hives/{id}/breaker` queues the request and the spoke applies it on its next heartbeat, so a spoke can be paused without opening its dashboard. +- Activity Monitor: **Accept triage** now heads the "⋯" row menu of every issue waiting on a maintainer's triage — stage 015, the `needs-triage` pill, and the label-less 000-new row the reporter-trust gate holds before the first stage pass (previously only Hold / Re-evaluate / Mark needs-human were offered there). The hint reads *"adds `triage/accepted` as @you; the hive takes it on its next pass (≈N min)"*, the result toast carries the governor's next scanner pass, and the row reads accepted at once (015 → 010 actionable; a 000-new row flips to *triage ✓ → actionable (next)*), which the server narrates the same way once the label is on. Same audited, permission-gated write path as before ([#15215](https://github.com/hivecommons/hive/issues/15215)). +- Hive PRs that touch `src/crux/**` now run crux's Go file-size ratchet (the `crux-file-size-ratchet` check), using the script and baseline fetched from crux `main` at run time. A PR that grows a grandfathered `src/crux` file past its baseline now fails in hive with crux's own `::error::` annotation instead of breaking crux `main` on the next sync. (#15331) +- The dashboard's RUNNING tile now rotates its fleet spend through `$X this hour` → `$Y today` → `$Z this week` → `$W this month` (~4 s each, a quiet vertical crossfade of just the amount and window, agent count fixed, width reserved so the tile never wraps; pauses on hover and while the tab is hidden, instant under reduced motion, hover lists all four), and `/api/status.fleetRun` gains `dayUSD`, `weekUSD`, `monthUSD`, `windowsPriced` summed from the cost ledger over the UTC day, ISO week and calendar month (#15614). +- The activity monitor shows push progress on every PR row in the CI / Review column ([#15784](https://github.com/hivecommons/hive/issues/15784)): the stage record keeps `waiting_push_since` / `last_push_at` / `last_push_sha`, booked from the `pull_request` synchronize / `push` webhook re-read with the enumerate head change as fallback. A 071 / 072 pill ends with the wait's age ("waiting on 👤 @user to push · 38m", muted-amber past `dashboard.stage_tracker.waiting_push_stale_h`, default 4); once a push lands the chevron returns to the column's own word (the 👤 clears — the ball is back with the hive) and the gray pill names the push ("@user pushed abc1234 · 2m" linking to the commit, "adopted from @x's #N · pushed 2m ago" on adopted rows, "pushed abc1234 · 2m" on plain CI / Review rows) while CI / the re-review for that head still run; the hive line reads "push seen 2m ago → CI/re-review queued". +- The dashboard's upgrade animation now plays for every pod roll, not only self-upgrades ([#15788](https://github.com/hivecommons/hive/issues/15788)): the hub announces hub-managed rolls through the heartbeat (`upgrade_announce`), operators can announce theirs with `POST /api/upgrade/announce` (owner-only; one-liner in `dashboard-standalone-upgrades.md`), and a SIGTERM with no announce still publishes an SSE `upgrading` event with `phase: restarting` before the stream drops. The banner survives the reconnect, shows the new pod's boot phase from `/api/version.startupPhase`, and reads **Upgraded to `<sha>` ✓** or **Restarted ✓** by comparing build hash and process `startedAt`. Preview it any time with `?demo=upgrade` or Settings → Diagnostics → *Preview upgrade animation*. +- Stage tracker: the "pushed" pill on a CI / Review row now drops once the PR head moves past the pushed commit (hivecommons/hive#15797). +- The activity monitor's stage tracker names, on the PR sub-row drawn under an issue, the other listed open issues that PR also closes ([#15806](https://github.com/hivecommons/hive/issues/15806)): a gray "also closes #15503" pill beside the PR link (comma-separated, three numbers then "+N", every number linking to its issue; the hover names each issue's title) — the reciprocal of the "↳ #N · under #M" chip the other issues already show. The issue's `linked_prs[]` entry drawn here (`drawn_under` == the issue) gains `also_closes` (number, title, url). +- The Activity Monitor's ⚙ settings gain a "Toasts & timing" section: info and error toast durations (`dashboard.stage_tracker.toast_info_s` / `toast_error_s`, 3–120 s, saved per hive through `PUT /api/config/dashboard` and served in the `/api/stage-tracker` payload, with a localStorage fallback only when the write is refused) and the contributor lane's pre-merge soak (`auto_merge.contributor_lane.soak_minutes`), live without a restart ([#15813](https://github.com/hivecommons/hive/issues/15813)). +- The Hive activity monitor can now be popped out into its own browser window (⧉ on the card header, `?popout=1`, same sign-in, tracker-only layout for a second monitor, ⤶ Return to dashboard) or taken full screen (⛶ / the `f` key, Esc exits) ([#15829](https://github.com/hivecommons/hive/issues/15829)). +- Add experimental, opt-in Matrix Rain and Cascade displays at `?kiosk=1&view=matrix`, with pause, reduced-motion paging, source and freshness labels, and authorized line fetching; the normal tracker is unchanged (#15936, RFC #15862). +- Serve Matrix lines via authorized `GET /api/matrix/lines` and a content-free `code-lines` SSE nudge on `/api/events` (experimental, default off; [#15935](https://github.com/hivecommons/hive/issues/15935)). +- `ioscan.classifier.backend` now accepts `omp`, running the prompt-injection classifier through a tool-less omp CLI that authenticates via the omp auth broker. +- RFC notices in rich mode (`rfc_format: card` or `rfc_threads: true`) now announce open-decision count changes (at most one per RFC per 30 minutes), target and status changes, and an added `stage/045-needs-decision` or `needs-human` label into the RFC's thread. A retitle edits the card and renames the thread instead of posting. A same-author RFC with the same title within an hour gets no card, only one note in the first RFC's thread. Line mode is unchanged. +- Spokes can attach a bounded, read-only activity digest to their hub heartbeat, and the hub serves it per user and per hive on `GET /api/hub/activity` with ETag polling: 100 items by default under a hard 250-item server-side ceiling, private-repository items excluded unless the spoke opts in (always counted in totals), truncation and stale, not-reporting or missing hives disclosed, and digests kept in hub memory only. Nothing populates the digest yet and no rollout or participation setting changes ([#15951](https://github.com/hivecommons/hive/issues/15951), RFC [#15861](https://github.com/hivecommons/hive/issues/15861)). +- Spokes now publish the bounded activity digest to the hub: each heartbeat carries it, built in process from the stage tracker, with up to `hub.activity.max_items` items (default 100, hub ceiling 250). When the cap applies, the most urgent items are kept and `truncated` reports how many were left out. Private-repository items are left out unless `hub.activity.share_private` is set, but totals still count them. Once the hub acknowledges an etag, later beats send only that etag. A tracker change sends an activity-only update on the heartbeat endpoint at most once every 15 seconds, and changes that arrive meanwhile are merged into it. `hub.activity.enabled` defaults on for hosted spokes and stays opt-in for self-hosted ones ([#15963](https://github.com/hivecommons/hive/issues/15963), RFC [#15861](https://github.com/hivecommons/hive/issues/15861)). +- The heartbeat `activity` block now carries the stage hops, opens and merges a spoke saw since the hub last acknowledged them (at most 200, oldest dropped first, drops disclosed as `events_dropped`), and `GET /api/hub/activity` serves them as `events` from a fleet-wide, memory-only ring of the last 1,000 events, filtered per user and per hive like items, so the hub board can animate movement and show merge toasts ([#15964](https://github.com/hivecommons/hive/issues/15964), RFC [#15861](https://github.com/hivecommons/hive/issues/15861)). +- The streamer can now run a second, independent broadcast for the hub-wide monitor on `twitch.tv/hivecommonsfleet` ([#15966](https://github.com/hivecommons/hive/issues/15966), part of [#15861](https://github.com/hivecommons/hive/issues/15861)): `src/deploy/stream/fleet/` is its own namespace, Deployment, stream-key Secret name and NetworkPolicy, ships disabled (`replicas: 0`, `STREAM_ENABLED: "false"`), and its `STREAM_PROFILE=public-safe` refuses to start the encoder without the owner's enable, the public-safe policy acknowledgement, a real public source and an installed key. It renders the hub anonymously — the auth proxy accepts no token and strips cookies — because Twitch output is public whatever the dashboard's authentication. The existing `twitch.tv/hivecommons` stream config is unchanged and pinned by a test; no broadcast is activated. +- The hub serves an anonymous **public-safe Fleet activity view** at `/activity/public`, backed by `GET /api/hub/activity/public` ([#15966](https://github.com/hivecommons/hive/issues/15966), part of [#15861](https://github.com/hivecommons/hive/issues/15861)). It is the source of the `twitch.tv/hivecommonsfleet` broadcast, and `src/deploy/stream/fleet` now points `DASHBOARD_PATH` at it. The view shows only public-repository items and events from hives the registry lists as public on github.com. It leaves out private or unknown-visibility rows, totals and drop counts that can include private items, hive owners and every per-user grant. It never reads a session or token, so a signed-in viewer's own Fleet access cannot leak onto a public stream. The signed-in `/activity` page is unchanged, and no broadcast is activated. +- Add the Ghost coder (`mx.effect=ghost`) and Terminal (`mx.effect=terminal`) effects to the opt-in Matrix display, plus an `mx.captions=off` toggle; both render only lines already served by `/api/matrix/lines` (#16041, RFC #15862). +- Add a Matrix tab to the Activity Monitor header, shown only when `dashboard.matrix.enabled` is set; the status payload gains an additive `matrixEnabled` boolean (#16042, RFC #15862). +- The hub has a read-only **Fleet activity** page at `/activity`, linked as **📡 Fleet activity** next to **🔬 Evidence**. It shows the open issues and PRs of the hives you can see, from `GET /api/hub/activity`, which scopes every hive to you server-side. It polls every 15 s with `If-None-Match` and redraws only when the ETag changes. A **Hive** column carries a colour chip that opens the hive's own tracker; rows link to GitHub, titles render as text, and there are no action menus. Group-by-hive draws a header per hive with its item count and freshness (`stale` after two missed heartbeats, "upgrade to report activity" for hives that send no activity, missing hives). A list above the board always names truncated items, dropped events and stale or missing hives. Rows use the shared tracker row asset, and the page is served with its own Content-Security-Policy (no inline scripts, handlers or styles). Display mode follows separately ([#16063](https://github.com/hivecommons/hive/issues/16063), part of [#15965](https://github.com/hivecommons/hive/issues/15965), RFC [#15861](https://github.com/hivecommons/hive/issues/15861)). +- The hub **Fleet activity** page (`/activity`) takes the spoke Activity Monitor's display parameters, read by the spoke's own code: `?kiosk=1` hides the chrome and cursor for an unattended screen, `?display=1` gives an attended chrome-less wall view that **Esc** or **d** leaves, `am.*` describes the board's view with the spoke's keys (kind, repo, q, author, sort, dir and `am.group=none`), and in display mode `am.view` + `interval` rotate `hub-activity` views with the spoke's wall-clock dwell. `am.*` keys the activity digest has no data for stay in the URL and are named on the board as not applied. A copy of the spoke's URL-view and playlist helpers is served byte-identical from `/activity/assets/` (`pkg/webassets/trackerview`), and a compatibility test fails if it drifts. The spoke tracker's display mode is unchanged ([#16064](https://github.com/hivecommons/hive/issues/16064), part of [#15965](https://github.com/hivecommons/hive/issues/15965), RFC [#15861](https://github.com/hivecommons/hive/issues/15861)). +- Every `?kiosk=1` view — the spoke Activity Monitor, the Matrix view and the hub's public Fleet activity page, i.e. the three Twitch streams — shows a small "Request a Hive" call-to-action pill bottom-right with `hive.hivecommons.dev/get-started` and a QR code of it ([#16236](https://github.com/hivecommons/hive/issues/16236)). It never appears in the operator dashboard, `&cta=off` removes it, and the text is `dashboard.kiosk_cta_url` / `dashboard.kiosk_cta_text` on a spoke or `HIVE_HUB_KIOSK_CTA_URL` / `HIVE_HUB_KIOSK_CTA_TEXT` on the hub. `src/scripts/twitch-channel-cta.sh` sets the matching title, category and tags on the channels (`--dry-run`, idempotent, per-channel `channel:manage:broadcast` token). +- The *Let hive decide* dialog, the tracker payload (`sentinel_details`), `/api/sentinel` (`findings`) and the hive's "reviewed, intended" decision comment now name the files and the sentinel rule that fired — bounded to 10 paths per finding with a "+N more" count — instead of only "changes N sensitive path(s)" ([#16237](https://github.com/hivecommons/hive/issues/16237)). +- The Hive activity monitor's header now carries its own live item count pill next to the title — the sidebar badge's twin, written by the same render call with the same ↑ +N / ↓ −N cue and `prefers-reduced-motion` handling — so kiosk (`?kiosk=1`), pop-out (`?popout=1`), display mode (`?display=1`) and browser full screen, which all hide the sidebar, still show how many items the monitor is tracking. The pill is enlarged in the chrome-less views so it reads at 1920×1080 ([#16243](https://github.com/hivecommons/hive/issues/16243)). +- Added `github.notifications.shadow` (default off): would-notify instrumentation that classifies every notification-capable GitHub write by producer and class, counts repeats it would suppress, exports the counters on `/metrics`, and documents the write-site inventory — measurement only, no write changes (#16264). +- Per-recipient attention budget (`github.attention.recipient_budget`, `0` = off) with shadow would-overflow counting and an opt-in, edited-in-place digest (`github.attention.digest_recipients`); security, required-review, protocol-command and hold notices are never budgeted ([#16271](https://github.com/hivecommons/hive/issues/16271)). +- Neutralise incidental `@user` mentions in copied text inside hive-authored status comments, so copying a title or quote no longer re-notifies the person named. +- With `github.notifications.attention_pilot` on, each item's `hive:status` card gains an **Attention** section (who owes what, since when, snoozed until), each repository gets one `Hive attention queue` tracking issue that is created once and then edited in place, and unresolved attention episodes get at most one reminder per `github.attention.reminder_interval` (default 24h), skipped while acknowledged or snoozed and after the recipient comments, reviews or changes a label; closing an item resolves its episodes and clears it from both. +- Add an opt-in code activity reader at `?kiosk=1&view=reader`. It shows pushed changes from `/api/matrix/lines` as readable, wrapping paragraph cards with green `+` additions and red `−` removals, with the repository, PR link, file, stage and observed time. It supports pause with P, Space or the button, pauses while you scroll, uses a static layout for reduced motion and stops in hidden tabs. The Matrix view is unchanged (#16475). +- Feed the Code activity reader whole pushed PR diff regions, including removals, through the existing authorized sentinel observer, with whole-region secret filtering, bounded memory-only history, policy reset, visible freshness, buffered-snapshot labels and explicit replay; stop restoring or writing the legacy Matrix code-history file. +- `/api/matrix/lines` now returns `more`, true only while another line the caller may see remains past the page, so clients paging a filtered backlog can stop without an empty follow-up request ([#16530](https://github.com/hivecommons/hive/issues/16530)). +- The hive re-authors its own fixer-exhausted PRs by itself instead of parking them for a person ([#16582](https://github.com/hivecommons/hive/issues/16582)): the exhausted hive PR is closed as superseded with a note, the issue is labelled `hive/re-authored` and requeued so the next kick opens a fresh PR from the current base (the kick asks for `Supersedes #<old>`). One automatic re-author per issue; a second exhaustion parks at 085 with Give direction / Hand it to a person / Close as not planned. The Activity Monitor words the issue `Re-authoring · superseding #N` (remediation evidence `kick`) and the fresh PR's chip `re-authored from #N`. `decide:re-author` is gone from the decision vocabulary: a person's rewrite of a contributor PR (unsigned DCO, exhausted) is `decide:adopt` — "Adopt as hive PR"; historical `re-author` ledger entries still read. +- Activity Monitor chevrons follow the canonical spec ([#16599](https://github.com/hivecommons/hive/issues/16599)): a row always has 1–2 **active** chevrons (amber fill + counted caption) — the item's stage column, plus a CI/Review track only while it genuinely runs on the current head; every other chevron is an **icon only** (neutral not-yet-run, red failed/changes requested, green passed/approved) with its counts and the backend sentence in the tooltip. CI and Review icons are a tiny ring segmented into `checks_total` / `perspectives_total` steps that fills clockwise (pass green, fail red, newest step pulsing while running). When nothing moves the blocker column is filled in a still stalled style, e.g. `CI 1/11 · waiting on workflow approval` for heads whose workflow runs are `action_required` on GitHub (new `PRCIActivity.WorkflowApproval`, blocker `workflow-approval-required:N`). Review-pending rows never read `Review unknown` / a default `5/5`: with no verdict bundle on the head they are `Review N/5 · in progress` (N = verdicts actually posted) or `· adjudicating`. +- Expose conflict-aware merge train, rebase-attempt and stall-warning controls under Settings → Auto-merge → Merge train, including disabling stall warnings with zero seconds ([#16677](https://github.com/hivecommons/hive/issues/16677)). +- Carry contributor abandoned PR counts through spoke heartbeats and task-status pushes into the hub's merged leaderboard, treating older spokes as zero ([#15799](https://github.com/hivecommons/hive/issues/15799)). +- Show abandoned PR counts in the dashboard and contribute landing leaderboards without changing contributor rankings ([#15796](https://github.com/hivecommons/hive/issues/15796)). +- **Activity Monitor display controls.** In display mode (`?display=1`), moving the pointer or tabbing reveals an overlay with separate **Exit display**, **Copy link**, **Full screen** and **Keep awake** controls that hides after 3 s idle. Full screen and the screen wake lock are requested only when you click their control, never on load; unsupported and denied states render disabled or with the browser's reason and are never retried automatically. The copied link carries only `display=1`, the `am.*` view and `theme` — never a token. Nothing is persisted, and kiosk mode is unchanged ([#15929](https://github.com/hivecommons/hive/issues/15929)). +- **Activity Monitor display playlists.** A display-mode URL can rotate between views: repeat `am.view=<url-encoded am.* query>` and set `interval=Ns|Nm` (10 s–1 h, default 60 s), e.g. `?display=1&am.view=am.needsHuman%3D1&am.view=am.kind%3Dpr&interval=2m`. Invalid views are skipped and fewer than two means no rotation. The current view follows the wall clock, so it survives reloads and reconnects; rotation is in memory only (no navigation, refetch or local storage), with a thin progress bar or a static "next in Ns" label under reduced motion. Playlists live only in the URL — no `hive.yaml` presets — and kiosk mode is unchanged ([#15932](https://github.com/hivecommons/hive/issues/15932)). +- Activity Monitor display mode (`?display=1`) now says when its data is stale ([#15930](https://github.com/hivecommons/hive/issues/15930), part of [#15860](https://github.com/hivecommons/hive/issues/15860)). A wall screen used to keep showing its last payload as if it were live after the event stream or the spoke went quiet. Now the display header shows the hive id, a clock and a live dot. When the stream has been silent for more than two poll intervals, or the payload is older than two cache TTLs, the dot turns amber, the board dims and a banner reads *Stale: last update N ago*. The display recovers by itself when updates resume. After five failed reconnects it reloads on a 30 s → 10 min backoff, and it reloads once after an upgrade finishes. The URL, and so the view, survives the reload. The ordinary Activity Monitor and headless `?kiosk=1` output are unchanged. +- Activity Monitor display mode (`?display=1`) gains wall-screen options ([#15931](https://github.com/hivecommons/hive/issues/15931), part of [#15860](https://github.com/hivecommons/hive/issues/15860)). `density=tv` uses larger type and shows only each row's stage, title and actor. It shows only the rows that fit the screen, with a "+N more" footer instead of the pager. `shift=1` moves the board 1–2 px every 4 minutes to protect OLED screens from burn-in. With *reduce motion* on, a display plays no row movement and no shift. Both options are ignored without `display=1`, so the ordinary Activity Monitor and `?kiosk=1` render exactly as before. The TV layout adds nothing that changes state. +- Hive activity monitor label chips are ordered `stage/NNN-*` by number then every other label alphabetically, every label is reachable — the **+N more** indicator is now a button that opens an in-app *All labels* dialog (same order, counts, type-to-filter, the chips' own toggles and *Clear*; labels picked there join the visible row) — and a **🙋 Needs human** facet leads the row, counting distinct items carrying any label of the server's needs-human set (`/api/stage-tracker.needs_human_labels`, the same list as the Projects *Needs human* preset, which now also includes `stage/071-needs-author` and the reporter-trust `needs-triage` label). +- **The Hive activity monitor can play a short "bug zapper" when a pull request merges while the page is open** ([#13275](https://github.com/hivecommons/hive/issues/13275)). A speaker chip at the right end of the monitor's toolbar (🔇/🔊, off by default, remembered per browser under `hive.tracker.sound`) opts in; turning it on plays the zap once. The sound is synthesised in the browser with the Web Audio API — a third of a second of crackling noise swept down through a bandpass filter over a low thunk, peak gain 0.3 — so there is no audio asset and no request the dashboard's CSP would have to allow. It fires when a PR the tab was already showing turns merged between two tracker refreshes, once per PR, never on first load, never for issues or already-merged rows, at most two zaps per refresh, and never while the tab is hidden. To make "merged" distinguishable from "closed" (the tracker lists open work only), `GET /api/stage-tracker` now also carries `recently_merged` — the PRs whose `pr_merged` audit entry (sweep, queue, relay, or a human merge the PR poller observed) is under 30 minutes old. +- Activity Monitor: every row action now reports what actually happened in a result toast that stays until the row changes state (shared `result` payload on the decision, delegated-decision, accept-triage, hold, send-to-human and rescan endpoints), rows show an in-flight "acting…" cue from click to state change, each confirm dialog has a "Don't ask again for this action" box (reset from ⚙ → Confirmations) with the sentinel ⚠ line carried into the toast, the lit chevron turns while a hive agent is on the item and a one-line event line says what just happened, and a merge pins the row for a moment while an amber token rises into a new "Merged today" counter (toggle "Celebrate merges"). Requested by @clubanderson. +- `src/deploy/stream/`: a headless Twitch streamer image (Xvfb + Chromium + ffmpeg, published as `ghcr.io/hivecommons/hive-stream`) with Kustomize manifests that put the dashboard's Activity Monitor on an unattended 24/7 stream, plus a dashboard `?kiosk=1` display mode that hides the chrome, dialogs and every other section ([#15594](https://github.com/hivecommons/hive/issues/15594)). Guide: `src/docs/streaming-the-activity-monitor.md`. +- **Activity Monitor URL views and display mode.** Every Activity Monitor filter can now be described in `am.*` URL parameters (`am.kind`, `am.repo`, `am.q`, `am.labels`, `am.group`, …), so a link reproduces the same view in a fresh browser profile; a tab opened with `am.*` keeps its filter to itself and never overwrites the saved one. A new 📺 header button (or `?display=1`) turns the monitor into an attended wall view with no row actions, left with Esc or `d`; it never requests full screen or a wake lock, grants nothing, and `?kiosk=1` is unchanged ([#15924](https://github.com/hivecommons/hive/issues/15924), [#15925](https://github.com/hivecommons/hive/issues/15925)). +- Activity Monitor: a PR waiting on a contributor's clanker (stage 072/071) now offers **Adopt now — hive takes it over** (decision API `adopt` + `force: true`: forced supersede adoption bypassing presence, grace and `maintainer_policy`, marker `hive:adopted reason=operator-forced by=@login`) and **Reroute to another clanker** (decision API `reroute` + `to`: the follow-up work is dispatched to an online clanker's fix queue as a `fix-pr` interrupt, `hive:rerouted` note, `rerouted → @X` pill; falls back to Adopt now after `governor.reroute.pickup_timeout`, default 30m), in the row menu, the Needs-human popover and the delegated "Let hive decide" rules (hivecommons/hive#15038). +- `governor.labels.stage.adoption.maintainer_policy: adopt | ask | never` (default **adopt**) replaces the hard-coded "author maintains the repository; not adopting" rule: clanker PRs are adoptable on disconnect regardless of the owner's repo role (owner decision on [#14524](https://github.com/hivecommons/hive/pull/14524), a maintainer's `author/clanker` PR left 26h at 072 with its hive offline). `ask` parks a maintainer's PR for an owner — the activity monitor row reads "waiting on @author (maintainer, offline 26h) — adopt?" and offers **Adopt** (`decide:adopt` → decision API `adopt`, which sets `adoption/supersede`); `never` is the previous behaviour. Every nudged 072 PR row now carries `adoption{due, blocked_by, since, nudges, author_online, …}` and a plain-words caption/pill; Settings → Labels gets the three-way selector. +- ADR-0025 and implementation plan for a central stage engine: one `pkg/stageengine` reconciler derives every `stage/*` label for issues and PRs from GitHub truth each cycle, a single `StageWriter` performs all stage writes, relay/claim paths submit facts instead of labels, and unexpected transitions are asserted as anomalies rather than rejected. Docs only; rollout gated by `governor.labels.stage.engine.mode: shadow | enforce`. +- Agents: idle CLI sessions over an RSS (`agents.session_recycle.max_rss_mb`, default 1536 MiB) or age (`max_age`, default 6h) budget are recycled through the normal restart path, bounding the V8 heap growth that was OOM-killing the pod; the dashboard shows each agent's session RSS and age (#14842). +- **`/hive ack` and `/hive snooze <duration>` for attention episodes, plus the attention action contract** ([#16359](https://github.com/hivecommons/hive/issues/16359), part of [#16270](https://github.com/hivecommons/hive/issues/16270)). On a repository whose `github.attention.admitter` is this hive, the episode's responsible person or a maintainer (`write`/`maintain`/`admin`) can acknowledge an attention episode or pause its reminders (1m–30d) from a comment; the un-park sweep records who and when on the episode (`acked_by`, `snoozed_by`, `snoozed_until`), refreshes the attention status section and replies once. Anyone else is ignored and nothing is recorded. Acknowledgement is not approval: neither command changes a label, releases a security/merge/review hold or opens a merge gate. `attention.Event` / `attention.NewObservation` define the contract every attention event must satisfy — who, what changed and why now, requested action, evidence, what Hive tried, what happens next, and how to ack, snooze or resolve — and refuse incomplete events. See `src/docs/maintainer-commands.md` and `src/docs/notifications.md`. +- `github.notifications.attention_pilot` (default off) opts a hive in to the attention pilot ([#16358](https://github.com/hivecommons/hive/issues/16358), part of [#16270](https://github.com/hivecommons/hive/issues/16270)): routine issue notes — partial work, close/auto-close narration (merged fix, decomposed parent), reopened-after-merge, stage regressions, the covering-PR note and the blocker-settled note — fold into the issue's single `hive:status` card through the shared status writer, and a newly required action (confirming a merged fix) is still announced by exactly one notifying write. With the flag off nothing changes. +- The hive approves workflow runs GitHub holds behind "Approve and run workflows" once per PR head for trusted bots (`governor.ci.auto_approve_workflow_actors`, default dependabot and renovate), its own App and heads a person admitted from the dashboard (`governor.ci.auto_approve_workflows`, default on; needs App **Actions: Read and write**, or set it `false` to keep Actions: Read); counts are in `/api/status` `workflow_approvals`, and a missing `actions: write` permission shows `CI waiting · needs workflow approval on GitHub`. +- The contribution list now shows an **Auto** state for repositories that were turned on because you follow their Hive. Ticking "Accept all new repositories" (or pressing "Refresh membership") stages the new repositories as Auto for review, `hivectl hives preset refresh` marks them in `profiles.yml` (`auto:`), and turning one off under a followed Hive also excludes it so following does not add it back. +- Settings → Features → Auto-merge gains a "Merge only on current base" switch (`auto_merge.require_current_base_default`, **off** by default) and each row on the Repos tab a per-repo inherit / on / off override (`auto_merge.require_current_base` / `auto_merge.skip_current_base`); the repo card shows a `current-base` chip when the gate is on. A gated repo only merges a head that contains the current base tip — a green head whose base has moved is updated with GitHub update-branch and merges once CI is green on the new head, which would have stopped the stale-green merge that broke `v5` for every open PR for 20 minutes. Explicitly listed repos are strict; repos gated only by the default merge a head the App cannot update (fork without maintainer edits, branch protection) as tested, with one WARN per PR. The fleet default stays off while the gate soaks on hive's own hive ([#15335](https://github.com/hivecommons/hive/issues/15335)). +- Conflict-aware merge train in every automerge lane ([#15117](https://github.com/hivecommons/hive/issues/15117)): approved PRs to one base with overlapping changed files are grouped per sweep, one front merges at a time, siblings wait at stage/080 as `merge_gate.state=queued-behind` ("In merge train · 3rd of 4", never a human stage), and after the front merges the lane updates `behind` branches and asks the rebase-resolve hook for `dirty` ones (`auto_merge.merge_train.max_rebase_attempts`, default 2; past it: stage/085 "Needs human decision · rebase failed twice" with "Rebase, then merge as maintainer"). The Activity Monitor renders a train contiguously with a left rail and a `⛓ merge train · N PRs · front #X` header chip, and `/api/stage-tracker` items carry `merge_train{id,state,front,position,size,overlap_files,ahead}`. `auto_merge.merge_train.enabled` (default on) turns it off. +- A failed `check_run`, `check_suite` or `status` webhook now reacts within seconds instead of waiting for the next governor sweep: the head SHA is resolved to its open PR from the PR detail cache, recorded as a CI failure signal (`/api/status.ci_failure_signals`), and a hive-authored PR's owning agent is kicked at once with the check name and log URL while a contributor PR gets a targeted automerge/contributor-lane pass — gated by `governor.ci_failure_webhook_kick` (default on), repo/agent pauses and a per-head cooldown (`governor.ci_failure_kick_cooldown_s`, default 600). Agents still never watch or poll CI themselves. +- ClankeR contributors can select Apple MLX on `/contribute` and use dedicated `just` setup/serve/launch recipes for user-managed MLX-LM inference through Pi on supported Apple Silicon Macs, with loopback-only configuration, explicit streaming tool-call verification, fail-closed checks, and public integration/setup documentation. +- Add opt-in Cline CLI coding workers to Crux, Hive and the ClankeR contributor relay, with explicit provider/model selection, isolated API-key credentials, bounded turns, streaming results and cancellation; disposable Jobs use dedicated provider Secret references and Podman uses a scoped read-only selected-provider mount with per-run cleanup; unsupported tool policies and OAuth refresh sharing fail closed. +- Add an opt-in, per-repo single-admitter attention primitive with durable condition episodes, quiet recovery, and uncertain-POST reconciliation; existing quiet-mode writers and review/hold behavior remain unchanged. +- Add a shared contribution-tree staging layer with reviewed membership and exclusion diffs, shared-Hive effects, guarded Apply retries, and separate persistence, relay notification, and pending-adoption receipts. +- Add a credential-free shared contribution tree read model and read-only `hivectl hives tree` inspection of saved consent, with explicit legacy, exclusion, and incomplete-discovery status; persisted hub discovery integration follows separately. +- Each contributor profile now records the PRs the hive had to adopt from that contributor: `abandoned` (one per PR, deduped) plus `abandoned_prs` records `{repo, pr, adopted_into_pr, reason, at}` on `/api/contributors`, counted at in-place adoption, supersession onto `hive/adopt-<n>` and operator takeovers (Adopt now / `adoption/supersede`, reason `operator_takeover`); automatic adoptions carry `offline` or `unresponsive` ([#15782](https://github.com/hivecommons/hive/issues/15782)). +- Show abandoned PR counts and recent-adoption tooltips on Contributors cards, and expose historical totals and per-login counts in `/api/status.contributorPool`. +- Contributor lane approves `action_required` workflow runs once per head for a PR author the contributor registry admitted at a `require_tiers` tier when the lane stops at `required-check-missing:<ctx>` (fork heads included), posting one `hive:contributor-held-runs-approved` audit comment; toggle `auto_merge.contributor_lane.approve_held_runs_for_registry_trusted` (default on). Claim-marker, auto-promoted and association admissions, sentinel/exclude-labelled PRs and `.github/workflows/**` diffs are never approved for (#14519). +- Show online ClankeR contributor IDs vertically in the Contributors sidebar count pill's hover and keyboard-focus tooltip. +- The sidebar **Contributors** item now reads **online/total** (for example `3/12`), the same two-part pill Governor and Overview use, with the tooltip *N online · M registered (heartbeat within 15m)* ([#15651](https://github.com/hivecommons/hive/issues/15651)). *Online* is the stage tracker's own presence test — a registered contributor whose relay heartbeat landed within `governor.labels.stage.presence_window` — so the pill and *waiting on @name (offline 13m)* always agree. `/api/status.contributorPool` gains `online` and `presence_window`; `/api/contributors` rows gain `online`; the Contributors header shows the same figure and the card list sorts online contributors first with a green/grey presence dot. +- Cost section: the spend-over-time chart's default windows are wider and adjustable — hourly 24 h, daily 14 d (month/day labels once there are more than 7 bars), weekly 5 wk (one bar per week), monthly 5 mo (one bar per month) — with a −/+ stepper beside the range chips (hourly 6–72 by 6, daily 7–60 by 7, weekly 2–26, monthly 2–24; remembered per range). Spend-in-range and run-rate follow the stepped window. Each completed UTC day of cost snapshots is now folded into a per-day rollup kept ~2 years (`/api/cost` `daily_rollup`, `/data/cost-daily-rollup.json`) so weekly/monthly windows reach past the 30-day snapshot ring; bars with no recorded history draw hatched and the summary notes where history starts. +- The `crux` binary now exports its OpenTelemetry spans and new kick duration/outcome metrics (`crux.agent.kick.duration`, `crux.agent.kick.outcomes`, labelled only by agent role and outcome) over OTLP/HTTP when the standard `OTEL_EXPORTER_OTLP_*` environment names an endpoint; with none set nothing changes ([hivecommons/crux#19](https://github.com/hivecommons/crux/issues/19)). +- `crux agy-turn`: the headless agy turn subprocess is a `crux` subcommand, so a manager running under `crux serve` (which types its own executable into the pane) can drive agy agents the same way `hive agy-turn` does in-process. +- The crux callback API now records `crux.callback.request.duration` and `crux.callback.requests` metrics and a span per request, labelled by capability, status class and refusal code only; nothing is exported unless an OTel exporter is configured. +- crux: `serve` attaches a caller principal to every authenticated request (`serve.CallerFrom`): the control token is the operator (named by `--operator-name`/`CRUX_OPERATOR_NAME`), and lane project credentials are accepted as project principals on work-services routes only — agent RPCs still refuse them. Groundwork for the crux work services (hivecommons/crux#114 S0). +- crux: pinned checkout service (hivecommons/crux#114 S1): `POST/GET/DELETE /v1/checkouts` on `crux serve` (enabled by `--checkout-allow`/`CRUX_CHECKOUT_ALLOWLIST`) and `crux checkout add|rm|list` provision a git worktree pinned at a full 40-hex SHA from an allowlisted repository, owned by the caller principal, with a recorded TTL and a post-hoc size cap. Records live under `<workdir>/checkouts`; design notes in `docs/design/crux-work-services.md`. +- `crux` CLI (`src/cmd/crux`: `run`, `ps`, `logs`, `kick`, `stop`) that drives an agent through the `crux.Runtime` interface from a hive `AgentDefinition` or overlay file, with a control socket served by `crux run` so the observer commands act on the live runtime; shipped in the image and documented in `src/docs/crux-cli.md` ([#13536](https://github.com/hivecommons/hive/issues/13536)) +- crux: contained run service (`crux runs`) on top of the sandbox launcher (Podman + kubejob) with saved run state under `runstate/` and `/v1/runs` serve routes (RFC hivecommons/crux#114, S2 + S7 minimum). +- Design record `src/docs/design/crux.md` for the Crux agent-runtime boundary (RFC #13536) and an architecture ratchet test that fails when any package outside `pkg/agent/...` references more distinct `agent.<Symbol>` identifiers or invokes tmux from more files than its recorded baseline. +- Add opt-in, forge-neutral Crux durable event/work lanes backed by NATS JetStream, project-scoped API credentials, verified publish generations, replay, fenced leases, authorized audited expiration recovery, persistent fair retry rotation and reusable reserved delivery slots, with Hive participating through a read-only governor adapter. +- Crux stage 2 (#14138): `crux/api/callback` is the stdlib-only wire contract a sidecar runtime uses to call back into hive for scoped GitHub tokens, REST accounting, usage, canary/text scans, conditions, the Linear credential and PR creation (HTTP+JSON over a hive-served 0600 Unix socket, fail closed when hive is unreachable); `crux/hivecap` adapts it onto the ring's existing seams and `pkg/cruxhost` is the hive-side mount over hive's existing implementations. The runtime never holds the App private key. +- `crux serve --hive-callback ADDR` (default `$CRUX_HIVE_SOCKET`, token from `$CRUX_HIVE_TOKEN`) dials hive's capability endpoint and feeds the runtime's seams from it (Crux sidecar plan, stage 3): the manager's condition reporter, sandbox pull-request creator, Linear credential resolver and push-token minter, and the process-wide tool-approve text scanner, all through `crux/hivecap` so each fails closed when hive is unreachable. The endpoint's reachability is reported as `hive_callback` on `GET /v1/health` and as the `hive_callback_unavailable` condition on `GET /v1/events` (`hivecap.Watch`, `serve.Server.Conditions`). +- `crux serve` now exposes every `crux.Runtime` family over its API (Crux sidecar plan, stage 3): per-agent start/restart/pause/resume/restart-count, full `crux.Process` snapshots, async kick + validate + dispatch state, kick-log listing and reads, verbatim definitions (add/update/remove/reconcile), overrides and pins, mode sync/clear, fleet breaker/ACMM/relaunch/startup-queue/crash-restart/token-refresh/kick-log archive, Copilot and Claude credentials, the Resumer session routes (`409 resume_busy`, `410 resume_session_gone`, `422 resume_unsupported`), one supervision read per agent, backend auth, nudges, audit, trajectory views, restore seeds, a synchronous `POST /v1/authorize` (204 / 403, unknown action 400 — clients treat anything but 204 as a denial), and the watchdog seam (`/v1/watchdog/agents`, per-agent observe and conditions; `501 not_supported` on a runtime without one). `GET /v1/events` carries the `crux.Host` observer events (kick outcome, pause transition, relaunch, pause persist, prompt, sandbox audit, audit, condition) with typed `data` payloads, and the server can run the Background loops in-process (`Server.Background`; `GET /v1/health` lists them). `crux/api.RuntimeRoutes` is the method→route table the parity tests hold the interface to; `crux/cruxtest.Recorder` is a recording `crux.Runtime`/`crux.Host` fake for anything that drives a runtime without running one. +- `crux/api/client.Runtime` implements every `crux.Runtime` family over the `crux serve` API (Crux sidecar plan, stage 3): `crux/runtime.New` returns it in `CRUX_MODE=sidecar` (connecting to `$CRUX_SERVER` or the serve socket) instead of `ErrModeUnavailable`, and `NewWatchdogFleet` composes a watchdog fleet for it from the wire watchdog source plus the runtime's Lifecycle. Kick and Host observer events ride one reconnecting `/v1/events` stream; the Resumer sentinels (`ErrResumeBusy`, `ErrResumeSessionGone`, `ErrResumeUnsupported`) round-trip from the server's status codes; Authorizer refusals and transport failures fail closed. A parity test holds `crux.Runtime` and `api.RuntimeRoutes` to each other in both directions so a method cannot be added without a route. +- crux: the proxy lets an in-hive Spek publish its RFC and children — GitHub `POST …/issues/{n}/sub_issues` and `POST …/issues/{n}/dependencies/blocked_by` and Linear `issueRelationCreate`/`projectCreate`/`projectUpdate` are allowed at ISSUES_ONLY; a new `crux/spekmarker` package parses the `<!-- spek:publish … -->` marker and `issueshape.SpekPublished` exposes it as the "already specified" clarity-gate signal (spektacular#114). +- Crux stage 4: sidecar agents now get the same credentials as in-process ones. The hive callback gains `agent_mint` (`POST /v1/tokens/mint`) and `bob` (`GET /v1/bob/credential`) families; `crux serve` installs callback-backed `SetAppAuth` (tier-scoped App installation tokens minted by hive over `POST /v1/tokens` and written in place to the per-agent cache), `SetAgentMint`, and the Bob key resolvers, all failing closed (no credential) when hive is unreachable; `sidecarHost` carries every remaining credential setter. Tokens are never logged. +- Crux stage 4 failure semantics (#14138): hive supervises `crux serve` as a child (`CRUX_SUPERVISE=child|external`, `CRUX_BINARY`) with readiness checks and restart backoff; a lost runtime socket refuses kicks with `crux.ErrRuntimeUnavailable` (no replay), raises the `crux_runtime_unavailable` fleet-report condition, and surfaces as `crux_runtime` in hive's `/api/health`; `crux serve` `/v1/health` reports `started_at`/`uptime_seconds`. +- Crux sidecar runtimes (`CRUX_MODE=sidecar`, [#14138](https://github.com/hivecommons/hive/issues/14138) stage 4) now reach two more `crux.Host` setters over the hive callback endpoint: the manager's inference routes go to hive's proxy over `PUT`/`DELETE /v1/inference/routes/{agent}` (pushed by a non-blocking worker with retry and a one-minute resync, so a restarted hive relearns them) and sandbox branch pushes run through hive's journaling mutation boundary two-phase over `POST /v1/effects` / `POST /v1/effects/{id}/end` (an unreachable hive refuses the push; a denial is `effects.ErrDenied`; a sidecar that dies mid-push is journaled as abandoned after 15 minutes). `SetSpanStarter` is documented in-process-only. `api.HostSetters` is the disposition table (callback | event | route | config | in-process-only) for every `Host` setter and `crux/api/client`'s parity test fails when a setter is added without a row. In-process mode is unchanged. +- A sidecar Crux runtime now receives hive's host policy over the hive callback endpoint ([#14138](https://github.com/hivecommons/hive/issues/14138), stage 4): `GET /v1/policy` and `POST /v1/policy/repo-auto-merge` carry build info, the explain-mode default, the kick log source, configured gateway backends, per-repo auto-merge, dead-session recovery ownership and the `agent_sandbox` config, which `crux serve --hive-callback` polls and installs on the manager. In-process mode is unchanged; inference routes, the sandbox mutation boundary and the span starter are not carried yet. +- Crux stage 4: hive now serves the inference usage ledger to a sidecar runtime over the hive callback's `usage` capability (it was `not_configured`), so a proxy whose `Accounting`/`Usage`/`Canary` seams are the callback adapters records usage and REST traffic into hive's ledgers, refuses GitHub writes while hive is unreachable and resumes when it returns. +- Add opt-in, default-off `dashboard.matrix` config block with an explicit `owner/name` repo allowlist (#15928, part of #15862) +- "Let hive decide" on a parked issue now judges the way the owner would: a fleet self-report whose remedy is the spoke operator's (expired provider login, credentials, disk, network, App setup) gets one direction comment to the spoke owner — no `approved-direction`, no implementer, the park kept, and never the same direction twice; a hive-filed proposal is approved when it cites an incident or a fixed-one-at-a-time recurrence and declined for now (closed as not planned) when it cites neither; a hive-policy item's recommendation is a real sentence instead of "no special rule applies". +- **"Let hive decide": LLM step for non-mechanical cases.** With the new `decisions.delegate.llm.enabled` (default false), an item the owner-delegate rules leave at the reversible default is decided by one model turn that sees the item, its thread, sentinel findings, linked items and the owner's policy; its structured verdict is validated against the delegate's closed action set and goes through the same safety rails, and any error or invalid reply keeps the reversible default. +- Add `hivectl hives repos <hive> --deselect-current` to clear current repository consent while retaining exclusions, provenance, and future-follow policy, and `--follow-new-repos=false` to stop following without removing accepted repositories. +- Evidence cards: every panel now carries a server-computed letter grade (A+ … C-, or — for not enough data) and a one-sentence plain-English summary; dense stats and "what this does not show" move behind the ⓘ popover, and the CI gate card no longer breaks the type scale (#13204) +- Evidence "Outcome by author kind" card now records change failures per author kind: reverts (`reverted_14d`, from `reverted_by` links written when a merged PR's title or body names the original PR or commit — `Reverts #N`, `Revert "… (#N)"`, `This reverts commit <sha>` — via webhook, PR state or merged-PR backfill, with no new GitHub calls) and issue re-opens (`issue_reopened_14d`, stamped on the closing PR's bundle as `issue_reopens` when the claim ledger sees an issue it closed reopened within 14 days). `/api/evidence/summary` additively exposes `change_failures` and `change_failure_rate` = (reverts + re-opens) ÷ merged; the Outcome grade and plain summary include re-opens (#13241). +- Evidence outcome cards support explicit on/off control-window assignments with within-repository metrics and deltas withheld below 20 usable observations per arm; unassigned records remain separate. This is reporting groundwork only: dispatch scheduling and control collection are not yet enabled ([#13532](https://github.com/hivecommons/hive/issues/13532)). +- The hub Evidence card gains an **Issue opens : PR merges** panel: hive-filed issues (audit-log `agent_issue_created` / `hive_issue_created`) ÷ hive-merged PRs (merged by this hive, or agent-authored — the Outcome by author kind set) per repository and fleet-wide over the selected window, read against the governor's cadence band instead of a flat 1:1 — surge/busy expects ≤ 1 (drain), quiet/idle expects 1–2 (bounded scouting), unknown expects parity ±25% — with a trailing-7-day sparkline over a rolling 30 days that should regress toward 1:1. Shipped as `issue_opens_pr_merges` on `/api/evidence/summary` and `cards["opens-merges"]`; thresholds are named constants in `pkg/evidence/opens_merges.go` (`src/docs/review-evidence.md`). +- New `pkg/forgestate` per-repo GitHub state cache (Phase 1 of [#13373](https://github.com/hivecommons/hive/issues/13373), [#13374](https://github.com/hivecommons/hive/issues/13374)): one in-process snapshot of open issues and PRs per repo, kept current by an ETag-conditional slow reconcile (a failed reconcile, such as a 403, keeps the last good snapshot and marks it stale instead of showing zero counts), webhook patches that re-fetch only the named item and upsert monotonically by `updated_at`/head SHA (closed and merged items leave at once, out-of-order deliveries settle correctly, delivery ids are kept for audit), and write-through of the hive's own label, comment, merge, close and claim mutations. It also adds a `forgestate_drift` metric, a startup gate that waits for every repo's first reconcile, freshness-bounded read-through for irreversible actions, and a per-minute `search` bucket budget. It is configured under a new `forgestate:` block (`enabled: false` by default) and is not wired to any reader yet, so enabling it changes no behaviour until the follow-up migrations land. +- forgestate: the governor's reconcile cadence now falls back from `eval_interval_webhook_s` to `eval_interval_s` automatically when webhooks degrade (no deliveries while GitHub activity continued, or deliveries failing verification) and returns only after two consecutive healthy windows; one INFO line each way (`webhooks degraded; polling cadence restored` / `webhooks healthy; webhook cadence engaged`), `/api/status.webhooks.mode` (`webhook` | `polling`) with `since`, `mode_reason` and `healthy_windows`. New `src/docs/webhooks.md` documents polling cadence vs webhook patch vs reconcile, the #13373 accuracy guarantees, every cadence key with its default, and the fallback (#13381). +- OpenTelemetry spans and metrics for GitHub API spend and cache freshness ([#13380](https://github.com/hivecommons/hive/issues/13380), Phase 3 of [#13373](https://github.com/hivecommons/hive/issues/13373)): every GitHub REST/GraphQL call gets a `github.request` span (`github.endpoint`, `github.repo`, `hive.caller`, `hive.pacing_class`, `github.cache_hit`, `github.ratelimit.remaining`/`bucket`, `github.shed`), the governor eval cycle gains `governor.stage_labels`, `governor.kick` and `governor.automerge` spans, and an OTLP/HTTP metrics pipeline exports `github.requests{caller,endpoint,status}`, `github.ratelimit.remaining{bucket}`, `github.secondary_limit_hits`, `forgestate.staleness_s{repo}`, `forgestate.drift{repo,kind}` and `webhook.event_to_patch_ms`. ForgeState reconcile now stretches its interval (2×/4×/8× below 20%/10%/5% core quota). Everything rides the existing `otel.enabled` + `OTEL_EXPORTER_OTLP_ENDPOINT` switch and is off by default; see `operator-reference.md` § OpenTelemetry. +- `cmd/hive` boots against a sidecar `crux serve` when `CRUX_MODE=sidecar`: the sidecar client is wrapped so the Host observers (kick outcomes, pause transitions, relaunches, prompts, audits, conditions) are fed from the runtime's event stream, and hive serves its capabilities to the runtime over the hive callback endpoint (`$CRUX_HIVE_SOCKET`). The in-process path is unchanged and still the default. +- `hivectl hives hub add|list|show|remove` tracks hubs in a new optional `hubs:` key of `profiles.yml` and reads each hub's federation registry (`GET /api/hives`) to list its advertised Hives. `hub adopt` confirms and bulk-registers only missing Hives through the existing `hives add` path, `hub follow` stores a future-enrollment policy without changing current membership, and `hub refresh` reports additions/removals while retaining successful partial progress. No credentials are stored on hubs; redirects, error statuses and malformed registries report unavailability instead of empty results (#13174, #13175). +- Add the opt-in Claude Managed Agents self-hosted external backend prototype with relay capability gating, durable session reconciliation, and USD 25/day ledger metering. +- Hub My Hives: a dismissible "Your hive <name> is ready → Open your hive ↗" callout for owners explains that the hub only lists hives (the Guide, settings and GitHub App install live inside the hive), names any attention item that must be fixed there, and points at the row ⋯ menu; the hive-name link gains an ↗ glyph and tooltip and the ⋮ button a "Manage: permissions, pause, funding, delete…" hint. Dismissal is per user and hive in localStorage and re-arms when a new attention item appears. +- Auto-merge never merges a breaking-titled (`⚠️`/`⚠`) or `needs-owner-merge`-labelled PR: one shared `RequiresHumanMerge` predicate skips it in every lane and the merge train, the tracker parks it at 090 *Ready for human merge · human merge* ("breaking change — owner merges") with **Approve & merge as maintainer** as the lead action, and hive posts one writeback-gated comment saying it waits for a human. Configurable via `auto_merge.human_merge_title_prefixes` and `auto_merge.human_merge_labels`. +- Trusted integration candidates now compose real required CI jobs and bind read-only member-governance verification to signed exact-job receipts; execution remains opt-in and OFF by default, with protected-promotion qualification still required. +- Add independent default-OFF integration execution enrollment, versioned private candidate provenance and actual runner accounting, designated-executor authority, bounded preparation admission, and exact protected-prefix promotion guards without replacing normal review, trust, CI, hold, or native-queue authority. +- Add a default-disabled trusted integration-candidate materializer, create-only initial-dispatch ownership and isolated job-bound CI receipt workflows derived from read-only validation profiles; no execution controller, runtime activation or required CI/review replacement is enabled. +- Add default-off, explicitly scoped integration orchestration with durable change intents, separate candidate observations, workflow-job accounting, and bounded admission above the existing preparation and GitHub queue authorities. +- Add an isolated Integration-aware promotion protocol foundation with exact tested commit/tree and ordered-parent verification, journaled destination compare-and-swap, live-guard fencing and conservative ambiguous-result reconciliation; execution remains unwired and disabled, with producer, permissions and protection prerequisites documented. +- Every primed kick now logs one `knowledge: injected N bytes from M entries (skipped K for cap)` line with the primer cap and the sizes of the AGENTS.md and skills blocks, so the knowledge share of a kick is measurable next to `kick rendered` (#17049). +- **Tracker: "Let hive decide" for items parked at *Needs human decision*.** The *Decide…* submenu on a parked issue or PR row (and the selection bar's *Decide…* for a bulk run) now opens with **Let hive decide**: the hive makes the decision itself as the owner's delegate, under the owner's standing operating rules (`pkg/delegatedecision.PolicyText` — decisive, reversible, keep work moving; prefer contributor PRs over hive duplicates; approve small low-risk changes and trusted-author sentinel alerts with a "reviewed, intended" line; supersede offline contributors now; dedupe aggressively; secrets/PAT/org-permission items are owner-only; quarantine flaky tests; accept CI hygiene gates as ratchets and design proposals with explicit defaults; never auto-close review-backlog items), and records it exactly as a human decision is recorded — `/hive decision <text>` comment, park labels lifted, `triage/accepted`, queue approval on a released PR head — so the item leaves 085/045 without the owner. Every delegated comment carries `<!-- hive:delegated-decision by=<hive-id> policy=owner-delegate -->` and the Decisions log marks the row *delegated*, so delegated and human decisions can be told apart and counted. Rails: the delegate never merges, refuses items wearing `hold`, never grants membership/secrets/permissions (`needs-owner` + `hold` with the exact owner action instead), and only *recommends* on policy or scope changes to the hive itself (keeps 085). New endpoint `POST`/`GET /api/repos/{owner}/{repo}/items/{number}/decide-delegated`; new setting `decisions.delegate.enabled` (default true) with a per-repo override. This release's decider is rules-first (the mechanically decidable rules above; the reversible default otherwise) — the LLM-backed decider for the rest is a follow-up. +- Inline the linked Linear issue (title, state, description, recent comments; capped and marked untrusted) into review kicks whose scope contract is a Linear issue, read hive-side so reviewers need no Linear token. +- Recognise configured Linear issue identifiers as review scope contracts. +- **Activity Monitor Matrix: bounded, scrub-drop line source behind `dashboard.matrix`** (#15934, part of #15862). When `dashboard.matrix` is enabled with an allowlist, the sentinel's existing patch fetch now feeds an in-memory source of pushed lines — no new GitHub calls, nothing written to disk. Only hive-identified authors on public, allowlisted repos are admitted; secret-shaped and generated paths are skipped before parsing; any line that `logscrub` would change, that already carries a redaction marker, that looks high-entropy or exceeds 160 runes is dropped rather than masked. Ingest is non-blocking (a full 64-slot channel drops and counts), with dedup per PR, 200 lines per head, a 2,000-line backlog and a per-minute rate cap. Default off: with the flag off no observer is registered and nothing is retained. No HTTP surface yet; the endpoint follows in #15935. +- Document Matrix's separate `hivecommonsmatrix` channel and add an inactive, silent streamer overlay with isolated deployment identity and zero replicas (#15937). +- Merge-hotspot advisor (`governor.hotspot_*`): the merge train's own PR file lists and rebase conflicts now feed a per-file score of how often concurrent PRs collide on the same file. Files above `hotspot_min_prs` / `hotspot_min_overlaps` in a `hotspot_window_days` window are reported on `GET /api/hotspots` (`hivectl governor hotspots`, `/api/status.hotspots`); a code file of at least `hotspot_min_lines` with two or more top-level symbol groups gets one `refactor: <path> is a merge hotspot — split into <N> units` issue (labels `agent/ci-maintainer`, `kind/cleanup`) through the writeback gate, deduped by `<!-- hive:hotspot file=<path> -->` and refiled no sooner than `hotspot_refile_days` after close. Docs are only ever recommended for a by-section split, generated files point at their source, and the ci-maintainer prompt gains a "Merge Hotspots" section describing the mechanical, no-behaviour-change split. +- Activity Monitor: a merge-train member's chip reads its place in the queue in ordinal words — "Merge queued · 1st", "Merge queued · 2nd · ~4m" (never the `front` / `queued-behind` slugs; hover "2nd of 6 in the merge queue · behind #15253 · ETA ~4m") — with a countdown to its estimated auto-merge turn that survives poll re-renders, the same words whether or not a merge sweep is evaluating it (the sweep is the spinning glyph and a "Checking now…" hover line), a hover that names what the head waits on (soak left, CI, a maintainer) and the estimate's basis, a Merge queue popover listing every train in merge order, a readable inline-SVG train icon on the train header chip ("merge train · 2 PRs · 1st: #15400"), the Merge queue column header and the 080 chevron, and a stall warning ("Merge queue stalled · head #15253 waiting for CI 3h", one activity-log line per train per hour) past `governor.merge_train_stall_warn_s` (default 3600). `/api/stage-tracker` `merge_train` gains `length`, `head_number`, `head_state`, `head_reason`, `head_since`, `eta_s`, `eta_at`, `eta_basis`, `late`, `stalled`, `stalled_s` (#15395). +- Merge queue: one PR per issue — when two open PRs declare the same `Fixes #N`, the sweep keeps one (a green head first, then the earlier-opened) and holds the other out of every train with gate state `duplicate-of:<n>` (chip "Duplicate of #15402 · needs a pick", `merge_gate.duplicate_of` / `duplicate_issue`, `needs-decision`); "Let hive decide" on either PR takes the existing supersede path (rule `one-pr-per-issue`: the held one closes as superseded with credit, the kept one is released) (#15395). +- Activity Monitor: the "Merge gate" column is now "Merge queue" everywhere a person reads it (header, hovers, legend, decision copy; ids, classes and JSON keys unchanged), and every merge-train state — the 1st in line included — lights that column even while the lane holds the head at 050/070 (hive's own #15400 lit CI / Review beside its 2nd-place sibling) (#15395). +- Automerge merge train: approved PRs whose changed files overlap are grouped per repo and base branch, and only one front per group (mergeable first, then oldest) merges per sweep pass, so parallel approvals no longer dirty each other; `auto_merge.merge_train.enabled` (default `true`) turns it off (#15141). +- Added an operator page, `src/docs/monitoring.md`, covering Prometheus and Grafana monitoring of a hive: enabling the fail-closed `/metrics` endpoint with `HIVE_METRICS_ENABLED` and `HIVE_METRICS_TOKEN`, the metric families, alert runbook anchors, and a plain `scrape_config` without Prometheus Operator ([#15440](https://github.com/hivecommons/hive/issues/15440)). +- Add a fail-closed monthly outcomes publication wrapper and reviewed-PR cadence for owner-supplied, sanitized evidence aggregates; deployment source access and monthly input remain explicit operator prerequisites. +- Automerge sweeps can enqueue eligible PRs into GitHub's native merge queue with the validated head pinned, report queue position and state, and withdraw Hive-enqueued entries only when the PR loses merge eligibility (a hold, a withdrawn or stale approval, changes requested, a paused or disabled repo, or a draft or closed PR) while preserving entries queued by people. The hand-off is opt-in per repo through `auto_merge.native_merge_queue.enabled` and `.repos` (default off; hives without queues see no change). On a queue-enabled base a `blocked` or `behind` PR is enqueued rather than reported `not-mergeable`; the `require_current_base` gate and the `behind` update-branch stay in force unless `auto_merge.native_merge_queue.skip_current_base_gate` is set. The `isMergeQueueEnabled` probe is cached per base branch for `auto_merge.native_merge_queue.probe_ttl` (default 30m) and the entry reconciliation runs only on opted-in repos. A mixed-authorship PR whose queue uses `SQUASH` parks at `stage/085-needs-decision` with the `merge-method` explanation, and the refusal is remembered per head for 30 minutes. +- Add native merge-group CI and an owned PR-evidence gate, opt-in external freshness-writer suppression, default-off scoped owner Settings controls, and a distinct Activity Tracker rail backed by bounded provider-neutral observations of actual GitHub queue entries, exact candidate CI, proven-or-unknown members and lifecycle receipts. +- Tracker, online-contributor and Knowledge sidebar count pills briefly show the actual signed increase or decrease on live updates, with directional amber feedback and a static reduced-motion alternative. +- Activity Monitor: hovering or focusing the *Needs human decision* chevron word or a lead *needs-human* / *triage needed* pill opens an in-app popover that says what the row is waiting on (the reviewer's own question when the hive has one, else the park reason in plain words, plus the blocker — "A reviewer requested changes on b0f5f80 — needs a new commit. Approving cannot override that."), offers the applicable actions as buttons (*Let hive decide* first, then Approve / Give direction / Close as superseded / Close as won't fix / Hold or Release; disabled ones grey with their reason) down the row context menu's code path, and names who asked and when; `GET /api/stage-tracker` rows carry the new `decision_needed` (`question`, `asked_by`, `since`, `blocker`, `blocker_reason`, `options[]`). Requested by @clubanderson ([#14994](https://github.com/hivecommons/hive/issues/14994)). +- Add the reusable Hive `/ok-to-test` workflow and caller template so trusted same-repo bot/App workflow runs can be approved by a repository `GITHUB_TOKEN` without granting the Hive App Actions write. +- Onboarding problems the dashboard shows — GitHub App not installed / wrong installation / insufficient permissions / undelivered credentials, GHES base URL, project target, no projects, no agents — now carry a *New hive? Open the 🧭 Guide → step …* link that opens the Getting Started guide at the matching step; the Guide chip stays visible while any such problem is active, the guide's GitHub App step prints the concrete install URL for the configured GitHub host, and `GET /api/status` exposes the classification as `onboardingIssues[]` (plus `onboarding`/`guideStep` on system alerts and deep-health checks) (#15772). +- Activity monitor: a ✓ decision badge on every row you acted on from the dashboard — green once recorded, amber when the item is still at the same stage past the stuck window, red when the action failed — with a plain-words tooltip (what it is waiting on → what you chose, when → what the hive did next) and a **Decisions** filter (Awaiting my decision / I acted / Acted, still stuck). Actions are kept in a server-side ledger (`/data/operator-actions.json`), surface as `last_operator_action` on tracker rows and via `GET /api/repos/{owner}/{repo}/items/{number}`. Requested by @clubanderson. +- `hivectl evidence benchmark` and `src/scripts/outcome-benchmark.sh` compute a reproducible mediated-vs-unmediated outcome report (revert rate, change-failure, median time-to-merge, CI at merged head, changes-requested-before-merge, cost per merged PR; Wilson intervals, n < 10 not reported) with generated SVG charts under `src/docs/benchmarks/` and a `--readme` flag that rewrites the README's `<!-- outcomes:start/end -->` block, guarded by a drift test +- Human-merge-path holds now record their exact head without claiming pre-existing holds; a shared fail-closed release API validates App ownership and complete label history for later pin-only admission integration, with operator rollout prerequisites documented (#16269). +- Add validated per-repository `auto_merge.human_merge_pin_only` schema, changed-file patch evidence and a fail-closed pin-replacement syntax classifier as building blocks for #16242; merge-path exceptions are not yet enabled and existing human-merge protections remain unchanged. +- The `hive-merge` relay now honours the `auto_merge.human_merge_pin_only` exception, with the same checks as the automerge sweep plus an exact requested-head match; anything short of a proven pin-only change by a trusted author stays held (#16265). +- Enforce the `auto_merge.human_merge_pin_only` exception in the automerge sweep lanes and `/hive approve` (#16266): a PR by a listed trusted author whose complete diff is pin replacements on guarded paths is no longer held for a person. Any other changed file, including an unguarded changelog or doc, keeps the hold (#16326). Repos without an enabled entry are unchanged; the `hive-merge` relay enforces the same exception as of #16265. +- Show preparation owners and FIFO waiting positions in a visible train-style Activity Monitor rail, removing redundant preparation pills and the zero-train header summary while preserving real ready trains, PR stages, row sorting, pagination, and issue trees. +- `hivectl hives preset adopt --onboard` reviews and enrolls missing Hives and preset hub snapshots in one confirmed flow, reusing existing credentials and retaining successful enrollments on partial failure. +- Added an automated list-price refresh for the Cost panel: `go run ./internal/tools/pricetable` reconciles `src/pkg/tokens/pricing.go` with OpenRouter's public model catalogue (no vendor HTML scraped), rewrites only the rates that moved, bumps `priceTableDate`, and reports every change and every row it could not verify; the weekly `price-table-refresh` workflow turns a non-empty diff into a single `needs-human` PR on `bot/price-table-refresh`, and CI now fails when the table is more than 60 days old so a stalled refresh is noticed. See the "Price table refresh" section of `src/docs/token-tracking.md`. +- Once its `hive:recheck-after` deadline passes, a `blocked` ops-tracking soak checklist on the hive's own project gets one soak-evidence comment (stable-channel hives' heartbeat, restart loops and candidate digest/SHA, read from the hub or the spoke's own `/api/version`), the checklist lines that evidence proves are ticked, and `<!-- hive:recheck-done -->` stops repeats; the issue stays open and `blocked` for a maintainer to close (#13311). +- The hub accepts a contributor's **opt-in** relay audit attestation: an `audit_share` on `task_complete` / `task_failed` (rows up to the shared level, clamped to the relay's capture level) writes a `relay_task_attested` audit row cross-referencing the contributor's local record. At `commands`+ the hub stores the shared command rows in `/data/contrib-audit/<login>/<task>.jsonl` (0600, 90-day retention) rather than the 500-entry audit ring. The new `hub.contribute_audit_share_request` (default empty) lets a hive *request* a level, advertised on `auth_ok` (`audit_share_requested`) and on `/contribute` before setup. Admission never depends on it ([#13458](https://github.com/hivecommons/hive/issues/13458), part of [#13441](https://github.com/hivecommons/hive/issues/13441)). +- `GET /api/audit?contributor=<login>` narrows the Audit Log to one contributor's rows (same 200-entry cap and role gate; combines with `?sensitive=1`), the Audit Log gains a `relay_` quick-filter chip beside the sensitive toggle, and the contribute page's Operations tab gains a read-only "Your assignments" card listing the caller's own `relay_*` audit rows ([#13454](https://github.com/hivecommons/hive/issues/13454), part of [#13441](https://github.com/hivecommons/hive/issues/13441)). +- The hub now records the contributor relay's lifecycle in the existing `/data/audit.jsonl` as `relay_*` rows — `relay_connected`, `relay_rejected`, `relay_disconnected`, `relay_task_assigned`, `relay_task_accepted`, `relay_task_declined`, `relay_token_minted`, `relay_task_completed`, `relay_task_failed`, `relay_task_revoked` and `relay_task_abandoned` (plus the reserved `relay_mcp_lease_issued` / `relay_mcp_lease_revoked`) — attributed to the contributor's GitHub login and session, with the task's repository and issue/PR number. Rows are written from frames the hub already receives, so an unmodified relay needs no change; progress and heartbeat frames are not audited and no token is ever written. `relay_token_minted` (which carries the `installation` id) and `relay_task_revoked` are sensitive actions and raise `sensitive_24h` on hives with active contributors; `relay_connected` is not sensitive and omits the remote address. Documented in `audit-log.md` and `contributor-relay.md` ([#13453](https://github.com/hivecommons/hive/issues/13453), part of [#13441](https://github.com/hivecommons/hive/issues/13441)). +- Delegated relay work is now covered by the audit substrate: a new `relay_audit_coverage` compliance posture check passes when the hub wrote at least one `relay_*` audit row in the last 24h or no relay connected, fails when relays connected without any row, and is mapped to SOC 2 CC7.2 (with notes on ISO A.8.15 and FedRAMP AU-2) ([#13455](https://github.com/hivecommons/hive/issues/13455)). +- Dashboard: stage-tracker action-result toasts (adopted, posted, held, no-op) now close themselves after 15 s with the countdown bar and hover/focus pause; errors and toasts offering next actions stay until acknowledged. +- Settings → Features → Review Gate → Reviewers now picks `review.reviewer_agents` from the hive's configured agents, showing each agent's engine/model, the review-capable count, a warning when fan-out would run every review on a single engine, and a note when combined-perspective mode limits fan-out to the first reviewer; `GET /api/config/review` gains `reviewer_candidates`. +- `review.pending_fix_ttl` sets how long a dispatched review fix may go without a new head before the next bounded attempt is dispatched (default 2h; negative disables expiry). It was previously fixed at 2h even though the docs presented it as tunable (#14643). +- `review.require_labels` — a PR-side approval allow-list for reviews, the counterpart of `project.issue_filter.require_labels`: when set, the hive reviews only PRs carrying at least one of the labels. Enforced server-side in the cadence reviewer's PR list, the fan-out dispatch planner and the `hive-review` relay (which re-reads the PR's labels and refuses any review, thread reply or verdict on an unlabelled PR, audited as `review_label_gate_refused`), so a prompt cannot bypass it. New **Settings → Features → Review Gate → "Only review labelled PRs"** toggle with a label list, saved through `PUT /api/config/review`. Empty (the default) changes nothing. Reported-by: @joerunde (a1-vllm-spyre spoke: "the team wants reviews gated — run only when a label is added to a PR"). +- `review.reviewers.autoscale` (off by default; Settings → Review Gate → Reviewers) sizes the reviewer lane to its backlog ([#14685](https://github.com/hivecommons/hive/issues/14685)): the planner now reports the PRs it left waiting for a free reviewer or a parallel slot, and a controller adds a `reviewer-N` replica after `scale_up_cycles` cycles behind `target_backlog_per_reviewer` (or a wait older than the review-pending stage dwell), drains the top replica after `scale_down_cycles` idle cycles and retires it only once its turn ends. Scale-ups are refused by named guards — `at-max`, `cooldown`, `saturated` (kicks not reaching the CLI prompt), `provider-budget`, `provider-headroom`, `max-parallel-reviews`, cgroup `cpu` / `memory`. Dynamic replicas go through the ordinary replica expansion (same role, prompt, token, pane and cadence as `reviewer-2`) and the entrypoint pre-creates their users up to `max`. Each decision logs as `reviewer autoscale: 2→3 reason=backlog=7 oldest=41m0s`; `/api/status.reviewerAutoscale` and an *auto* badge on the lane's agent cards show current/target/min/max and the last decision. +- Reviewer calibration now compares five-bin self-reported confidence with an evidence-derived score, preserves raw reports and legacy fallback, and shows series coverage and monotonic merge-share comparisons without changing review gating ([#13239](https://github.com/hivecommons/hive/issues/13239)). +- Stage tracker: a PR row returned to its author (071 needs-author / 072 returned-to-contributor) now carries a `rework` pickup signal — requested / queued / acknowledged / working / re-review pending — on the waiting-on pill, its tooltip and the row event line, derived from the stage record, the PR list and the contributor fix queue with no extra GitHub calls. +- Render RFC lifecycle notices as Discord summary-card embeds alongside transition text when `rfc_format: card` is configured on the designated announcer. +- In rich mode (`rfc_format: card` or `rfc_threads: true`, on the designated `rfc_announcer`), RFC lifecycle notices now cover RFC documents proposed as pull requests: a PR titled `📝 proposal:` / `📝 RFC`, or one adding or changing `docs/rfc-*.md` / `src/docs/rfc-*.md`, is announced once when it opens (titled by the document's first heading when available) and once with `RFC doc accepted` when it merges, attributed to the RFC issue its body links. PRs already open at the baseline are not announced, the private-repository gate applies, and line mode stays issues-only (#15942, part of #15869). +- RFC lifecycle notices gain opt-in rich-mode keys under `notifications.discord`: `rfc_format` (`line`, the default, or `card`; an unknown value is a config error), `rfc_threads`, `rfc_announcer` and `rfc_backlink_comment`. All default off, so today's one-line posts are unchanged. Card and thread rendering land later. For now, rich mode switches on the designated-announcer gate: a hive set to `rfc_format: card` or `rfc_threads: true` without `rfc_announcer: true` posts nothing and logs `rfc notify: rich mode requires rfc_announcer; not posting` once. Its detector state still advances, so turning on the announcer later does not backfill. This stops several hives sharing a channel from racing to publish (#15926, part of #15869). +- With `rfc_threads: true` on the designated `rfc_announcer`, each RFC now gets one Discord thread under its opened card, with a durable per-RFC message/thread mapping in `/data/rfc-notify.json` (state version 2; version 1 files load unchanged), a write-ahead intent plus Discord `enforce_nonce` and a bounded 50-message history lookup so a crash or retry never posts a second card, later closed/ready/doc-accepted events posted into the thread (closed and ready also echoed once to the channel), and an opt-in `rfc_backlink_comment` that comments the thread link on the RFC once, only after the thread exists (#15939). +- Loopback-only `net/http/pprof` listener (`debug.pprof_addr`, default `127.0.0.1:6060`, `off` to disable), a `mem: runtime snapshot` INFO line every 60 s (heap in-use/live/objects, next GC, goroutines, OS threads, GOMEMLIMIT), the same counters under `runtime` in `GET /api/health`, and a cgroup-aware GOMEMLIMIT default (85% of the container memory limit when the env var is unset) ([#14681](https://github.com/hivecommons/hive/issues/14681)). +- `agents.<name>.sandbox.job.scheduler_name` sets the Job pod's `schedulerName`, for clusters whose admission webhook requires a custom scheduler for device-requesting pods (e.g. `spyre-scheduler`) +- Sandboxed kicks gained a deterministic publish preflight that does not trust the agent's report: `sandbox.publish.verify` (per agent) or `agent_sandbox.publish.verify` (global) lists shell commands hive runs in the same sandbox image/workspace after the run (with `HIVE_CHANGED_FILES` / `HIVE_CHANGED_TESTS` exported), and the first non-zero exit withholds the push and the PR with the command's output tail on the card (`no PR opened: verify failed (1/2): uv run pytest --collect-only -q (exit 2) …`) and in the kick log. A whole-suite `pytest --collect-only` there would have stopped a test-gap PR whose new test file's basename clashed with an existing one and broke collection for every CI shard. Reported-by: @joerunde (a1-vllm-spyre spoke); hivecommons/hive#14999. +- `src/docs/security-model.md` is now the complete inventory of how hive keeps autonomous agents from doing damage: threat model, a control table (control → threat → file/ADR → how to verify), sections per layer from agent runtime isolation to human-in-the-loop, an honest gaps list, and an audit checklist for a running hive; linked from the docs index, documentation map and the root README security section (#13409). +- A trusted maintainer's **changes requested** review on a hive-authored PR, or a `/hive decision <what to change>` comment on one parked at `stage/085-needs-decision`, now moves the PR to `stage/070-fixing` and kicks the author agent once per head with the text verbatim plus the swarm's outstanding findings; the self-authored automerge lane no longer merges over such a review, `/hive decision` on a PR the hive did not open gets an explanatory reply instead of silence, and the 085 entry comment names both actions (hivecommons/hive#13041, live case hivecommons/hive#12968). +- Self-reports now notice clogged queues and repeated errors without a hand-placed hook: a `slog` tee (`pkg/fleetreport/slogfeed`) on the hive's root logger feeds every WARN/ERROR line into `unclassified_error_repeated` (5 identical normalised messages in 10 min; clears after 20 quiet minutes; benign i/o-timeout / context-cancel lines and messages already covered by an explicit class are skipped), and two new queue-health classes report work the hive is silently not doing — `issue_request_stuck` (an issue-request file that has failed ≥3 attempts or been retrying for ≥30 min; clears on completion/quarantine) and `effect_ledger_op_stuck` (a journaled external effect refused for reconciliation while Unknown/Planned for ≥30 min; clears when applied or reconciled). The dashboard's Fleet report card labels every runtime class in plain words. Motivated by eleven placeholder relay requests retried for six hours behind one Unknown ledger op that no self-report ever mentioned. +- Self-report (`[selfreport] …`) issues now name the reporting hive by its display name and link to its dashboard: the evidence table gains `hive name` and `spoke` rows and each `Affected hives (N)` line renders `name (hive id) … — open` as a link to the dashboard. Both travel as `hive_name` / `spoke_url` on the report and the hub relay, which overlays its own project name and vanity URL and fills them for older spokes; hub-less hives stay anonymous and render `—` (#13211). +- Sentinel sweep: optional bounded PatchObserver hook on the PR-patch fetch (#15933) +- Add owner-only Event triggers settings with scoped scanner first-seen issue presets, advanced CEL editing, validation, durable conflict-protected saves, and a direct link from agent Channels. +- Settings now expose the prior-art gate's kinds, max_findings, max_parks_per_cycle and bot_close_ttl with validation. +- Add an opt-in Hub-coordinated CLI session pool for spokes. Participating Hives keep separate workspaces, UIDs, credentials, and tmux sessions; the Hub leases a global live-session slot and idle sessions are terminated after a turn. Configure `HIVE_SHARED_AGENT_POOL_ENABLED` on spokes and `HIVE_SHARED_AGENT_POOL_MAX_SESSIONS` (optionally `HIVE_SHARED_AGENT_POOL_MAX_PER_HIVE` for a per-tenant cap) on the Hub. +- Activity Monitor: every soak-related pill — 095 "Soaking" and a trust-blocked head at 060/080 — now carries the lane's soak clock (`soak: {started_at, until, window_s, head_sha}`) and counts it down in place, says "ready — next sweep in Nm" once the window has passed and "Soak restarted · new head" when a push replaced the soaked head; hovering the soak chevron shows the live time left, when the soak ends and the rule, refreshed as the clock ticks. "merge sweep running" no longer hides the countdown ([#15218](https://github.com/hivecommons/hive/issues/15218)). +- Hive honours the Spek publish marker `<!-- spek:publish name=… artifact_id=… target=… [task=…] [rfc=…] -->` (spektacular#109/#114): a Spek-published child stays on the direct-fix path under `runs.triage` (never a new `spec` run), skips the clarity score, and its kick line carries the RFC link and spek identity with the `Fixes #<child>` instruction; the RFC itself (marker without `task=`) is treated like `epic` for `governor.claims.never_claim_labels` and `IsTrackerIssue`, so Hive never claims it even in a repo without that label. Parser in `pkg/spekmarker`; documented in `docs/spektacular.md` → Publish hand-off. +- Stage engine: new issue-only stage `stage/015-triage-needed` ("Triage needed") for an actionable issue no maintainer has looked at yet — it carries `needs-triage` or the reporter-trust gate holds it in `reporter_triage`; issues filed by hive agents or trusted humans stay 010. The activity monitor's Actionable column now reads "Actionable", "Triage needed" or "Needs human decision"; the Open column is unchanged. 015 is a tracking state, not a gate: claiming and PR coverage move it on exactly like 010, and a maintainer triaging it (015 → 010) is never a regression. +- Stage tracker: new PR stage `stage/095-pre-merge-soak` between `090-ready-for-human-merge` and `100-merge-queue`. A PR the automerge lane has admitted but whose pre-merge soak window is still running now lands on 095 (dashboard word "Soaking", headline "Pre-merge soak — Xm left" from the new `soak_remaining_seconds` tracker field) instead of showing as "Admitted — merging"; 100 is reserved for soak-complete, merge-eligible PRs. 100 → 095 on re-evaluation is a reclassification, not a regression; a quiet 095 past its 45m dwell gets a stall note flagging a probable lane bug. +- Landed the central stage engine skeleton from ADR-0025 (hivecommons/hive#13007, part of hivecommons/hive#12999): the new `pkg/stageengine` package carries the shared `Facts`/`Decision` contract, the `Deriver` registry, the `StageWriter` and `FactSink` interfaces, a `Reconciler` with off/shadow/enforce modes, the `Expected` transition table generated from the stage diagram (a test proves table ⇔ diagram), and the ADR's counters; `pkg/github/automerge` and `pkg/github` gain adapters that derive PR and issue stages through today's `resolveStage` / `IssueStageFor` unchanged, so the sweeps keep their behaviour until PR-C switches them to the reconciler. +- Stage labels: golden fixture corpora freezing the current PR-side (`resolveStage`/`classifyStage`) and issue-side (`IssueStageFor`) stage derivation byte-for-byte, replayed by `stage_goldens_test.go` / `issue_stage_goldens_test.go` (regenerate with `-update`), plus `pkg/stagelabels/shadowdiff`, a pure recorder that counts legacy-vs-engine stage/reason mismatches with a bounded example ring for the ADR-0025 shadow rollout ([#13006](https://github.com/hivecommons/hive/issues/13006)). +- The Activity Monitor Twitch streamer now carries the tracker's merge-zap and new-item-buzz sounds: Chromium plays into a PulseAudio null sink that ffmpeg captures (`STREAM_AUDIO=silent` restores the silent track), and kiosk mode (`?kiosk=1`) turns tracker sounds on by default without a gesture or localStorage write (`&sound=off` keeps it quiet). +- The review swarm now honours `agents.<reviewer>.review_models` ([#13243](https://github.com/hivecommons/hive/issues/13243)): every `[review-perspective:…]` kick is planned against the PR's author model, carries the same `## Independent review — run this review with <backend>/<model>` section the queue kick uses, and respects `exclude_author_model` / `exclude_author_family` / `fallback` (`skip` withholds the kick, `requires_human` holds the PR). New `review.perspective_models` pins a model per perspective. Verdicts now carry `author_model` and `review_model` even without a pool (the reviewer-accuracy summary falls back to the reviewer's launch model), and the Evidence → Accuracy card and `/api/evidence/summary` add per-author-family and same-family vs cross-family buckets (`outcomes_by_author_family`, `by_author_family`, `by_family_match`, verdict `same_family`). +- **Dashboard toasts show a countdown bar timed to their auto-dismiss.** Every timed toast — success, info, warning, an error given an explicit deadline, and an in-flight toast resolved into its result — now draws a 2px bar along its bottom edge that drains from full to empty over exactly the toast's dismiss window, so it reaches zero at the moment the toast leaves. The bar takes the toast's severity colour at reduced opacity, never shifts layout, is hidden under `prefers-reduced-motion`, and is absent on sticky (error) and persistent (spinner) toasts that wait for a click. +- Dashboard toasts: the countdown bar now drains right-to-left over the toast's real lifetime (`--toast-ttl`), pauses with the dismiss timer while the pointer or keyboard focus is on the toast and resumes on leave, uses the severity colour at 40% so it reads in dark and light mode, and stays visible under reduced motion. +- Activity monitor: a multi-row selection offers **Accept triage (N selected)** — leading the selection bar and the bulk ⋯ menu when every selected row waits on a maintainer's triage, *Accept triage (k of N)* when some rows are skipped — accepting every selected issue through the existing per-item endpoint with one summary toast ("Accepted 4 issues"). +- The activity monitor says who holds a claimed item, not just what kind of actor. `GET /api/stage-tracker` rows (and nested `linked_prs[]`) carry `claimant: {kind: hive-agent|clanker|person, login, agent, hive, since, source}` on claimed / in-progress issues and PRs under review or rework, derived from the worker-claim ledger, the `hive:claim` marker (with its hive fingerprint), an assignee or the agent the status payload says is on it. The lit chevron appends one token after its word — **Claimed · quality**, **Claimed · quality@alchemy** (another hive), **Claimed · @bob's clanker**, **Claimed · @alice** — and the chevron hover adds *Held by: <identity> since <ago> (<source>)*. Nothing is added when nobody is named. +- Hive activity monitor: draft PRs (forge draft bit or prow `do-not-merge/work-in-progress`) now wear a muted `draft` pill with a tooltip explaining the review and merge lanes skip them, and their Open cell reads "Draft · since …" without the stale tint, instead of a bare "Open · since …" that looked stuck (#14572). +- Activity Monitor: a row's "Hive: …" note shows for 30 s when it is new, then slides left into a small ⬡ info icon so the list stays quiet; the icon's tooltip keeps the note and its age, a click (or Enter / Space) opens it for another 30 s, a hidden tab pauses the clock, and ⚙ → Hive notes → *Auto-collapse hive notes* (default on) turns it off. +- The Activity Monitor renders a row's lead action inline — `[Accept triage]`, `[Let hive decide]`, `[Merge now]`, `[Adopt…]` — as a button beside the chips whenever the next move is the viewer's, the same entry the ⋯ menu leads with, with its hint as the hover and greyed with the reason when the viewer lacks write access; a sidelined issue (reporter triage, filtered) now keeps its author kind in the row payload ([#15456](https://github.com/hivecommons/hive/issues/15456)). +- The activity monitor's tracker now says where an adopted PR came from: the hive's copy wears a compact `adopted from @author's #N · 6h` chip beside its number, linked to the original, with a plain-words hover on why the hive took it over (CI red and the contributor's agent silent, a maintainer's request, a DCO / rebase re-home); a still-open original reads `superseded by #M`. The `lineage` field behind it is also what the *Let hive decide* preview and the row hover use to add *(adopted from #N)* after the PR number, so an issue covered by an adopted PR no longer looks like the hive took a contributor's PR for no reason. +- Hive activity monitor: a **Movement animation** section in the card settings (⚙) with a subtle, user-selectable animation when an item's lit chevron moves to another column (six styles, default colour wash; respects `prefers-reduced-motion`). +- Activity Monitor: the **PR in progress** chevron names who is working the PR, exactly like **Claimed** — `PR in progress · scanner ⬡`, `PR in progress · @odttlnt's clanker 🤖`, `PR in progress · @clubanderson 👤` — resolved from a live worker-ledger claim on the PR, else the PR author (a hive PR names its attribution-trailer agent); the name ellipsizes before the one-line sub-row wraps and the hover carries the full identity and source (hivecommons/hive#15541). +- Dashboard: the Hive activity monitor now shows a per-repository chip before each issue/PR number (tinted per repo, muted for the primary repo, click to filter to that repo; "Show repo chip" setting in ⚙ defaults to only when multiple repos are listed) and gains a **Group** control (None / Repo) that groups rows under collapsible, sticky per-repo headers with row, needs-attention and per-column counts, remembered across reloads. +- Hive activity monitor rows have a right-click context menu (also the ⋯ gutter button, Shift+F10 and the context-menu key) with the actions that fit the row's state — Decide… (on a PR parked at 085 — or the issue row nesting it — Approve posts `/lgtm` + `/approve` as the operator, Close as superseded by… with a PR picker, Won't fix, Give direction as `/hive decision`; on an issue parked at 045 approve direction / send back to the hive / close; recorded exactly as the maintainer's comment would be; never merges), Hold / Release hold, Re-evaluate now, Mark needs-human, Open on GitHub, Copy link — and multi-select (gutter checkbox, Shift+click range, Cmd/Ctrl+click toggle, Space) with a selection bar whose bulk actions run per row under a progress toast and list failures by row. Selection survives the live re-render and is dropped for rows that leave. Backed by the existing hold, send-to-human and rescan endpoints plus a new audited `POST /api/repos/{owner}/{repo}/items/{number}/decision`. +- Hive activity monitor: a ⚙ settings modal on the card lets you replace the merge zap and new-item buzz with your own WAV (or any browser-decodable audio) files, kept in the browser (IndexedDB, 4 MB cap, built-in fallback if a file fails to decode), with a Play-sounds master toggle, a 0–100 volume slider applied to built-in and uploaded sounds, per-sound preview and reset. Sounds fire for every repo the hive governs. +- Hive activity monitor: an Open issue still labelled `needs-triage` now shows a "triage needed" action chip (and "Open · triage needed" in its tooltip), alongside the existing hold chip. +- Triage prior-art gate (`runs.triage.prior_art`, default on): before any agent claims a feature / RFC / epic issue, the scheduler searches knowledge beads, the Settings index, merged PRs (12 months), closed issues, docs and code for the issue's key terms. A human-filed issue whose best finding reaches the threshold (default 70) is parked at the new `stage/017-possible-existing` ("Possibly exists · needs author") with one comment quoting the findings and two replies: `/hive decision proceed — <gap>` lifts the park and appends a *Scope vs existing* section to the body; `/hive decision exists` closes it `not_planned` with `already-exists`. A discoverability advisory bead is recorded so the docs can improve. Clanker-filed issues are parked the same way and auto-closed after `bot_close_ttl` (default 72h) with no reply; hive-filed issues are never parked (a findings note is attached and the agent prompts make the search a precondition to filing). The dashboard tracker shows the lane and a `possible dupe` chip (#13575). +- `hivectl tui --hives` now shows the shared Hub → Hive → Repository contribution tree (press `t` in the Hives overlay) with textual selection, badge, follow, readiness and activity columns, ancestry-preserving search, staged edits with affected counts for bulk actions, and review-then-Apply or Discard; it shows the same diff and Saved / Relay reload / Acknowledged receipt as `hivectl hives web`, writes nothing until Apply, and asks before discarding unapplied edits on leave or quit. +- Twitch live stream (https://www.twitch.tv/hivecommons) listed in every community-link cluster: README badge and Community section, CONTRIBUTING, community/getting-started docs, issue-template contact links, dashboard sidebar Help / FAQ / Getting Started modal, the `/contribute` portal and default `contribute.help_links`, and hub landing/status page navs and footers. (#15635, #15637) +- Mark lanes `unauthorized` when the hive's GitHub App lacks the permission for the next step: a `403 Resource not accessible by integration` on a prerequisite call (first: approving held workflow runs without `actions: write`) adds `hive:unauthorized`, posts one comment per head naming the permission and the human step, logs once per head, parks the PR at 085 as `Awaiting human: approve workflow runs`, shows a muted `unauthorized` pill in the activity monitor, and clears itself the tick the step is no longer needed ([#14589](https://github.com/hivecommons/hive/issues/14589)). +- Both dashboards now show scheduled-upgrade progress ([#14950](https://github.com/hivecommons/hive/issues/14950)). The hub hive card and the spoke's version menu render the upgrade state as a pill — `Draining · 2/5 agents in turn: reviewer 38m, scanner 12m · 14m left`, `Missed window · drain lapsed` — and list the hub's recent upgrade attempts so a missed window is visible on both sides. `/api/version` carries `upgradeProgress` and `upgradeHistory`. Owners get an **Upgrade now (interrupt turns)** action on the hub card while a hive is draining or missed; it is the normal upgrade request with `?interrupt=1`, audit-logged, delivered on the next heartbeat as `upgrade_interrupt`, and makes the spoke skip its drain and restart immediately. +- Scheduled upgrades now expose their progress as data on both dashboards ([#14950](https://github.com/hivecommons/hive/issues/14950), motivated by [#14856](https://github.com/hivecommons/hive/issues/14856)): the hub's `/api/saas/my-hives` carries `upgradeState` (`scheduled` → `draining` → `pulling` → `rolling` → `verifying` → `done` | `missed`, with the drain deadline/countdown and the agents whose turns are holding it — "2/5 agents in turn: reviewer 38m, scanner 12m") and `upgradeHistory`; the spoke's `/api/status.upgradeProgress` derives the same state locally and the heartbeat policy gains `next_window_at` (the hive's own window, even on `stable`) plus `upgrade_history`. The hub persists the last 14 attempts and held windows per hive (`HIVE_HUB_UPGRADE_HISTORY_MAX`) under `/data/saas/upgrade-history/`, so a missed window survives a hub restart and is never silent. The spoke's drain report now includes per-agent turn elapsed (`upgrade_drain.turns`). +- The dashboard now tells the operator when work is parked on a human: `/api/stage-tracker` carries `waiting_on_human` (`count`, `items[{repo, number, type, kind, since, who}]`; kinds `needs-decision`, `ready-for-human-merge`, `approve-needed`, `returned-to-contributor-offline`, `other-human-wait`) and each item `waiting_on_you` / `wait_kind`. A second, orange **Hive activity monitor** sidebar badge and a **Waiting on you · N** topbar pill (hidden at zero) show the count; both, `?filter=waiting-on-you` and the new **Waiting on you** toolbar chip narrow the activity monitor to those rows; a debounced in-app toast (one per ten minutes, none in kiosk mode) fires when the count rises. Hold, advisories, decided rows and contributors still inside their grace are not counted. +- `hivectl hives web` now renders the shared Hub → Hive → Repository contribution tree with keyboard navigation, mixed selection states, staged Apply/Discard, revision-checked review, and separate Saved / Relay reload / Acknowledged receipts; opening the page preserves legacy profiles without migration. +- **GitHub webhooks now move the Hive activity monitor row for just the PR or issue that changed, in seconds.** A verified `POST /api/webhook/github` delivery that names an item this hive tracks (`pull_request*`, `check_suite`/`check_run`, `status`, `push` to a PR branch, `issue_comment`, any `issues` action) drops the `/api/stage-tracker` cache at once and queues a targeted re-read of that one item — a single `GET`, debounced by `dashboard.stage_tracker.webhook_refresh_debounce_ms` (default `2000`) and coalesced per item so a check fan-out costs one request — then patches its row in the status snapshot (labels, title, draft flag, last activity; closed or merged items leave) and sends the `stage-tracker` SSE nudge. Before, a webhook only invalidated caches and the tracker waited for the next eval cycle (120 s today, up to `governor.eval_interval_webhook_s` = 900 s in webhook mode), so webhooks made the tracker slower rather than faster. No repository is re-enumerated; the read uses the paced REST transport and is skipped while the API budget is critical. `dashboard.stage_tracker.webhook_refresh: false` turns it off. `/api/status` and `/api/gh-rate-limits` `webhooks{}` additively gain `targeted_refreshes_1h` and `tracker_invalidations_1h`. +- **GitHub webhooks now wake the governor loop and refresh the stage tracker in seconds, with fewer GitHub calls.** A verified `POST /api/webhook/github` delivery that invalidates cached state — `pull_request`, `pull_request_review`, `pull_request_review_comment`, `issue_comment`, `check_suite`/`check_run`, `push` to a PR branch, `issues` label/reopen — asks the loop for an early eval cycle, debounced by `governor.webhook_wake_debounce_s` (default `10`) and spaced at least `governor.webhook_wake_min_gap_s` (default `30`) apart; the wake cycle re-enriches only the PRs the webhooks marked dirty and serves every clean PR from cache, so `eval_interval_webhook_s` (default `900`) is now a safe base tick while webhooks are healthy. The loop re-checks webhook health when the `2 × eval_interval_s` window closes and drops back to `eval_interval_s` right away rather than at the next stretched tick, logging one line per transition (`github webhooks healthy; eval mode webhook` / `github webhooks went stale; eval mode poll`); `/api/status` reports `evalMode`, `evalIntervalS`, `lastWakeReason`, `lastWakeAt` and `webhookWakes`. Each status publish also invalidates the `/api/stage-tracker` cache and sends a `stage-tracker` SSE event the dashboard refetches on, instead of waiting out the cache TTL plus its 30 s poll. See the operator reference's "Webhook-driven PR cache invalidation" for the App event subscriptions and `GITHUB_WEBHOOK_SECRET` setup. +- The write-back gate is content-aware: an identical comment on the same item within 24h, the same notice fanning out to several items within 60s, or more than 60 comments of one kind per repo per hour is suppressed (`writeback.dedupe`), persisted across restarts, counted on `/api/status` and shown in the Write-back containment drill-down as `duplicate`, `burst` or `rate-capped`. + +### Changed + +- Clarified the busy-no-activity stall documentation to cover live CLI panes without an input prompt ([#12922](https://github.com/hivecommons/hive/issues/12922)). +- build(deps): bump golang.org/x/net from 0.60.0 to 0.61.0 in /src (#12941) +- build(deps): bump express from 5.2.1 to 5.3.0 in /src/proxy (#12942) +- `governor.labels.stage.engine.mode` now defaults to `enforce` (was `shadow`) after the ADR-0025 rollout gates held on hive's own spoke; an invalid value still falls back to `shadow`, and ADR-0025 is Accepted. Set `mode: shadow` or `off` to opt out. Part of #12999. +- Stage engine (ADR-0025, plan PR-F): the issue stage derivation now lives in `pkg/stageengine` (`DeriveIssue` over `IssueFacts` carrying the resolved hold / blocked / park / umbrella / triage label verdicts); `pkg/github.IssueStageFor` is a shim over it and the issue goldens replay unchanged. `cmd/hive/stageengine_wire.go` is gone (the issue deriver is built in; automerge registers the PR deriver at init) and the ADR's review-state open question is closed with the `ReviewFacts.State` fold table ([#13011](https://github.com/hivecommons/hive/issues/13011)). +- Stage engine (ADR-0025, plan PR-F part 1): the legacy comparator is retired. `governor.labels.stage.engine.mode` accepts `enforce` (default) or `shadow`; `shadow` is now a pure pause (derive and count, write nothing) and the old rollback value `off` is rejected at config load. `stage_shadow_mismatch_total`, the `mismatches`/`lastMismatchExamples` fields of `/api/status.stageEngine` and the tracker strip's mismatch item are gone. Retiring the comparator exposed and fixes an enforce-mode gap: the PR sweep's engine decision dropped the dwell verdict and configured author-kind names, so `stage/stalled` was never written on a PR and a merged/closed PR kept its `role/*` label ([#13011](https://github.com/hivecommons/hive/issues/13011), part of #12999). +- docs: say noWorkReasonMaxLen caps bytes, not runes (#13109) +- refactor: co-locate truncateReasonBytes with noWorkReasonMaxLen (#13121) +- Moved the contribution stage test fixture out of the shipped `hivectl` package into `hivectltest`, so its placeholder credentials are no longer compiled into the hivectl binary ([#13342](https://github.com/hivecommons/hive/issues/13342)). +- images: bump claude 2.1.306 -> 2.1.308 (#13509) +- Crux: `cmd/crux` is a host composition root in the root module, like `cmd/hive`, and is no longer counted as a ring package by the outbound ratchet; with its `config`/`defsrc` rows gone the ring imports nothing from Hive in non-test code (Stage 2 prerequisite 3 complete). +- Crux design doc: Stage 1 marked shipped, measured outbound edge table and Stage 2 (nested module) prerequisites recorded, how to run the Crux package set alone (#13536). +- The Crux agent runtime (`pkg/agent`) no longer imports `pkg/github`, `pkg/agentaudit` or `pkg/tracing` (RFC #13536, Stage 2 prerequisite): the created-PR shape and the per-agent token-cache path moved into the stdlib-only `pkg/crux/types` leaf as `PRResult` and `AgentTokenCachePath` (with `github.CreatePRResult` now an alias, so `*github.Client` still satisfies the sandbox executor's `PRCreator`), the runtime-emitted audit vocabulary, `AuditSink` and `Fields` moved there too (`pkg/agentaudit` aliases them; `pkg/toolapprove` imports the leaf), and the `agent.send_kick` trace span is opened through a new `Manager.SetSpanStarter` seam that `cmd/hive` wires to `tracing.StartSpan`, so reach bookkeeping is unchanged for the hive binary while an embedding without `pkg/tracing` still gets OpenTelemetry spans on the global tracer. The review-prompt restart-trigger test moved from `pkg/agent` to `pkg/review` against the new `crux.FatalNetworkErrorPatterns()` accessor. A new fail-closed ratchet, `src/internal/testutil/crux_outbound_ratchet_test.go`, records every remaining import from the Crux package set to the rest of Hive (dominated by `pkg/config`) and only lets the list shrink. No user-visible behaviour change. +- The inference-gateway health store and the issue/comment shape validators moved into the Crux ring as the stdlib-only `pkg/crux/inferencehealth` and `pkg/crux/issueshape`; `pkg/inferencehealth` and `pkg/issueshape` alias every symbol, so hub, dashboard, github and classify callers are unchanged and the proxy no longer imports either Hive package (Stage 2 prerequisite 3, #13536) +- The GitHub proxy now takes its canary registry, inference usage sink and GitHub REST accounting through three narrow seams (`proxy.CanaryScanner`, `proxy.UsageSink`, `proxy.GitHubRESTAccounting`) that `cmd/hive` wires to `pkg/ioscan`, `pkg/tokens` and `pkg/github`; `ioscan.CanaryLeak` is now an alias of `pkg/crux/types.CanaryLeak`. No behaviour change for a running hive; the proxy no longer imports any Hive package outside the Crux ring (Stage 2 prerequisite 3, #13536) +- The Crux boundary ratchet (`src/internal/testutil/crux_boundary_ratchet_test.go`) now fails closed when a per-package `agent.<Symbol>` or tmux baseline is above the measured count, so removed coupling must be locked in by lowering the baseline in the same change (RFC #13536). Internal test change only; no user-visible behaviour change. +- Comment with the reason (conflict / failing checks / requested changes) when a `role/trusted` human PR enters stage 071 ([#13636](https://github.com/hivecommons/hive/issues/13636)) +- dco: waive the squash of #13548 whose trailer the template dropped (#13647) +- proxy: the GitHub proxy timeout and client-read log paths share one level-parameterised helper, so both keep their levels and `isTimeoutError` gating from a single place ([#13678](https://github.com/hivecommons/hive/issues/13678)). +- chore: share one level-parameterised helper for proxy timeout logs (#13690) +- images: bump codex 0.163.0 -> 0.164.0 (#13734) +- Dashboard cost tiles: issue before PR, merge header sentences (#13750) +- PR stage derivation now lives in `pkg/stageengine` (`PRDeriver`, `ObservationsFromPRFacts`) with the shared lane vocabulary and observation shapes in `pkg/stageengine/prstage` and review-prose classification in `pkg/review/reviewtext`; the automerge package registers its lanes through the central deriver instead of owning the classifier. Labels and reasons are unchanged. Closes #13779. +- docs: documentation-rot audit dead links, stale v4 channel/branch claims, drifted citations, orphan pages (#13820) +- Point pkg/agent, pkg/crux and the crux CLI at the pkg/crux/config leaf (#13868) +- refactor: share the commit-CI pending predicate between pkg/github and stageengine (#13913) +- Crux module API: the `crux/types` leaf package is folded into the `crux` root package, so the runtime's value types (process states, kick dispatch and outcomes, restart events, start-failure classes, turn loss, provider status, audit vocabulary, `ConditionReporter`, `PRResult`, `CanaryLeak`, `ProofProvenance`) are defined as `crux.<Name>`; `watchdog.Condition`, `ConditionType` and `ConditionStatus` and their constants are now defined in `crux` and aliased by `crux/watchdog`, so the root no longer imports `crux/watchdog` ([#13963](https://github.com/hivecommons/hive/issues/13963), [#13536](https://github.com/hivecommons/hive/issues/13536)). +- Updated the scanner threat model and deploy README to cite the Crux module paths (`src/crux/agent/manager_tmux.go`) after the module cut ([#13951](https://github.com/hivecommons/hive/issues/13951)). +- refactor: route agent-mode and capability parsing through crux (#13969) +- The contributor-adequacy rail from [#13998](https://github.com/hivecommons/hive/issues/13998) is the owner's standing policy, not a proposal: `prefer-contributor` still prefers the contributor's PR, and the hive's competing PR is closed only after an adequacy review passes. Policy text and docs no longer call it "proposed". +- proxy: carry loopback remediation guidance as a structured 'hint' attribute on debug log failures instead of embedded prose (#14083) +- crux: Stage 3 status, crux serve how-to, CLI remote mode docs (#14157) +- Crux stage 4 docs: Host-setter disposition table, callback families for credentials and proxy seams, and the failure-semantics decisions in `docs/design/crux.md`, `docs/crux-serve.md` and `crux/README.md` (#14138). +- Crux stage 4: setter dispositions, callback families, failure semantics (#14426) +- chore(fleetreport): IsBenignMessage comment stops enumerating a stale list (#14463) +- dashboard: rename the overview-export encode-failure log helper from `slogWarnOverviewEncode` to `logOverviewEncodeFailure` to match its Debug-level client-disconnect handling ([#14718](https://github.com/hivecommons/hive/issues/14718)). +- refactor(proxy): split github_proxy.go by concern (move-only) (#14733) +- Document that `publish.verify` runs the configured commands in the run's workspace at HEAD, so test-runner configuration the agent committed (conftest.py, pytest.ini, Makefile) is executed as-is; this is a determinism/regression preflight, not an integrity gate (#15006). +- A combined review head kick (`review_heads` under `review.combined_perspectives: true`) now tells the head to read the PR once and judge each perspective in its own parallel sub-agent, then record the one verdict array itself, falling back to reviewing the perspectives in sequence when sub-agents are unavailable. Every sub-agent runs on the head's own model, so each head's verdicts still come from the model it is stamped with. +- Remove an unreachable cancellation check from the MITM inference proxy; runtime behavior is unchanged, and the HTTP translator retains its caller-cancellation handling ([#15159](https://github.com/hivecommons/hive/pull/15159)). +- The rebase-then-merge follow-through now counts a head as the hive's own by its committer: an email-domain-only match (no GitHub login resolved) needs GitHub to report the commit as verified, and the author counts only when GitHub resolves it to the App bot, since a signature never vouches for the author address ([#15182](https://github.com/hivecommons/hive/issues/15182)). +- chore(crux): move tmux session accessors out of manager.go (#15330) +- docs: clarify delegated issue park diagnosis (#15354) +- chore(crux): split manager_restart.go under the crux file-size ratchet (#15362) +- chore(stageengine): share decision-cause prose between automerge and goldens test (#15384, #15385) +- Linked the HIVE_METRICS_TOKEN row in operator-reference.md to the ServiceMonitor setup and alert runbooks ([#15514](https://github.com/hivecommons/hive/issues/15514)). +- dashboard: split stage_tracker.go into 4 files (#15574) +- refactor: split `src/cmd/hive/main.go` into 4 files (`main.go`, `main_github_app.go`, `main_eval_cycle.go`, `main_sweeps.go`) to cut rebase churn on a merge hotspot; no behaviour change ([#15585](https://github.com/hivecommons/hive/issues/15585)). +- refactor: split tracker words source (#15632) +- refactor: split stage tracker UI tests (#15633) +- Split the `stage_tracker_decision.go` and `stage_tracker_merge_train.go` merge hotspots in `src/pkg/dashboard` into four files each (`stage_tracker_decision_{lanes,human_merge,pr}.go`, `stage_tracker_merge_train_{overlap,postpass,eta}.go`). Pure move of whole top-level declarations within the same package; no behaviour change and no exported API change. (#15676, #15678) +- refactor: split `src/pkg/review/prompts.go` into 4 files (`prompts.go`, `prompts_instructions.go`, `prompts_publish.go`, `prompts_combined.go`) to cut rebase churn on a merge hotspot; no behaviour change ([#15701](https://github.com/hivecommons/hive/issues/15701)). +- refactor: split `src/pkg/dashboard/api_repo_item_decision_test.go` into 4 files (`api_repo_item_decision_test.go`, `_approve_test.go`, `_close_test.go`, `_merge_test.go`) to cut rebase churn on a merge hotspot; no behaviour change ([#15702](https://github.com/hivecommons/hive/issues/15702)). +- refactor: split src/docs/labels-and-control-signals.md into per-section pages (#15712) +- refactor: split tracker row source (#15771) +- refactor: split src/pkg/github/automerge/automerge_sweep.go into 4 files (#15819) +- Document the per-hop either-parent tolerance in headIsBaseRefreshChainOf so the comment matches the code (#15835). +- Review backlog issue bodies now put the `Finding:` line before `Evidence:` and place the code permalink, without parentheses, on its own line ([#15955](https://github.com/hivecommons/hive/issues/15955)). +- The tracker's stage-to-column mapping and text-only row title now live in a shared embeddable module (`src/pkg/webassets/trackerrow`) that both the spoke dashboard and the hub can load, with a compatibility test that fails if the spoke's rows and the shared copy drift. The spoke dashboard serves byte-identical HTML; nothing changes for operators yet — this is groundwork for the hub Fleet activity page ([#16062](https://github.com/hivecommons/hive/issues/16062), part of [#15965](https://github.com/hivecommons/hive/issues/15965)). +- The `request_review` relay no longer re-requests reviewers or teams whose review request on the pull request is still pending, so they are not pinged again for the same ask ([#16075](https://github.com/hivecommons/hive/issues/16075)). +- Documented that `crux logs -f` always reads the ring buffer, so `-buffer` is implied and redundant with `-f` ([#16076](https://github.com/hivecommons/hive/issues/16076), [#16077](https://github.com/hivecommons/hive/issues/16077)). Previously the flag help text and documentation did not mention this relationship. +- docs(dashboard): describe the Reviewed row's re-read and unknown column (#16135) +- docs(releasesentinel): describe GitRetagger.git output via the Runner contract (#16161) +- refactor(crux): share front-matter splitting between agentsmd and skillreg (#16182) +- build(deps): bump http-proxy-middleware from 4.2.0 to 4.2.1 in /src/proxy (#16187) +- images: bump omp 18.14.0 -> 18.15.0 (#16210) +- crux: the socket-directory ownership/mode check used by both `crux serve` and the callback listener is now one shared implementation (`crux/internal/privatedir`), so future hardening cannot drift between the two (#16213, #16214). +- **gh-aw compiler upgraded to v1.0.1, with the weekly competitor report regenerated in the same change.** The pinned compiler moves from `v0.89.21` to `v1.0.1` in the on-ramp compile CI and the gh-aw install docs, and `weekly-competitor-report.lock.yml` plus `.github/aw/actions-lock.json` are regenerated from the unchanged Markdown source rather than hand-edited ([#16226](https://github.com/hivecommons/hive/issues/16226), replacing [#16190](https://github.com/hivecommons/hive/pull/16190)). The compiler itself now emits `actions/upload-artifact` v7.0.2 and `actions/download-artifact` v8.0.2, so the `uses:` lines, the `# gh-aw-manifest` header and the "Custom actions used" list agree again (the manifest still listed v8.0.1/v7.0.1 after hand pin bumps). Runtime pieces move with the compiler: setup action v1.0.1, Copilot CLI 1.0.103 with a checksum pin, AWF firewall 0.29.0, MCP gateway v0.5.0, GitHub MCP server v2.0.3. Secrets, triggers, engine and the agent's permissions are unchanged; the generated `conclusion` job gains read-only `checks: read` for gh-aw's agent-failure diagnostics, and the `safe_outputs` job on `ubuntu-slim` is capped at 15 minutes (gh-aw v1.0.1's slim-runner limit). The "Firewall blocked N domains" false positive in the report comment, fixed upstream in gh-aw v0.89.22, no longer appears. +- The per-recipient attention budget (`github.attention.recipient_budget`, still `0` = off) and opt-in digest (`github.attention.digest_recipients`) now load from the `github.attention` block and gate the episode ledger's live first pings and reminders: over-budget asks stay open and listed (status card, attention queue, digest) instead of being posted, and security, required-review, protocol-command and hold asks are never budgeted ([#16271](https://github.com/hivecommons/hive/issues/16271)). +- The post-merge refs sweep (`src/scripts/comment-merged-refs.sh`) no longer posts its "PR #N has merged and referenced this issue with a non-closing `Refs`" nudge when the issue's `hive:status` card already carries an `issue-partial:<pr>` section for that PR (#16363) +- chore(dashboard): fold the no-models warning branches into one if/else (#16382) +- chore(crux): format validateBounds range text lazily (#16406) +- Attention pilot (`github.notifications.attention_pilot: true`): the last two routine issue notes that still posted standalone comments now fold into the issue's single `hive:status` card — the relay's one-line state notes (awaiting CI, parking, already fixed) and the decision-downgrade note left when a label change walks back an earlier maintainer decision (section `issue-decision-downgrade`). Quiet mode without the pilot is unchanged. Section text is also neutralised so quoted issue-authored text can no longer open or close status-card sections ([#16270](https://github.com/hivecommons/hive/issues/16270)). +- Code activity supersedes the Matrix code view: the Activity Monitor topbar has one **Code activity** entry (still `#oc-matrix-tab`) that opens the published-checkpoint reader at `?kiosk=1&view=reader` in a new tab. The decorative rain/cascade/ghost/terminal renderers and their `mx.*` settings are retired. Saved `?kiosk=1&view=matrix` URLs are a deprecated alias for the reader, and the internal `/api/matrix/lines` and `dashboard.matrix.*` names are deprecated but still supported. Capture and broadcasting stay off by default. +- build(deps): bump ws from 8.21.3 to 8.22.1 in /src/proxy (#16567) +- Fixer queue keys and deferred-fix reconciliation now use the same repository qualification as the review queue, including whitespace trimming and empty-repository handling ([#16571](https://github.com/hivecommons/hive/pull/16571)). +- Document why dashboard matrix authentication failures also receive `Cache-Control: no-store`. +- The stage tracker's row tooltip and current-stage line now share one relative-age formatter (#16668) +- `src/docs/env-vars.md` and `src/docs/security-model.md` now describe `HIVE_PROXY_ALLOW_PRIVATE_FORWARD` as it behaves since [#16785](https://github.com/hivecommons/hive/pull/16785): the destination guard covers plain-HTTP forwards, uninspected CONNECT tunnels and transparent-TLS passthrough, and the override lifts it for all three legs at once. The docs previously described the guard and its override as plain-HTTP-only. +- Dashboard: repository org-qualification in `buildReposWithForge` is now expressed once instead of in two duplicated blocks (#16929). +- docs: refresh Codex model snapshot provenance (#16965) +- images: bump claude 2.1.318 -> 2.1.319 (#16970) +- Stage transition dampener: document that `stagelabels.Store`'s dampener history is deliberately in-memory and not persisted with the record; given the short 30-minute window, a process restart only resets suppression, and a reconciler test now covers the suppressed early-return path ([#16978](https://github.com/hivecommons/hive/issues/16978), [#16981](https://github.com/hivecommons/hive/issues/16981)). +- The `ioscan` semantic classifier is now on by default at ACMM L4–L6 (off at L1–L3; `ioscan.classifier.enabled` overrides). A new `ioscan.classifier.fail_mode` says what happens when the classifier cannot answer: `open` passes the rule-cleaned text on, `closed` withholds it. Unset, it follows `ioscan.fail_mode`, so it is closed at L5–L6. At L5–L6 a hive with no model endpoint configured withholds untrusted text until one is set or the classifier is turned off; the boot log says so. Cost is one cached model call per untrusted text per pass, documented in `docs/ioscan.md` ([#6685](https://github.com/hivecommons/hive/issues/6685)). +- `ioscan` peels more encodings before matching (base64 up to three layers, hex escapes, HTML entities, percent encoding, rot13, hyphen/underscore slugs; reported as `injection.obfuscated`), adds rules for paraphrased overrides, forged system turns, text addressed to the AI, claimed approvals, mass deletion via the API, workflow-secret echo, `authorized_keys` writes, fetch-then-run and force-push over `main`, and records a short quoted mention of an injection phrase at Low instead of withholding it. Red-team corpus grew by 20 attacks and 6 benign controls; block rate 67% → 97%, benign false positives 2 → 1 ([#6685](https://github.com/hivecommons/hive/issues/6685)). +- `ioscan`'s red-team corpus now has a committed scorecard baseline (`src/pkg/ioscan/testdata/scorecard_baseline.json`) and a CI ratchet: the attack block rate may only go up and the benign false-positive count may only go down. `go test ./pkg/ioscan/ -run TestScorecardRatchet -v` prints the per-family table ([#6685](https://github.com/hivecommons/hive/issues/6685)). +- `ioscan` now applies a per-surface block threshold (`ioscan.block_at`: `issue_body`, `comment`, `pr_body`, `review`). For text by an untrusted author the default moved from High to Medium, so any injection or dangerous-instruction rule that fires withholds the text instead of only recording it; text by the hive's own identities, repo owners and members keeps the High line. Red-team corpus block rate 51% → 67% with no new false positives ([#6685](https://github.com/hivecommons/hive/issues/6685)). +- `ioscan` now scans an issue/PR conversation as one unit as well as comment by comment (`ioscan.ScanThread` / `EnforceThread`), so a prompt-injection payload split across two comments is withheld from both halves. The kick path uses it on each PR's review-bot threads, which were previously injected unscanned. A new `injection.bypass_review` rule blocks direct orders to merge or proceed without review. Red-team corpus block rate 42% → 51% with no new false positives ([#6685](https://github.com/hivecommons/hive/issues/6685)). +- Activity monitor: once a CI or Review chevron reaches a settled verdict (all checks reported / review approved or changes requested) the chevron shows only its icon in green (pass) or red (fail); the former words ("CI 11/11 passed", "Review 5/5 · 1 changes requested", failing check names) move into the chevron tooltip and `aria-label`. In-progress and awaiting-human states keep their text; chevron geometry is unchanged. +- Activity Monitor rows now draw a PR's base-branch pill (`v5`, `main`) right after the repo chip at the head of the row, before the issue number, instead of in the right-hand modifier cluster; the pill names its PR on hover ("PR #N targets v5") and rows with no linked PR show none. ([#16620](https://github.com/hivecommons/hive/issues/16620)) +- Activity Monitor now shows independent CI and Review columns on each PR, preserving current-head required App/check identity, freshness and each reviewer's own completion receipt. Source repair returns visually to PR in progress only with verified successful source-edit evidence; assignments, administrative writes and owner/adoption waits stay explicit without changing native stages or merge authority. +- Contributor PRs the hive adopted in place (`stage/074-adopted-by-hive`) now merge under the hive's own authority: the contributor lane admits the adopted head (`contributor-lane:adopted-by-hive`) without the original author's registry tier, claim marker or GitHub association, once CI, reviewer verdict, DCO, diff fences and soak pass on exactly the head the hive adopted/pushed; a contributor push over it still yields back to 072 and the usual trust gates. Opt out with `governor.labels.stage.adoption.auto_merge: false`. +- Supersede adoption is close-first: the hive closes the contributor's original in the same pass that opens its copy (one note naming the copy and why, `hive/superseded`), so an issue never shows two active PRs; a copy that is closed unmerged or red at two heads reopens the original (`adoption-copy-failed`, at most once per 24h). `governor.labels.stage.adoption.supersede.close_first: false` keeps the original open until the copy merges (#15135). +- Agent-runtime configuration (`agents`, `backends`, `providers`, `tool_approval`, `agent_sandbox`, `turn` and the governor-nested watchdog / engine / gateway / trajectory / rotation blocks) is now grouped in Go under `config.AgentRuntimeConfig` and `config.AgentRuntimeGovernorConfig` (inlined, so `hive.yaml` is unchanged) as the first Crux boundary (#13536). +- `src/docs/api-reference.md` is now an index over per-area pages in `src/docs/api-reference/<area>.md` (health/status, snapshots, auth, configuration, agents and controls, packs and ACMM, cost, knowledge, contribute, nous, inception, beads, dashboard misc, hub SaaS, hub server), so a route change touches one small page instead of one 760-line table and PRs stop conflicting on it ([#15299](https://github.com/hivecommons/hive/issues/15299)). `check-api-reference-citations.sh` walks the index and every area page by default (a file or directory may still be passed) and `--fix` rewrites only the page whose citations drifted; existing `api-reference.md#<section>` anchors still resolve. +- Docs: `github.app_signed_commits` now has an operator-reference row (default off, App-only, what it rewrites, fallbacks, Settings location) and the level-6 checklist and `github-app-setup.md` point at its dashboard switch (Settings → Forge App → "Re-author agent PRs as GitHub-signed commits") instead of calling it YAML-only. +- Raise the dedicated LKE CI runner ceiling to 140 to relieve queued checks while preserving existing runner resources and the four-runner minimum. +- Codex model fallback refreshed to the 0.165.0 catalog: `gpt-6.1-sol` (the CLI's current default) and the new `gpt-6.1-terra` appear in the dashboard's codex model picker when the live `codex app-server` probe cannot run, instead of the stale 0.159.0 snapshot that lacked both +- `hivectl hives web` now looks like the Hive dashboard (🐝 header, amber eyebrow, dashboard dark/light palette, amber primary button) and the contribution tree works like a file manager: `↑ ↓` move, `←`/`→` collapse/expand or jump to parent/child, `Space` selects, `Enter` expands, `*` expands everything below, typing jumps to a name, and an info panel in the sticky bar describes whatever row is focused or hovered. Each hub and Hive gains a tick-down "Accept all new repositories" box (a hub's box sets it on every restricted Hive under it, with a mixed state) and an "Accept N new" button for repositories already waiting. +- `hivectl hives web` is simpler: the "contribution tree" is now just "What you contribute to", a one-sentence intro (glossary and keys folded into "Help & keyboard"), short row text such as "3 of 12 on · 9 new" instead of three clauses of status, repositories as a plain checkbox with a "New"/"Excluded" badge, secondary actions (Pause, Deselect all, Exclude, Add) shown only on the active row, a one-line "Your changes" summary and a four-line plain-language save receipt, with "Manage Hives" collapsed. On a 6-Hive, 72-repository list that is about 40% fewer words on the first screen (516 to 296) and a page less than half as tall (8,080 px to 3,519 px). +- Contributor-lane auto-promotion now counts an author's clean merged PRs across every repository the hive manages (`auto_merge.contributor_lane.auto_promotion_scope: hive`, the default; `repo` restores the per-repository count), so a contributor trusted in the main repo is admitted on their first PR to a satellite repo; the audit marker and admission log carry the scope and a per-repo breakdown (#14517). +- chore(crux): extract backend resume-handle logic into agent/resumehandle (hivecommons/crux#89) +- chore(crux): extract the copilot token store into agent/copilottoken (hivecommons/crux#90) +- chore(crux): move blocking-prompt matching into agent/panesignal (hivecommons/crux#91) +- Crux rune-aware string truncation helpers (`truncateHead`, `truncateTail`, `truncateStr` and `truncateRunes`, previously implemented separately inside `crux/agent`) moved into the new leaf package `crux/internal/textutil` as `Head`, `Tail` and `Runes`; `crux/agent` keeps one-line delegates, so behaviour and callers are unchanged ([hivecommons/crux#92](https://github.com/hivecommons/crux/issues/92)). +- chore(crux): drop test-only launch-cmd wrappers (hivecommons/crux#93) +- Crux pane-signal parsing (CLI/input-prompt/busy markers, the Copilot question-form check and the pane chrome filter behind `SanitizePaneText`/`DeduplicateBlocks`) moved out of `crux/agent` into the leaf package `crux/agent/panesignal` with its tests; `crux/agent` keeps forwarding wrappers, so behaviour and callers are unchanged ([hivecommons/crux#87](https://github.com/hivecommons/crux/issues/87)). +- crux: `BreakerTrigger`, `PauseCausation` and `PauseTransitionEvent` are defined in the `crux` root (aliased by `crux/agent`) and `cmd/hive` names `ProjectContext` and `DefaultAgentMode` as `crux.<Name>`; the inbound boundary ratchet's `cmd/hive` row drops 22 → 12, and what remains is the in-process manager and its host wiring (refs #14138). +- `docs/design/crux.md`: Stage 2 prerequisite 1 (the `pkg/crux/config` leaf) recorded as done with the final outbound edge table, and prerequisite 2 (the `effects` / `gitidentity` / `outputschema` / `jev` / `fleetreport` / `pushbroker` edges out of `pkg/agent`) scoped with per-edge symbol counts and the shape of each cut. Docs only. +- Added the stdlib-only `pkg/crux/config` leaf holding the agent runtime's configuration types (`AgentConfig`, `AgentRuntimeConfig`, gateway/LiteLLM/sandbox/watchdog types and their defaults); `pkg/config` now aliases them, so `hive.yaml` loading and every key position are unchanged ([#13536](https://github.com/hivecommons/hive/issues/13536)). +- `pkg/agent`, `pkg/crux` and `pkg/crux/cli` now import the stdlib-only `pkg/crux/config` leaf instead of `pkg/config`; the gateway resolution helpers moved onto `AgentRuntimeGovernorConfig` (still reachable through `GovernorConfig`), the `crux` CLI reads `hive.yaml` and definition files through an injected `cli.DefinitionLoader` that `cmd/crux` supplies, and the Crux outbound ratchet no longer lists `config` for those three packages. +- `pkg/inference`, `pkg/proxy`, `pkg/toolapprove` and `pkg/watchdog` now import the stdlib-only `pkg/crux/config` leaf instead of `pkg/config`, so no Crux ring package depends on Hive's loader. The inference route and gateway resolvers take `*config.AgentRuntimeGovernorConfig`; `toolapprove.DeskFromConfig` takes the `ToolApprovalConfig` block and reaches the ACMM-pack plan gates through `Desk.SetPlanPolicy`, which `cmd/hive` wires to `config.PlanAutoApproveForLevel` and `PlanningConfig.PlanFromLabelEnabled`; the origin-label vocabulary moved into the leaf (`pkg/config` aliases it). No behaviour change. +- crux: `CanonicalizeCopilotModel` and `BackendRequiresInteractiveAuth` are defined in the `crux` root (aliased by `crux/agent`), so `pkg/dashboard` no longer imports `crux/agent`; the inbound boundary ratchet drops its `pkg/dashboard` row (3 → 0), leaving `cmd/hive` as the only consumer naming `agent.<Symbol>` (refs #13536). +- `src/docs/design/crux.md`: Stage 2 prerequisite 2 recorded as done with the per-edge move/alias/invert table, the outbound baseline after it, the ring package list including `pkg/pushbroker` and `pkg/watsonx`, and prerequisite 3 (proxy and `cmd/crux` edges) scoped with symbol counts (hivecommons/hive#13536). +- `pkg/agent` no longer re-exports the governor-side audit vocabulary (`AuditLeaseStage*`, `AuditArtifactLinkMissing`, `Trailer*`, `ParseTrailers`, `MissingTrailers`, `ResolveCommit`, `ArtifactLinks`, `ArtifactResolver`, `LocalGit`, `CommitMessageReader`, `AuditRecord`, `AuditReader`, `Fields`, `FormatAuditDetail`); it lives in `pkg/agentaudit` and the dashboard references it there directly (hivecommons/hive#13536). +- `crux/lanes` configuration validation now names the failing field and its allowed range, and duration fields accept strings such as `"30s"` or `"5m"` in addition to integer nanoseconds (#16387). +- The Crux agent runtime (`pkg/agent`, `pkg/crux`, `pkg/inference`, `pkg/proxy`, `pkg/sandbox`, `pkg/toolapprove`, `pkg/watchdog`, `pkg/trajectory`, `pkg/pushbroker`, `pkg/watsonx` and the rest of the ring) now lives in the nested Go module `github.com/hivecommons/hive/crux` at `src/crux/`, joined to the root module by `src/go.work`; import paths moved from `github.com/hivecommons/hive/pkg/<name>` to `github.com/hivecommons/hive/crux/<name>` (`pkg/crux` → module root `crux`), the thin hive-side alias packages keep working, and CI, the Dockerfiles and the coverage floors address both modules (`./... ./crux/...` from `src/`). No runtime behaviour change (#13536). +- The Crux runtime surface (`pkg/crux`) now defines its value types — `ProcessState`/`State*`, `KickDispatch`/`KickPhase*`, `KickOutcome`/`KickOutcome*`, `KickLogInfo`, `KickRecord`, `RestartEvent`, `SubAgentModel`, `StartFailureClass`, `TurnLoss`, `TurnInterruption` — in `pkg/crux/types`, with `pkg/agent` aliasing them; `cmd/hive`, the spoke and `loginscan` reference the `crux.` names (hivecommons/hive#13536). +- Crux module API: `crux.Process` is now its own struct (a snapshot `crux/agent` copies out of its internal agent record) instead of an alias of `agent.AgentProcess`, and the `crux` root package no longer imports `crux/agent`. `ProjectContext`, `RingBuffer`, the Copilot-token constants, `GitHubTokenLogin`, `DefaultAgentMode` and `AgentAvailableAtACMMLevel` are defined in `crux`; `crux.FromManager` is now `agent.AsRuntime`, and `SanitizePaneText`, `ClassifyAuthPane`, `AuthPaneState` and `PaneShowsBlockingPrompt` moved to the new `crux/paneclass` leaf. This is the prerequisite for folding `crux/types` into the module root ([#13963](https://github.com/hivecommons/hive/issues/13963), [#13536](https://github.com/hivecommons/hive/issues/13536)). +- refactor: route Copilot-token and pane-classification helpers through crux ([#13962](https://github.com/hivecommons/hive/issues/13962)) +- Provider-status and backend-auth value types (`ProviderStatus`, `ProviderAgentEvidence`, `RollUpProviderStatus`, `BackendAuthState` and the `BackendAuth*`/`ProviderAuth*`/`Provider*` constants) are now defined on the Crux runtime surface (`pkg/crux`, backed by the leaf package `pkg/crux/types`) and aliased from `pkg/agent`; the hub, spoke and dashboard reference the `crux.` names (hivecommons/hive#13536). +- Crux: the ring's tests use their own `pkg/crux/testutil` helpers instead of `internal/testutil`, so the Crux outbound ratchet baseline is empty in test code too (#13536). +- The dashboard now programs against `crux.Runtime`, the exported agent-runtime surface in `pkg/crux`, instead of `*agent.Manager`; no behaviour changes, and the Crux boundary ratchet for `pkg/dashboard` drops from 68 to 51 distinct `agent.*` references. +- The agent runtime's self-reported error conditions (restart storms, repeated kick failures, stalls, data-disk pressure, GitHub App token-mint failures, CI-poll nudges, watchdog crash loops) now reach the fleet-report tracker through a `ConditionReporter` seam the host wires (`Manager.SetConditionReporter`, `watchdog.WithConditionReporter`); `pushbroker` takes its GitHub App credential as a `TokenScoper` interface and joins the Crux ring with `watsonx`. No behaviour change for hive; part of Crux Stage 2 prerequisite 2 (hivecommons/hive#13536). +- The agent watchdog's credential probe now reads a two-method `UsageProber` slice of the rotation probers (cmd/hive adapts them), and the tool-approval desk scans payload text through a `toolapprove.TextScanner` that `pkg/ioscan` implements and the host installs at init (`SetDefaultTextScanner`); a desk with no text scanner installed fails closed instead of skipping the scan. No behaviour change for hive; part of Crux Stage 2 prerequisite 2 (hivecommons/hive#13536). +- Crux docs: the design page records stage 3 of the sidecar plan (endpoint families, the sidecar client and parity test, callback wiring, `crux agy-turn`) and what stage 4 must do; `crux-serve.md` gains the per-family route table, the Host observer event types and `--hive-callback`; the module README lists `crux/api/client`, `crux/api/callback` and `crux/hivecap`. +- crux: the follow-stream overlap rule shared by the CLI and the serve layer now lives in one `internal/streamtail` package instead of two copies. +- tmux is now invoked outside `pkg/agent` only through the new `pkg/agent/tmux` funnel (`LookPath`, `Command`, `Attach`, `HasSession`); the TUI attach path uses it and the Crux boundary ratchet holds the tmux call-site count at zero elsewhere (RFC #13536). +- Crux Stage 2 prerequisite 2, value-type edges: `pkg/effects` moved whole into the stdlib-only `pkg/crux/effects` (aliased), `pkg/gitidentity` to `pkg/crux/gitidentity`, the Jev environment contract and jev-decide skill to `pkg/crux/jev` (aliased), the agent-report schema and validator to `pkg/crux/outputschema` with the receipt provenance handle as `pkg/crux/types.ProofProvenance` (aliased by `pkg/outputschema` and `pkg/convergence/proof`), and `pkg/jsonextract` to `pkg/crux/jsonextract` (aliased). `pkg/agent` no longer imports `effects`, `gitidentity`, `jev` or `outputschema`, and `pkg/trajectory` imports nothing outside the ring ([#13536](https://github.com/hivecommons/hive/issues/13536)). +- Dashboard: the Agent Logs pane poll (one `/api/pane/<agent>` request per agent every 5 s, ~180 requests and ~6.5 MB a minute on a 16-agent hive) now runs only while the Logs section is visible and the tab is in the foreground, asks the server for just the lines the "all agents" view shows, and refetches once when the section is expanded or the tab returns. Activity monitor `stage-tracker` SSE nudges (one per status publish and per webhook delivery, ~36 a minute on a busy hive) are coalesced to at most one refetch per 2 s and deferred while the tab is hidden. +- The spoke dashboard's `static/index.html` is now generated from per-area sources in `src/pkg/dashboard/static-src/` (CSS, JS and HTML split by dashboard area, concatenated byte-for-byte per `manifest.txt` by `make dashboard-gen`). Served bytes are unchanged; `TestIndexHTMLIsGenerated` fails when the artifact and its sources drift, so PRs touch the area they change instead of one 60k-line file and stop conflicting with each other. +- Moved the DCO provider-unavailable runbook to `src/docs/operator-reference/` and named its policy-message literals; admission behavior is unchanged ([#16404](https://github.com/hivecommons/hive/issues/16404)). +- Destination-merge guard now shares one claims/dependency-evidence helper in the automerge readiness checks and creates its state directory and lock files owner-only (#16054, #16055). +- Fleet self-reporting no longer files standalone `Fleet report: … hive-code defect` issues ([#13470](https://github.com/hivecommons/hive/issues/13470)). Those were synthesised from bare dashboard counters (`StallNudges`, `Restarts`, `CIPollNudges`) with no identity, owners, spoke link or diagnostics, and nobody could act on them (hivecommons/hive#13465; 12 of 18 in two weeks were closed by the bot itself). The conditions are now `runtime-error` self-report classes — `agent_stall` (≥3 consecutive unrecovered "continue" nudges, with last-kick time and frozen-pane hash), `agent_crash_loop` (the watchdog's crash-loop latch, acting mode only) and `ci_poll_nudge` (one per 24h window) — observed by the agent manager and watchdog at the moment they happen, with a scrubbed pane tail as diagnostics. Every remaining report (`acmm-shortfall` included) now carries the hive name, spoke link, owners, repos and `Affected hives` block and uses the self-report label set; an ACMM shortfall about a component this hive already has an open self-report for posts a short roll-up comment on that issue instead of filing its own. The hub relay's label-rejection retry falls back to the core self-report labels, never to none. +- The advisory issue lookup reads the ForgeState cache when a store is bound (`forgestate.enabled`): a memoized advisory issue costs zero GitHub calls on a healthy cycle, a cache miss one targeted GET, and the search/list path runs only when the cache cannot answer. The review-request watcher is event-driven: request-dir notifications and `issue_comment`/`pull_request_review`/`pull_request_review_comment`/`issues` label deliveries wake it, the unprompted scan is a 5-minute reconcile while webhooks are healthy, and the 10 s poll returns only when webhooks are degraded. A `--revise` request for a repo outside `review.revise_repos` is denied once instead of retried every tick (#13252). +- The automerge sweep lanes (self-authored, trusted-author, contributor lane) share one cached open-PR set from the ForgeState cache and run event-driven when `forgestate.enabled` is on ([#13377](https://github.com/hivecommons/hive/issues/13377), part of [#13373](https://github.com/hivecommons/hive/issues/13373)): no `/pulls` list per 10 s tick, a `check_suite`/`check_run`/`status`/`pull_request_review`/`pull_request` webhook triggers a pass for the affected PR only, a 5-minute floor pass covers the no-events case, and every merge first re-reads the PR through the cache with a 60 s freshness bound; a stale snapshot never merges. Review gate, required checks and hold labels are unchanged, and the legacy listing ticker remains the default. +- Overview open issue / PR totals are read from the ForgeState cache (`pkg/forgestate`) when it is ready, and the merged-PR / closed-issue counts behind cost-per-PR and cost-per-issue are incremented from `pull_request closed` (merged) and `issues closed` webhook events and reconciled against GitHub search once an hour (`forgestate.CountsReconcileInterval`) instead of on every 5-minute collection ([#13376](https://github.com/hivecommons/hive/issues/13376), Phase 2b of [#13373](https://github.com/hivecommons/hive/issues/13373)). A rate-limited or failed reconcile keeps the last good counts: `/api/status` carries `staleSince` and per-repo `countsStale` / `countsStaleSince`, `/api/cost` carries `count_stale_since` / `count_source`, and the Overview tiles and cost labels show "stale since <t>" rather than zeros. +- With `forgestate.enabled: true` the governor work source reads each repo's open issues and PRs from the per-repo ForgeState cache instead of listing GitHub every cycle ([#13375](https://github.com/hivecommons/hive/issues/13375), Phase 2a of [#13373](https://github.com/hivecommons/hive/issues/13373)): the cache's reconcile is the only full list, webhook wakes decide from the cached snapshot without a list call, the first decision pass waits for the first successful reconcile of every repo, a repo whose reconcile failed is served last-good and marked stale, every kick ref is held to the same 60 s freshness bound as close/merge (one targeted `GET` when older, withheld when stale), and the hive's own label, close and merge writes plus webhook/confirmation single-item reads are fed straight into the cache. +- The sentinel now evaluates a PR as soon as a `pull_request` opened/synchronize/reopened webhook names it (reading only that PR and its files), and its full sweep is a 15-minute reconcile cadence that enumerates open PRs from the ForgeState cache instead of listing each repo. The GitHub Projects v2 work source lists its board on the same reconcile cadence rather than every eval cycle and applies `projects_v2_item` webhook deliveries as targeted patches; the spoke webhook receiver accepts and routes that event (#13379). +- hive-hosted-matrix stream overlay opens the dashboard with `view=reader` instead of the deprecated `view=matrix` alias (#16612). +- Activity Monitor: the muted pill a PR wears while the hive's GitHub App is missing a permission now reads "hive bot lacks permission" instead of "unauthorized", and its tooltip, the row hover line, the Needs-attention chip title, the needs-human tip, the human-merge gate word and the decision popover say the same — nobody did anything illegitimate, the App installation lacks one permission (hivecommons/hive#16639). The `hive:unauthorized` label, comment marker and API fields are unchanged. +- Hive-authored superseding PRs (`Supersedes #N`, opened by the hive App) now auto-merge with no operator decision: a reviewer `requires_human` — security-sensitive included — is routed to the fixer instead of parking at `stage/085`, and only an unacknowledged sentinel finding, a hold, exhausted fix attempts, red CI after fixes or an unresolvable base conflict park it, each named in the 085 caption. New knob `auto_merge.hive_superseding.auto_merge` (default `true`). +- The hub's GitHub webhook relay now fans out to every enrolled hive that tracks the delivery's repository (and has a dashboard URL) instead of only the first match, so additional hives on the same repo no longer fall back to polling. One log line is emitted per relay target; hives without a dashboard URL are skipped and counted. (#13202) +- Hive activity monitor: every `090 Ready for human merge` row and its tooltip now say why a person must merge (`· workflow files`, `· untrusted author`, `· branch protection`, `· auto-merge off`, `· unauthorized`, … falling back to `· policy`), derived from the stage record's lane reason; nested PR sub-rows and the needs-attention headline carry the same (#14658) +- Refreshed the CA trust bundle in the spoke, contributor, hub, CI-runner and OSS-scanner images: two Mozilla roots withdrawn by the root programs (emSign ECC Root CA - G3, Comodo AAA Services root) are now distrusted at build time, and Node-based CLIs in the spoke and contributor images verify against the system store via `NODE_OPTIONS=--use-openssl-ca`. The image build now asserts the test chains are rejected. +- Issue-side comment churn is cut by editing in place instead of re-posting ([#16433](https://github.com/hivecommons/hive/issues/16433)): `hive:claim` / `hive:release` transitions now maintain one per-issue claim-ledger comment (`<!-- hive:issue-claim-ledger -->`, current state plus the last 8 transitions; `github.notifications.claim_ledger`, default on, `false` restores one comment per transition) that every existing claim reader still parses; a PR re-entering a needs-decision stage has its entry comment rewritten with an `Updated <ts>` line; a new push rewrites the hive's existing `hive-sentinel` comment for the new head; and in quiet mode a reviewer-lane review that narrates "no findings" with an approving, finding-free verdict is recorded and folded into the `hive:status` comment instead of being submitted as a review. +- ACMM L6 is now labelled **Autonomous** rather than "Fully Autonomous" everywhere operators see it — the dashboard header pill (`L6 · Autonomous`), the maturity-level dialog, the hub's level picker and ACMM pages, the `level-6` pack name, advisor criteria text, the tool-approval desk rationale, and the docs. L6 still parks items for human decisions, honours `hold`, cannot grant secrets, org membership, or workflow pushes, and keeps an owner in the loop, so "fully" overstated what the level does. The ladder is otherwise unchanged (L1 Inception → L5 Semi-Autonomous → L6 Autonomous); the numeric `acmm_level: 6` config value and the pack filename `level-6.yaml` are untouched, so no configuration changes are needed. +- `src/docs/landscape.md` is refreshed against the compared projects' current public docs (dated 2026-10-23), gains **New since August 2026**, **Agent isolation** and **Work sources** sections, and joins the fixed file list of `src/scripts/check-security-docs-readability.sh`, so the positioning page must also stay at Flesch-Kincaid grade 11 or below. +- Lane policies now check for an existing gate or written policy before filing a finding class, and propose the missing gate instead of filing a third same-class finding ([#13427](https://github.com/hivecommons/hive/issues/13427), [#13428](https://github.com/hivecommons/hive/issues/13428)). +- Tracker 090 *Ready for human merge*: the lead action is now **Approve and let hive merge** (`queue-merge`) — hive merges on its next tick once CI is green, soak and self-merge ban apply; **Merge now as maintainer** (`merge-now`, and its *Rebase, then merge as maintainer* variant) is secondary. The automerge sweep now honours an operator's recorded queue-merge approval on an untrusted-author PR and attributes the merge to that operator. On the hive's own PR the App no longer tries to review itself (GitHub 422 "Can not approve your own pull request"): the queue note is a comment, the operator's approval is recorded in the hive's store as the plain Approve records it, and the self-authored lane merges on it; the review-request watcher downgrades such a refused review to a COMMENT instead of retrying. +- logscrub: `ScrubString` and the contributor relay now mask the same api-key, Slack/Discord webhook, Slack token and Basic-auth shapes on v5 as on v6 ([#16470](https://github.com/hivecommons/hive/pull/16470)). +- Activity Monitor: the "Merged" ledger pill now rolls its numbers like a mileage odometer when they rise (per digit, ≈0.9 s ease-out; the total and the today / this week figures alike), sets them outright on the first draw, on a fall such as the midnight reset or under reduced motion, and keeps its width while rolling; the merge glyph's flight slowed from 0.9 s to 2 s on an ease-out, with the merged row pinned 3.5 s so it outlasts the landing. +- The dashboard's 🙋 Needs human facet now matches by pattern (`needs-human*`, `*needs-decision`, `*needs-author`) as well as by name, so new stages and labels no longer silently fall out of it; the *All labels* dialog shows a "Needs human covers N labels" group listing exactly which labels the facet selects. ([#13780](https://github.com/hivecommons/hive/issues/13780)) +- Make the `/ok-to-test` workflow template (and `hivectl ok-to-test-template`, now with `--app-login` defaulting to the hive's App login) fully self-contained with the approval logic inlined — no `uses: hivecommons/hive/...` reference — so it works under restrictive Actions policies and on GHES; the 085 stage entry now embeds that rendered workflow when held runs outlive the `/ok-to-test` grace. +- Contributor-lane auto-merge: a hive owner / trusted merger's explicit approval on the current head — a GitHub `APPROVED` review on that commit, or a dashboard `/hive decision approve` bound to it — now releases the `contributor-lane:workflow-path` fence, so the hive merges an approved PR editing `.github/workflows/**` / `.github/actions/**` itself instead of parking it at `stage/090-ready-for-human-merge` (`auto_merge.contributor_lane.owner_approval_releases_workflow_fence`, default on). Approval on an older head does not count; a merge refused for want of the App's `workflows: write` marks the PR `hive:unauthorized` (`merge-workflow-path`) and parks the approved head at 090 as before. The 085 note for an unapproved workflow-path PR now reads "awaiting owner approval" (#14664). +- Hive activity monitor: `sentinel`, `needs human`, `needs human decision` and merge-time `unauthorized` pills are held back (payload `deferred_modifiers`) until the pull request reaches the merge gate (stage/080+), and do not count under *Needs attention* before then; `hold`, `draft`, `stalled`, `regressed` and an `unauthorized` on held workflow runs always show. +- Activity Monitor: a lit "PR in progress" chevron names who works the PR with their kind icon — `PR in progress · @login` plus the hive / clanker / person glyph, the way "Waiting for @login" does (hivecommons/hive#16770); the name truncates with the copy, the tooltip holds the full text, and nobody known keeps the bare word. +- Refreshed the model list-price table from OpenRouter (29 rows moved; list prices as of 2026-10-22): GPT-5.2/5.4/5.4-mini/5.5, the GPT-5.6 sol/terra/luna codex variants and GPT-5.3-codex now carry OpenAI's current per-family rates instead of a flat $1.25/$10; Claude Opus 4.1 ($15/$75), Sonnet 5 ($2/$10) and the Fable 5.1 / Sonnet 5.5 cache-read rates follow Anthropic's published figures; Gemini 2.5/3.5/3.6/3.7 Flash, Grok 4.5, Kimi K3 / K2.7-code, Llama 3.3 70B and DeepSeek chat follow their providers' current list prices. The Cost panel estimate uses the new rates from this release on. +- Refreshed the model list-price table from OpenRouter (2 rows moved; list prices as of 2026-10-26); the Cost panel estimate now uses the new rates. +- Refreshed the Kimi K3 and K2.7 Code list-price estimates from Kimi's direct API pricing as of 2026-11-02, using K3's default 5-minute cache-write rate; all other model rates remain unchanged. +- **Prior-art gate searches docs and code locally across every registered repo** — the `docs` and `code` prior-art sources now query a `pkg/codeindex` snapshot of each `project.repos` checkout under `checkouts_dir` instead of GitHub code search, so findings cover all repos without spending the code-search quota, and a missing, dirty or partly indexed checkout is called out in the gate comment when a comment is posted ("checkout missing/partial for <repo>", repo slug only, no host paths), and recorded in the audit log (`prior-art-gate-coverage-gap`) otherwise, rather than read as no prior art; coverage is as of the local checkout, not origin (#13878). Reports built while the index is still building are not cached, and the first index build starts at startup. +- Issues filed through `hive-open-issue` now follow the prior-art filing verdict: a high-confidence match is refused (naming the existing item) and recorded as a knowledge bead, and a medium match must carry a "Gap vs existing" section and gets the findings attached; each refusal is audited as `agent_issue_prior_art_refused`; off with `runs.triage.prior_art.enabled: false` ([#13879](https://github.com/hivecommons/hive/issues/13879)). +- Show the dashboard shell before downloading its cacheable application script, prioritize the selected and visible panels, limit background refresh concurrency, and progressively render the latest live data without waiting for every panel before restoring navigation. +- Activity Monitor: every PR whose only remaining step is the merge itself now reads one chevron word, **Queued for merge**, with a short qualifier after the dot saying why it has not merged yet — *· next pass in 42s*, *· checking now*, *· soak 12m left*, *· 2nd of 3* (merge train), *· next pass* (Approve / Let hive decide), *· after CI* (Approve and let hive merge while checks run, or a merge call refused for unreported checks), *· needs rebase* (head moved under the merge call), *· branch protection pending*. Three adjacent approved rows on hive's own tracker read *Ready for auto merge …*, *Approved · hive will…* and *Approved · merge queu…*; the tooltip keeps the full explanation. *Soaking*, *Merging*, *Rebasing*, *Needs human decision* and a *Merge failed* a person must fix stay their own words (hivecommons/hive#16653). +- `hivectl evidence benchmark` now also draws the README outcome cards as 2× PNGs with an embedded font (flat colours, no glow), gains `--from-json` to re-render committed assets without the evidence tree, and the README embeds the PNGs so the cards look the same in every browser. +- The README and its outcome cards are written as short full sentences in plain speech, with the numbers inside the sentences. A test now rejects semicolons and label lines in the README prose and card text. +- README rewritten around plain-language evidence cards: `hivectl evidence benchmark` now also renders dark/light full-width SVG cards (accuracy, a before/after scenario from one real pull request, prompt injection, cost, "also" strip, how-it-works ladder) gated by `--readme-min-base` (default 200), takes `--stories` and `--red-team` inputs, and the generated README block lists Accuracy / Security / Cost / Also with no statistical vocabulary; the detailed charts and intervals stay in `src/docs/benchmarks/`, and the former README overview moved to `src/docs/what-is-hive.md`. +- Refresh the README around trust, productivity, efficiency, governance and auditability, with sourced charts and supported work tools. Benchmark regeneration no longer rewrites the root README; redraw its graphics with `node docs/readme/render-charts.mjs`. +- The review swarm now reviews **every open PR regardless of author** — hive agent, human, clanker at either trust tier, dependabot and any other bot — whenever PR review is on (`review.require_approval` + `review.fan_out`); the only switch is the review feature itself. `review.all_authors` is a deprecated no-op (still accepted, logged once). The automerge review gate now also covers the `trusted-bot` and `trusted-author` lanes, so a human's PR waits for the swarm verdict the same way the App's own does; previously human PRs merged through the trusted-author tier with zero swarm reviews ([#12974](https://github.com/hivecommons/hive/issues/12974)). +- A reviewer's scope / follow-up question on a hive-authored PR with CI green and no unresolved finding no longer parks the PR at 085 "Needs human decision": the dashboard classifies the ask and runs the existing *Let hive decide* pipeline itself (approve → merge queue plus a `follow-up:` issue; direction → fixer; owner-only → park with the recommendation), once per head, while policy sign-off asks (workflow edits from forks, OWNERS / secrets / permissions, auto-merge config, sentinel) stay a person's. Off switch `governor.review.auto_decide_questions`; counter `review_questions_autodecided_1h` on `/api/status`. +- The RFC notice poll now remembers pull requests found not to be RFCs by head SHA, so unrelated busy PRs no longer have their files listed on every poll ([#15960](https://github.com/hivecommons/hive/issues/15960)). +- Security docs rot pass: stale "tracked in" citations to closed issues (#2804, #6685, #9586) now say what landed or point at the live successor, every page in the set carries a `Last reviewed:` date, and a new CI guard `src/scripts/check-security-docs-rot.sh` (in the Docs Link Check workflow) fails when that date is older than 120 days or a tracking sentence cites a closed issue. +- The security documentation set (`security-model.md`, `security-threat-model.md`, `security-response.md`, `securing-your-hive.md`, `ioscan.md`, `ioscan-red-team.md`, `security-self-assessment.md`) is rewritten in plain language for a non-expert reader: 60% shorter overall, every page at Flesch-Kincaid grade 11 or below, process notes and `path:line` citations dropped, and factual drift fixed (responder roster, escalation path, SBOM statement, stale v4 header). A new CI guard, `src/scripts/check-security-docs-readability.sh`, runs in the Docs Link Check workflow and fails any of these pages, or `SECURITY.md`, that drifts above grade 11. +- Self-authored (Hive-authored) PR decision questions now escalate to `stage/085-needs-decision` only when they match a named risk class (`review.DecisionRiskClasses`: permissions/credentials, security, sensitive paths, data loss/irreversible, merge/trust policy, external side effects, licensing/legal, unverifiable) or the reviewer marks `<!-- hive-decision-risk: high -->`; every other question is resolved by policy and recorded as an advisory reason, replacing the narrow non-risk allowlist that parked green agent PRs (#13020) whose linked issue had already answered the question. The reviewer template now tells the swarm to cite the linked issue/spec (`per #<issue>: …`) instead of re-asking. +- The dashboard sidebar now reads "Experiment Lab (nous)" and "Inception (spektacular)" so the engine behind each section is visible from the left menu; the section card titles follow the same wording. +- `hive:signoff-attribution` and `hive:unauthorized` notes are now one comment per PR (per blocked step for `unauthorized`), edited in place with a capped update history / attempt count when a new head hits the same block, instead of a fresh copy per push (hivecommons/hive#17066). +- The stage engine now treats a covering PR closing (040→010/030/020) and claim/start-marker reshuffles (030→020) as expected issue transitions instead of anomalies. +- Stage labels now flow through a single `StageWriter` (`pkg/github/stage_writer.go`): the automerge `ApplyStageLabels` sweep and the issue `SyncIssueStageLabels` sweep build `stageengine.Facts` and reconcile through `stageengine.Reconciler.ReconcileBatch` (default shadow mode, byte-identical labels). An AST admission test forbids direct `stage/*` add/remove calls outside the writer, with a temporary allow-list for the relay/claim/ledger paths. Part of #12999. +- Out-of-cycle stage writers (claim relay and release, in-progress start mark, PR-claim sync, decision parking and `/hive approve`/`/hive decision` un-park, dashboard contributor claims and verdict settle) now submit facts to the central stage engine (`stageengine.FactSink`) instead of writing `stage/*` labels directly; the resulting labels are unchanged, and a lapsed claim, lifted park or closed PR re-stages the issue immediately rather than a cycle later ([#13009](https://github.com/hivecommons/hive/issues/13009), part of [#12999](https://github.com/hivecommons/hive/issues/12999)). +- Hive activity monitor: rows order attention-first within each column — rows a person must act on now (a shown pill or a human-gated stage) first, plain rows next, `hold` / `draft` / closed-issue-anchored rows last — for the *Furthest along* and *Longest waiting* sorts and for the PR sub-rows under an issue; the direction arrow flips the age order but never the tier, and the `GET /api/stage-tracker` payload is pre-sorted the same way so chat `/prs` and the hub agree. +- Hive activity monitor: hover text in a tracker row now appears only on the `#N` link (which carries the row tooltip), the covering-PR link, the title and the lit chevron (stage plus whose move it is); passed and upcoming chevrons, the kind, author and mover icons, chips and the `since` column no longer show tooltips. +- Stage Tracker: soaking rows now say what the reader cares about — **Soaking · 4m left**, **Soaking · complete** once the window has run out, **Mergeable · merging now** when the lane's pass is on the soaked head — instead of the lane's internal "merge sweep" name, and the 095 caption ages the soak clock from the lane's last read instead of pinning "0s left at the last sweep" on a row still called soaking. (hivecommons/hive#15575) +- Hive activity monitor: every movement animation now runs flash → move → land — the chevron an item is leaving pulses twice before the chosen effect travels and the new chevron lands lit (one soft flash then a crossfade under `prefers-reduced-motion`); flash timing is tokenised as `--ham-move-flash-*`. +- Activity Monitor: a PR nested under its issue now draws its header on one line — connector, author icon, number, title, lineage chip and base-branch pill side by side with the title ellipsizing (full title on hover) — instead of stacking the connector, the title and the pill on three lines; issue titles and the top-level PR header ellipsize the same way. +- Activity Monitor merge zap re-voiced as a real bug-zapper arc: a high-voltage snap followed by a sputtering 120 Hz mains sizzle that dies out over ~0.45 s, high-passed at 700 Hz, replacing the swept-bandpass crackle and thunk. +- The Activity Monitor's "waiting on" chip now draws who a row waits on instead of spelling it out: a human owner reads `waiting on [person] @login` with the stage chevrons' person glyph and no "(human · no clanker)" qualifier; a contributor's hive reads `waiting on [robot ●] @login` with the clanker's robot head and the online / offline / unknown dot beside it. The hover title says the rest — `Waiting on @zoe (human) — waiting for a human reply` / `Waiting on @hanthor's hive (clanker · offline 26h) — hive will adopt at …` ([#15227](https://github.com/hivecommons/hive/issues/15227)). +- Getting Started checklist: plain-language "what Hive is" intro matching the docs, current method list (codex, goose, agy, omp, bob; openrouter, watsonx gateways), ACMM spelled out, Inception and Experiment Lab added to "More to explore", and docs links moved from the legacy docs.kubestellar.io domain and the v4 branch to docs.hivecommons.dev / v5. +- Adoption close-first now asks the write-back gate before it closes, labels or reopens a contributor's original PR ([#15272](https://github.com/hivecommons/hive/issues/15272)). These writes land on a PR the hive did not author, but they were only counted in the direct-write ratchet baseline, so they ignored a repo pause, the per-repo mode and the `contributor_adopt` kind policy (default L6 + opt-in label). When the gate refuses, the original stays open and closes when the hive's copy merges, and the refusal shows up in the write-back drill-down. A reopen that is due waits for the next poll, for example until an operator lifts a pause; a refusal for any other reason (the kind policy changed after the hive closed the PR) is logged at warn, because it leaves a hive-closed PR shut until a person reopens it. The ratchet baseline drops `automerge_adoption_close_first.go` (7 → 0). + +### Fixed + +- Failed pane writes and rejected kick deliveries now reach the governor and kick-status error paths without recording success; repeated write failures use the existing undeliverable reporting, a failed insurance Enter after the first was accepted still counts as delivered, and idle reviewer lanes and first-scan-deferred targets appear as skipped in governor evaluation logs ([#12846](https://github.com/hivecommons/hive/issues/12846)). +- The `hive-action-smoke` workflow is now registered on the default branch so it can be dispatched, and its relay comment @-mentions a configurable `app_handle` (default `hivecommons-hive`) that the hive's mention parser recognises (#12964). +- With `agent_issue_decision_policy: resolve`, Hive-authored needs-decision requests are now downgraded only when they positively classify as engineering questions; requests the classifier cannot place stay parked for the owner (#12969, #12972) +- Fix the governor run loop stalling during a GitHub rate-limit caution window: the issue stage-label sync is now deadline-bounded and legacy label housekeeping is deferred until the window lapses, so config reloads and heartbeat stats no longer starve. +- Saving an agent's prompt template from the dashboard no longer fails with "permission denied" when the shipped template in `/data/policies` is read-only (e.g. on hosted hives). The edit is saved as a user override in `/data/policy-overrides`, which the editor and the next agent run read ahead of the shipped default; the editor now flags a read-only shipped template and shows where the override is saved (#13005). +- Claim label is generic hive/claimed-by-human, not per-user (#13051) +- Pull requests are never claimed as issues: review-swarm review/fix kicks (whose refs are PRs) are no longer listed in the issue-claims ledger, and the claim admission gate refuses a number that names a pull request. A PR author's comment on its own PR no longer records an issue claim that staged the PR `stage/030-pr-in-progress` — an issue-only stage — until the PR sweep healed it (hivecommons/hive#13061, seen on #12994). +- The issue relay no longer reports `ok:true` for a `stage/045-needs-decision` (or `needs-human`) park the stage engine did not apply: if the issue still wears another stage afterwards, the result is `ok:false` with the reason and the request is retried (#13069). +- Owner advice no longer counts on-demand agents (those with no schedule by design) as missing a cadence; only agents that should have a cadence but don't are flagged ([#13083](https://github.com/hivecommons/hive/issues/13083)). +- Hive now acknowledges `/hive approve` on pull requests once per command and explains what the merge lane will and will not do with it — naming the GitHub **Approve** review that releases a `requires_human` hold — without clearing hold labels. The `stage/085-needs-decision` comment names the lane's release action, including when a maintainer must merge manually ([#13087](https://github.com/hivecommons/hive/issues/13087)). +- Review-backlog findings whose evidence file exists only on the reviewed PR (absent on its base branch) are filed `blocked` with a `<!-- hive:blocked-on pr=owner/repo#N -->` marker and without `help wanted`; a `blocked` issue derives no stage label and refuses every automated claim, and a sweep lifts the label once the PR merges or closes. `hive-open-issue comment --blocked-on-pr <n>` posts the same neutral note with `@`-mentions stripped, so the scanner no longer pings a fork's author to do the hive's work. The contributor relay keeps a session off an issue it just failed or abandoned for `governor.claims.reclaim_cooldown_s` (default 6h) instead of handing it back every ten minutes. +- Exclude stall nudges that the harness "continue" nudge recovered from the fleet-report `agent stall` evidence so self-recovery no longer files hive defects (#13098). +- The release comments the hub posts when it lifts a relay-applied `blocked` or decision label now treat the relay-supplied verdict reason as untrusted text (#13106): it is flattened onto one line, capped on a rune boundary, stripped of HTML comment delimiters so it cannot forge the hub's own idempotency markers, and @mentions in it are neutralised, so a contributor relay can no longer make the App identity notify arbitrary users or inject extra lines into an issue comment. The verified reporter handle still reads as a mention. +- Preserve UTF-8 rune boundaries when truncating contributor verdict reasons in the persisted ledger, preventing replacement characters in long multilingual reasons ([#13110](https://github.com/hivecommons/hive/issues/13110)). +- Show superseded contributor PRs with close / keep-open actions in the Review Queue even when automatic closure is disabled; the sweep audits every detection and the queue shows no countdown while `supersession_sweep.close_contributor_prs` is off ([#13114](https://github.com/hivecommons/hive/issues/13114)). +- Fixed a `requires_human` verdict on an untrusted contributor PR routing to `stage/050-review-pending` (and picking up `stage/stalled`) instead of `stage/085-needs-decision` when the contributor lane's author-association admission reason applied or nothing had reported on the head yet (#13115, #13112). +- Superseded contributor PR threads now lead with the close/keep-open decision: review comments render the `hive-decision-question` as visible text, reviews marked `<!-- hive-redundant-of: #N -->` (now documented in the reviewer policy) show a `no-op merge: duplicate of #N` headline instead of a 0/5 score, and the supersession sweep notice addresses the repo operator with the recommendation and choices, staying neutral when an operator already chose keep-open (#13116). +- The entrypoint's agent token-cache re-own step now matches only the agent's own `gh-token-<agent>.cache` files (and `.cache.*` / `-<n>.cache` siblings) instead of any file containing the agent name, so `reviewer` no longer steals `code-reviewer`'s token cache ([#13123](https://github.com/hivecommons/hive/issues/13123)). +- The review-fix kick no longer pushes hive-signed commits onto PRs whose login author is a person, even when the PR is hive-attributed; the fix is proposed in the review instead (#13124). +- The dashboard now shows the release semver the hive is running ([#13130](https://github.com/hivecommons/hive/issues/13130)). `/api/version` returned only a hard-coded legacy `version` constant and the commit, so the build-stamped semver (`hive --version`, already sent to the hub) never reached the UI. It now exposes it as `release` (omitted when the build has no version), and the sidebar version chip and menu show it next to the commit. +- The dashboard header's feedback, theme and other right-hand buttons no longer overlap the project title or ACMM badge at window widths between 769px and 900px; those widths now show icon-only Settings, Health and Guide chips ([#13135](https://github.com/hivecommons/hive/issues/13135)). +- 085 entry comment follows the decision cause; flag @maintainer placeholder questions (#13139) +- Moves within 070/071/072 re-attribute the fix, not a regression (#13140) +- Contributor dispatch now honors `[vN]` title prefixes and `Target: vN` issue-body declarations, while a validated `wrong_base` verdict re-routes the next offer instead of applying `hive/already-done` or closing the issue ([#13146](https://github.com/hivecommons/hive/issues/13146)). +- A `replicas:` copy of an agent (`<agent>-2` .. `<agent>-N`) can now read its own GitHub token on per-UID deployments ([#13166](https://github.com/hivecommons/hive/issues/13166)). Replicas exist only in memory, so the entrypoint never gave them a `hive-<agent>-N` user, private token group or pre-created token cache. The manager ran each replica as a bare `uid:node` and its cache was written `dev:node 0600`, so every `gh` call in the replica was blocked with `token_cache_unavailable` and a restart did not help. The entrypoint now derives replica names from each agent's `replicas:` setting and provisions them at boot like declared agents. Raising `replicas` on a running hive still needs a restart before the new copies can read their tokens. +- Fixed: a not-licensed Copilot 403 during model discovery is no longer filed as a fleet `model_discovery_degraded` self-report; it is only warned and audited locally. (#13206) +- The superseded "Close now" action now refuses (404) a pull request with no recorded supersession state instead of closing it with a generic comment ([#13224](https://github.com/hivecommons/hive/issues/13224)). +- `just contribute-check` / `contribute-setup` / `contribute-move` now derive their accepted backend list from `KNOWN_BACKENDS` in `config/backends.conf` instead of a hard-coded copy, so the Justfile gate and the launcher can no longer disagree: `aider` (wired through backends.conf, the relay and the local launch path) is accepted with its own preflight probe, and `gemini` (no CLI in the contributor image and no `backend_binary` mapping) is no longer accepted by the gate. `bin/test_backend_smoke.sh` gains a parity check. Closes #13262, #13263. +- CI's base-image registry probe now verifies every linux/amd64 and linux/arm64 layer blob on mirror.gcr.io, not just the manifest list, and falls back to docker.io when a layer is missing — the pull-through mirror intermittently 404s a layer behind a manifest it still serves, which failed Docker builds across PRs with "could not fetch content descriptor ... not found". (#13300) +- The issue stage sweep now writes `stage/040-covered-by-pr` when GitHub actually lacks it: the in-memory covered-by-PR label the claim guard adds for the dashboard no longer hides the missing forge label from the planner, so an issue whose 040 was stripped by a claim release (or never written at PR open) is re-staged next cycle instead of staying stage-less while its PR is open ([#13316](https://github.com/hivecommons/hive/issues/13316)). +- fix(agent): credit stall recovery when a new kick or provider disarm resets the nudge, so fleet reports stop flagging uncredited recoveries as agent stalls (#13333, #13335) +- fix(stage): copy issue labels before synthesising stage/040 so callers are not aliased (#13336) +- Hive auto-merge (trusted-author, contributor, self-authored and queued lanes) and the hive-merge relay no longer squash forward-merge / top-up PRs: a `🌱 top-up:` or `sync:` title, a `topup/*` or `sync/v*-to-v*` head, or a head that merges another release branch now always lands as a merge commit, preserving the release lines' merge-base ([#13404](https://github.com/hivecommons/hive/issues/13404)). +- Activity monitor: sidelined PRs (drafts, exempt labels) now carry GitHub's closing references too, so a draft with a valid `Fixes #N` pairs with its issue instead of showing "no linked issue"; linked issues keep their title on both the batch and per-repo GraphQL paths. +- Webhook re-bucketed PRs keep their linked issues in the activity monitor instead of waiting for the next reconcile tick ([#13448](https://github.com/hivecommons/hive/issues/13448)). +- The Cost card's headline total now uses the same estimator as the trend chart — persisted per-day totals for days the snapshot ring no longer holds plus the positive step-to-step increments inside the ring — instead of a sum of per-"lineage" peaks that double counted the residual surviving a partial reset (a counter falling 13,964 → 5,058 added the 5,058 again, ≈$6K over on one spoke), missed spend inside a lineage that dipped and regrew, and changed every time the ring evicted a sample (the "since" date crept from Aug 8 to Aug 10 within a day of viewing). Only a step that is both abnormally large and restores the counter to a level it had already reached is treated as a data correction; a large step to a new high is spend. The "since" date — and the window the merged-PR / closed-issue denominators are counted over (`count_window_start`) — now comes from the oldest per-day total and is stable, so the headline and the per-PR / per-issue tiles name the same window. Fixes [#13481](https://github.com/hivecommons/hive/issues/13481). +- The Cost chart and per-day rollup no longer discard real spend revealed after a sampling gap. The discontinuity guard judged every increase of the cumulative estimate as if it had arrived at the 5-minute cadence, so when the collector had not sampled for hours or days (it only ran while a browser was polling) the single step that revealed that whole period was thrown away as a "correction" — on one spoke $10,679 of the $16,957 recorded increments, leaving a 14-day chart and run-rate that bore no relation to the headline. A step above the fixed ceiling is now kept when 20× the hive's average spend rate over the elapsed gap explains it (server `costFoldDailyRollups` and the UI's bucket code apply the same rule), and a step that is discarded now drops its token deltas too, so a day can no longer show 828M tokens at $0. Fixes [#13482](https://github.com/hivecommons/hive/issues/13482). +- The cost history that feeds the Cost tab's sparkline, trend chart and run-rate is now sampled every 5 minutes by the hive itself instead of only when a browser polled `/api/knowledge/stats`. Spokes nobody was watching had multi-day holes (up to 296 h) that the chart drew as $0 and whose spend then landed as one step when the page was next opened. No snapshot is written before the token collector has reported anything, so startup cannot record a false $0 reset. +- The Cost card now says what its headline is in plain words — **Estimated spend at list price — since <date> · tokens × public per-token price · not a bill**, with a **?** tooltip explaining that subscription seats and self-hosted inference are not billed per token — instead of "estimated total (persisted history × list price)" beside an unexplained "$X current lineage". The live token summary is shown as "of which $X … since the last reset on <date>", the per-PR / per-issue tiles read "total ÷ N PRs merged by hive since <date> · counts as of <time>" with a note that both divide the same total and are not additive, stale GitHub counts carry their as-of time, the usage tables are tagged as live-summary-only, and token counts keep two significant digits at every magnitude (176K rather than "0.000B"). Fixes [#13484](https://github.com/hivecommons/hive/issues/13484). +- The Cost chart, "spend in selected range" and run-rate no longer price historical models at $0. The per-model $/token map used to turn token increments into spend was taken from the newest snapshot alone; the token summary only lists the models of the sessions currently on disk, so once a hive's live traffic was down to a single helper model every Claude/GPT model in the history priced at $0 and the chart of a ~$17K history summed to $15 (flat sparkline, "run-rate ~$0.18/day" while the headline said $21K). Each model's rate is now taken from the newest snapshot that still lists that model. Fixes [#13498](https://github.com/hivecommons/hive/issues/13498). +- Dashboard cost-recording staleness check now normalizes model ids the same way the token price table does (provider prefixes, dash collapsing, Bedrock and dated suffixes), removing false stale alarms for configured models ([#13503](https://github.com/hivecommons/hive/issues/13503)). +- The reviewer lane's policy now carries the mandatory "do not wait for CI" guidance, so reviewer agents stop polling CI on PRs they have already handled instead of triggering the stop-polling nudge ([#13505](https://github.com/hivecommons/hive/issues/13505)). +- The task-list sweep no longer puts `needs-human` back on an issue after a maintainer un-parked it with `/hive approve`, `/hive decision` or label approval; only a PR merged after that answer with its own `(needs-human: …)` marker re-adds the label ([#13516](https://github.com/hivecommons/hive/issues/13516)). +- Resolve the GitHub App bot login without holding `selfLoginMu` across the network call, so `isHiveAccount` no longer blocks for up to 10s during the first lookup ([#13522](https://github.com/hivecommons/hive/issues/13522)). +- Concurrent first-time lookups of the authenticated GitHub login now share one `GET /user` instead of each issuing their own; waiters receive the same result (or failure cooldown) and can cancel their own wait without aborting the lookup ([#13524](https://github.com/hivecommons/hive/issues/13524)). +- Concurrent authenticated GitHub login lookups share one request and release pending waiters even if that request panics, allowing subsequent lookups to retry ([#13526](https://github.com/hivecommons/hive/issues/13526)). +- `review.ReviewCapable` is now replica-aware (a replica of a listed `reviewer_agents` lane is review-capable) and is shared by dispatch, the dashboard, relay, merge-eligibility and reviewer accuracy; the PR author's base agent is resolved from the full configured agent set (enabled or not, including a replica a reduced `replicas:` count no longer materialises), so a base or sibling replica is never dispatched to review its own family's PR even when the authoring replica is paused, disabled or not review-capable, and the verdict relay's self-approval guard refuses a dispatch-less verdict from any lane in the author's family (#13552, #13562) +- Compliance evidence exports now include SHA-256 manifests, coverage and retention metadata, selected profile versions, attester identities, and the authenticated export or posture-run actor; each `compliance_export` audit entry records the SHA-256 of the delivered file ([#13582](https://github.com/hivecommons/hive/issues/13582)). +- fix: `gh run watch` and `gh pr checks --watch` are now refused by the gh wrapper (reason=ci_watch_blocked) so agents cannot keep polling CI after the ci_poll_nudge; `watch` is dropped from the `run` surface allowlist (#13587, #13594, #13596) +- Sentinel now honours a maintainer's removal of `sentinel-alert` on a head it never alerted on: when the label was removed by a non-Hive human after the current head was pushed (a rebase between the alert and the review), the current head counts as cleared, the marker comment is rewritten for that head so the clearance survives a restart, and the label is not re-applied; a push after the removal still re-alerts. The push time is read only from signals GitHub stamps server-side — the `head_ref_force_pushed` event for the head, or the earliest check suite / commit status created for it — never from the commit's committer date, so a backdated commit cannot ride a stale clearance; a head with no such signal is re-alerted as before ([#13602](https://github.com/hivecommons/hive/issues/13602)). +- The hold guard no longer re-holds a PR whose branch was rebased earlier during the hold when a human (not a Hive account or bot) removed the gate label after the current head arrived on the branch: that lift reviewed the current head, so the snapshot clears without the integrity comment or a fresh `hold`. The head is accepted only on evidence a contributor cannot forge: the server-stamped `head_ref_force_pushed` event that produced it, or the hive itself having observed that exact head on the PR while the gate was still on. Commit committer dates and SHA-keyed check-suite/status times are never used; a push after the lift, a head the hive never saw while held, a lift by the hive or a bot, or a failed lookup still re-holds as before ([#13603](https://github.com/hivecommons/hive/issues/13603)). +- A review-backlog finding folded into an existing open issue over the same files now lands there in full — title, `file:line`, summary, severity, source PR and fingerprint — under an "Additional finding (folded in — same file, possibly a different problem)" heading with an unchecked task-list line, instead of a bare "Linked again from the Hive review of PR #N" comment; the `hive:review-backlog-link` dedup marker is unchanged, and the PR's backlog summary now reads `#T (folded into an existing issue) — <finding title>` instead of implying the twin carries that title ([#13604](https://github.com/hivecommons/hive/issues/13604)). +- Label-driven approval no longer deadlocks on a lifecycle bot's park label: a repository can list automation accounts in `label_driven_supersede_park_actors` (project-wide or per repo) so that a trusted `triage/accepted` added after such a bot's `needs-human` removes it, says so in the release comment, and releases the issue; park labels added by people, by unlisted bots, or by a listed bot after the acceptance still block, `hold` is never superseded, and the list is empty by default ([#13605](https://github.com/hivecommons/hive/issues/13605)). +- Queuing a PR for auto-merge with the default `lgtm` label now also sets the `prow/lgtm` commit status on the approved head commit, so repos running prow-github-actions v3 no longer strip the label and silently drop the PR from Hive's merge queue ([#13616](https://github.com/hivecommons/hive/issues/13616)). If the status can't be written (the App needs `statuses: write`), Hive logs a warning and comments on the PR; other labels such as `hive/auto-merge` are unaffected. +- Spoke heartbeat: HTTP 502/503/504 from the hub front proxy (hub restarting / "no available server") are treated as transient and no longer self-reported as `unexpected_http_5xx_from_hub` (#13620). +- Reject `review_heads` agent names whose `hive-<name>` group exceeds 32 characters with an `alias` hint, and log `groupadd` failures in the entrypoint (#13622). +- Adoption no longer opens a `signoff-rehome` superseding PR that would carry the same head and fail the same sign-off gate; the adopted PR goes straight to `stage/085-needs-decision` with one note proposing a merge-commit (`--merge`, not squash) merge or a re-authored head. +- Stop role/trusted flapping on and off: keep the PR's existing role label when no lane reports an author tier in a pass (#13637) +- signoff: skip the sign-off attribution nudge and commit sign-off check on `sync/v*-to-v*` and top-up forward-merge heads, which carry other people's commits by design (#13635) +- config: reject review_heads names over the 32-char group limit (#13641) +- The CI-poll nudge no longer counts polling commands quoted as prohibitions in the kick prompt as the agent polling CI, which filed false `ci_poll_nudge` self-reports "0s after the kick" (#13648). +- Automerge no longer reports fork PRs that disallow maintainer edits as conflicting when update-branch is refused; they now skip as fork-not-editable, and an already-current branch is a no-op; same-repo 403s keep the plain update-branch error (#13650) +- Proxy client read timeouts and pre-handshake disconnects (including the transparent-proxy handshake and copilot-sniff client reads) no longer surface as repeated-error self-reports (#13652, #13657, #13661, #13665). +- Permissions watcher fixes now log at Info, and the interactive-home mode restore no longer warns on EPERM for homes the process does not own, avoiding repeated self-report issues Per-agent XDG dir creation and per-agent dir-mode restore likewise log at Debug on permission errors for unowned homes (#13653, #13654, #13655, #13662, #13663). +- Bound bead vault filenames (truncate + short hash) so long bead titles no longer fail ingest with ENAMETOOLONG (#13656). +- Stopped agents no longer flood WARN logs and self-report issues: `tmux has-session` failing because the per-UID tmux server is not running is now treated as "no session" rather than a probe failure (#13658). +- The copilot CLI model-substitution warning is logged once per agent session instead of on every poll, so it no longer surfaces as a repeated-error self-report (#13659). +- Workspace cleanup no longer sweeps dot-prefixed per-agent cache dirs (e.g. `.gomodcache-*`) and logs repeated permission-denied removal failures at Debug after the first Warn, stopping the repeated warning spam (#13660). +- Review-evidence bundle writes that fail with permission denied now warn once per path instead of repeating every poll; the evidence directory ownership still needs fixing on affected hosts (#13664). +- A missing GITHUB_WEBHOOK_SECRET is warned about once per process instead of on every rejected webhook, so it no longer surfaces as a repeated-error self-report (#13666). +- GitHub REST negative-cache hits no longer log at Warn, so suppressed 404 refetches stop surfacing as repeated-error self-reports (#13667). +- Fleet self-report upstream-write and cleared-comment failures now warn once per fingerprint and error (Debug on repeats, re-armed after a successful write) instead of on every retry, so an unreachable report repo no longer files repeated-error self-reports ([#13675](https://github.com/hivecommons/hive/issues/13675), [#13676](https://github.com/hivecommons/hive/issues/13676)). +- Review-pending expiry and human-decision-label failures are logged once per PR (then at debug) instead of every sweep cycle, so they no longer surface as repeated-error self-reports (#13677, #13687). +- agent: stop re-fixing the antigravity CLI log mode on every permissions tick — the permissions watcher no longer re-chmods the Antigravity CLI log (`cli-*.log`) to group-write on every tick, which flooded the log with repeated mode fixes (#13692, #13653, #13695) +- The advisory digest no longer logs a `WARN advisory: issue state lookup failed` on every sweep for a referenced issue that was deleted (HTTP 410). `IssueClosedAt` now treats 410 like 404 — a terminal "not found, not closed" answer rather than an error — so the finding stays open without repeated warnings (#13725). +- The selfreport slog feed no longer files `unclassified_error_repeated` issues for the expected, self-healing "continuous re-kick backed off after failed kick" warning (for example a backend CLI slow to reach its input prompt); it is now recognised by the `kick_failed_repeatedly` class keywords, which only reports after the restart recovery fails ([#13732](https://github.com/hivecommons/hive/issues/13732)). +- The selfreport slog feed treats the permissions watcher's `fixed …` lines (file/directory permissions, ownership) as benign self-healing and no longer files `unclassified_error_repeated` issues for them. On v5 the `fixed file permissions` line is already Info-level and never reached the feed, so this is a guard against re-promotion there; the `fixed ownership` line still logs at Warn and is now suppressed too ([#13735](https://github.com/hivecommons/hive/issues/13735)). +- Refs-only PR claims now stage their issues as covered instead of actionable; activity rows show refs coverage, the covering PR's base branch, and tracker sub-issue progress when available, while preserving non-closing references for unchecked delegated tasks and watcher-downgraded links ([#13747](https://github.com/hivecommons/hive/issues/13747)). +- Bound `/api/knowledge` responses with default pagination and add Previous/Next navigation to the dashboard Knowledge fact list, rendering at most 50 facts per page; expose `hivectl knowledge list --limit/--offset` so CLI users can retrieve subsequent pages (#13790). +- Collapsed dashboard sections skip rendering hidden content while preserving visible summaries, expand animations, and sparkline replay ([#13791](https://github.com/hivecommons/hive/issues/13791)). +- Review dispatch no longer stacks several review kicks on one agent ([#13793](https://github.com/hivecommons/hive/issues/13793)). With `review_heads` replicas, the replica picker counted distinct PR heads per agent, so replicas holding the same PR tied and one PR's remaining perspectives all went to the first replica. On a two-replica Sonnet head, four kicks reached one Claude session within three minutes; it ran one turn, the other verdicts never arrived, and they expired and were re-sent to the same replica. The planner now sends a review kick (per-perspective, head, combined or decision) only to an agent with none in flight, picks the first free one in name order, and lets work wait for a later cycle when every candidate is busy. Waiting costs no `max_redispatch` or `head_max_retries`. +- Hide the `refs` chip after a red, stale pull request releases its issue back to actionable work. +- A seeded policy that differs from the embedded default with no seed record is now warned about once instead of on every reconcile tick ([#13825](https://github.com/hivecommons/hive/issues/13825), [#13835](https://github.com/hivecommons/hive/issues/13835)). +- A self-report "cleared" comment that GitHub refuses with a permanent error (403, 404, 410 or 422) is now recorded once and no longer retried every cycle; transient failures are retried with exponential backoff and given up after a capped number of attempts ([#13827](https://github.com/hivecommons/hive/issues/13827)). +- Copilot sniff client disconnects before the TLS handshake (EOF, reset, closed connection) are now logged at debug instead of warning, so they no longer raise repeated runtime-error reports (#13828, #13831). +- Review evidence no longer fails with "permission denied" when a PR's evidence directory was created by another user: the bundle is written to a writer-owned `<pr>.uid<N>` sibling directory that the evidence readers (API, dashboard, `hivectl evidence`) also consult. New evidence directories are created group-writable (`0o2775`), and existing ones the writer owns are widened to match ([#13836](https://github.com/hivecommons/hive/issues/13836)). +- Prevent routine pending-review expiry retries from creating repeated-error fleet self-reports across unrelated PRs; expiry logs and exhausted-review reporting remain available ([#13850](https://github.com/hivecommons/hive/issues/13850)). +- Close-on-merge logs non-closing PR references as informational diagnostics so repeated sweeps do not file spurious runtime-error self-reports ([#13852](https://github.com/hivecommons/hive/issues/13852)). +- Missing optional human-decision labels now log an informational notice instead of a warning, preventing false fleet self-reports across held PRs while preserving warnings for API and label-write failures and leaving the review marker intact ([#13857](https://github.com/hivecommons/hive/issues/13857)). +- The CI-poll stop nudge and its `ci_poll_nudge` self-report no longer fire for reviewer-lane agents, which read check status on the PRs they review as evidence rather than waiting on a PR of their own. +- The CI-poll guard no longer interrupts CI-maintainer lanes or reports their routine cross-repository workflow inspection as polling an owned PR ([#13898](https://github.com/hivecommons/hive/issues/13898)). +- Agent: 'failed to tighten …' interactive-home WARNs are now classified as agent_dir_setup_failed instead of unclassified (#13910). +- Review findings the backlog linker folded into another issue no longer vanish when that issue closes: every ten minutes, alongside the closed-issue stage sweep, the hive reads the `hive:review-backlog-link` comments on recently closed backlog hosts and re-files each still-unchecked `- [ ]` finding as its own backlog issue ("Split from #N (host closed)"), comments the new link on the host, and moves the finding's ledger and fingerprint records to the new issue. Hosts closed as not planned or duplicate keep the findings that match them and only split out unrelated ones; re-runs are idempotent via the new `split_keys` ledger entry keyed on the link-marker key ([#13914](https://github.com/hivecommons/hive/issues/13914), part of [#13906](https://github.com/hivecommons/hive/issues/13906)). +- Fleet report: 'prompt timeout — dumping pane' and 'pane content at timeout' agent-readiness diagnostic WARNs are now classified as agent_pane_timeout (low severity) instead of unclassified_error_repeated (#13920). +- Fleet report: repeated 'failed to ingest bead fact', 'fleet report: cleared comment failed' and 'failed to restore inference home mode' and 'failed to tighten inference home mode' WARNs are now classified instead of filed as unclassified_error_repeated (#13922, #13926, #13930, #13935). +- **Contributor quota guard now scopes to the active model's provider pool** (hivecommons/hive#13946). The contributor relay's quota guard evaluated every agy quota window regardless of which model the contributor actually runs, so an exhausted Claude/GPT (`3p-*`) window paused Gemini contributors that never draw from it. The guard now keeps only the windows of the effective model's pool (Gemini → `gemini-*`, Claude/GPT → `3p-*`); unknown models, non-agy backends and unrecognised window ids are still evaluated conservatively, and the hold message continues to name the triggering window. +- **Review-backlog hosts closed before the split sweep shipped are now split too** (hivecommons/hive#13947). The closed-host split sweep from #13914 only lists issues updated inside its 48h window, so a review-backlog host closed earlier (e.g. #13823, #13629) kept its still-unchecked folded findings closed with it. A one-off `BackfillReviewBacklogSplits` pass now runs after each split sweep: it walks the review-backlog ledger's host index, fetches each host directly and splits every closed one through the same idempotent path (ledger `split_keys`). Once a pass visits every host without hitting the per-pass cap or a transient error, the ledger records `split_backfilled` and later passes are no-ops. +- Policy denials logged by the request watchers (for example a repo not allowlisted for in-place review revision) are no longer self-reported as repeated unclassified runtime errors ([#13955](https://github.com/hivecommons/hive/issues/13955)). +- Contributor status and authentication hints now use named-instance syntax for Apptainer and Singularity, so the printed tmux attach command works with those runtimes ([#13976](https://github.com/hivecommons/hive/issues/13976)). +- A delegated decision no longer treats a competing contributor PR whose checks never ran or are still pending as mergeable ([#13986](https://github.com/hivecommons/hive/issues/13986)). +- Delegated decisions now compare real linked open PRs (including stage-store claim links) and use contributor commits, comments, and reviews within the configured presence window instead of park captions to detect absence; a competitor whose required checks are red is no longer treated as mergeable, and PR decisions fail closed until the dashboard snapshot exists ([#13986](https://github.com/hivecommons/hive/issues/13986)). +- Agent status snapshots now preserve CI waiting state, CI polling nudge counts, bootstrap overrides, kick refusals, and diagnostic errors. +- Evidence **Issue opens : PR merges** panel: a `?repo=`-filtered view now reads that repo's own governor cadence mode (`State.RepoModes`, under `cadence_scope: per_repo`) instead of always judging it against the fleet-wide mode, so a quiet repo inside a busy fleet is no longer read against the fleet's drain band; falls back to the fleet mode when the governor has no per-repo mode for it (#13992). +- Owner-delegate LLM decider: a model reply must carry its recording action (`comment-decision`, or `close-as-duplicate` for the close verdicts) so it can never lift `stage/085-needs-decision` with a bare `labels-remove`; `close-duplicate` closes only the newer item; verdict and actions are validated together so the job and audit log never record a verdict the executor did not carry out (follow-up to #14000). +- Delegated decisions now check the DCO sign-off and reporter-trust gates before preferring a competing PR, so a PR parked on either gate is no longer approved or superseded just because a duplicate exists (#14001). +- Contributor hubs whose GitHub App has no installation on the org (`installation_id: 0`) now refuse work with `app_not_installed` and a message naming the org and the App install link, instead of `repo_unmintable`; no GitHub request is made and no repository is excluded ([#14002](https://github.com/hivecommons/hive/issues/14002)). +- Exclude repositories with recorded token mint failures from contributor ready/actionable totals during their cooldown, expose the reason and expiry in opted-in withheld diagnostics, and preserve `repo_unmintable` refusals on subsequent work requests ([#14003](https://github.com/hivecommons/hive/issues/14003)). +- A hive whose policy directory predates the seed-manifest tracking no longer opens an `unclassified_error_repeated` self-report for the burst of once-per-template `policies: seeded policy differs from the embedded default with no seed record` warnings on its first post-upgrade reconcile; the per-path dedup added for [#13825](https://github.com/hivecommons/hive/issues/13825) only covered one file repeating over time, not many unrelated files warning once each in the same boot ([#14005](https://github.com/hivecommons/hive/issues/14005)). +- Review evidence no longer repeats the "could not write bundle" warning for every new head when a PR's evidence directory denies writes; it is logged once per PR directory ([#14008](https://github.com/hivecommons/hive/issues/14008), [#14009](https://github.com/hivecommons/hive/issues/14009)). +- Issue comments posted through the hive client no longer stay fenced forever after an ambiguous failure: an `issue_comment` operation journaled Unknown is now reconciled against the issue's existing comments (replayed as success when the comment landed, retried when it did not), and expired after `DefaultUnresolvedTTL` when the comments cannot be read, clearing the `effect_ledger_op_stuck` self-report ([#14011](https://github.com/hivecommons/hive/issues/14011)). +- A fleet-report cleared comment refused with 403 (a hosted hive's App cannot write to the fleet repo) is now journaled as a definite refusal instead of an uncertain outcome needing reconciliation, so it is given up once rather than re-warned every tick ([#14012](https://github.com/hivecommons/hive/issues/14012)). +- The fleet-report classifier now recognises the GitHub App "installation does not cover every configured repo" warning (new low-severity `github_app_repo_not_covered` class) and the `copilot sniff: client TLS handshake failed` line (now part of `proxy_tls_handshake_failed`), so they no longer surface as `unclassified_error_repeated` ([#14013](https://github.com/hivecommons/hive/issues/14013), [#14014](https://github.com/hivecommons/hive/issues/14014)). +- The CI-poll guard no longer reports a merge sweep or CI-repair pass that reads each of several PRs' checks once as polling an owned PR; only command lines repeated within a kick count toward the nudge threshold and the `ci_poll_nudge` self-report ([#14016](https://github.com/hivecommons/hive/issues/14016)). +- The auto-merge sweeps (self-authored, trusted-author, queued and contributor-lane) now record a `merge-queue-required` skip when a repository ruleset refuses the direct merge with "Changes must be made through the merge queue", instead of logging a `merge-failed` WARN every pass that surfaced as `unclassified_error_repeated` ([#14018](https://github.com/hivecommons/hive/issues/14018)). +- A hive whose copilot agents share a model id the Copilot CLI rejects no longer opens an `unclassified_error_repeated` self-report for the burst of `copilot CLI substituted the configured model` warnings; each agent already warns only once per substitution ([#13659](https://github.com/hivecommons/hive/issues/13659)), but many agents warning once each in the same boot crossed the repeat threshold. The substitution still shows on each agent's dashboard error and in the container log ([#14020](https://github.com/hivecommons/hive/issues/14020)). +- ioscan classifier: the "no model endpoint resolved" and "fail-closed blocked kick" warnings are logged once per condition instead of on every call, so a hive without an ioscan model endpoint no longer floods its log and the fleet self-report ([#14025](https://github.com/hivecommons/hive/issues/14025), [#14027](https://github.com/hivecommons/hive/issues/14027), [#14028](https://github.com/hivecommons/hive/issues/14028)). +- Stage-label provisioning stops retrying a repository GitHub reports as archived (403 "Repository was archived so is read-only"); the refusal is logged once with the remedy instead of on every sweep ([#14026](https://github.com/hivecommons/hive/issues/14026)). +- Fleet report: repeated `proxy: CONNECT dial failed` WARNs are now classified as `proxy_connect_dial_failed` (medium, component `github-proxy`) and `inference upstream failed` / `inference upstream error` ERRORs as `inference_upstream_error` (medium, component `inference-gateway`) instead of `unclassified_error_repeated`; the self-authored automerge sweep now logs `self-authored automerge sweep skipped PR` at WARN once per PR/reason/error and at Debug on later ticks ([#14031](https://github.com/hivecommons/hive/issues/14031), [#14038](https://github.com/hivecommons/hive/issues/14038), [#14042](https://github.com/hivecommons/hive/issues/14042)). +- Hosted hubs no longer repeat HTTP 403 warnings for the channel commit-date, channel-distance and SHA-poll commit-message GitHub fetches on every poll; repeats are logged at debug (#14033, #14034, #14040) +- The tool-less `claude` classifier backend now passes `--settings '{"disableAllHooks":true}'`, so hooks in the host's `~/.claude/settings.json` do not run in the classifier session ([#14062](https://github.com/hivecommons/hive/issues/14062)). +- CI-poll nudges no longer miss repeated polls of one PR when earlier reads have scrolled out of the 2000-line terminal capture (#14065) +- The self-authored auto-merge sweep now remembers a base branch that only accepts merges through GitHub's merge queue and stops re-issuing the refused direct merge on every pass, logging the `merge-queue-required` skip once per PR head instead of repeatedly ([#14068](https://github.com/hivecommons/hive/issues/14068)). +- Set NO_PROXY for loopback on every agent backend and stop warning when the proxy fails to forward to loopback (#14076) +- fix(dashboard): settings parity test matches whole paths, not substrings (#14080) +- Plain-forward proxy transport no longer honours HTTP_PROXY/HTTPS_PROXY on the proxy process, so the guarded destination check always evaluates the agent-named host (#14086) +- fix(close-on-merge): settle a referenced issue that GitHub reports as not found (404) as `issue_not_found` at Info instead of re-reading it every sweep and logging a WARN, which produced repeated `unclassified_error_repeated` self-reports (#14088, #14091) +- The GitLab forge adapter no longer reports a closed (unmerged) merge request as already merged: a closed MR is refused as not mergeable before any write, and a 406 from the accept endpoint is resolved against the re-read MR state. Follow-up to [#14151](https://github.com/hivecommons/hive/pull/14151) ([#14113](https://github.com/hivecommons/hive/issues/14113)). +- GitHub App token minting, installation verification and `InstallationID()` now read the installation ID under the auth lock, so adopting a discovered installation can no longer race a concurrent scoped-token mint or send a request with a torn ID ([#14123](https://github.com/hivecommons/hive/issues/14123)). +- CI: the sliced `test-hub` / `test-agent` lanes append the `ok <pkg>` / `FAIL <pkg>` summary line the coverage scorer classifies packages by, so a partial selection that includes `pkg/hub` or `crux/agent` no longer fails with "produced no test result" and their floors are scored on full runs again (#14135). +- The `crux-sync` workflow no longer aborts after committing the publish tree: the commit summary was piped through `head`, which under `pipefail` turned into exit 141 on a large first sync (#14138). +- `crux-sync` no longer commits when the only difference is the `.hive-sync` timestamp, so tag-only runs and re-dispatches do not add empty syncs (#14138). +- `crux-sync` tag runs (`crux/vX.Y.Z`) no longer commit to `hivecommons/crux` `main`; they tag the already-synced commit whose tree matches the tagged hive commit, fail clearly when none does, and refuse to overwrite an existing tag (#14138). +- `crux/hivecap`'s direct-vs-socket parity test used a fixed token expiry of 2026-10-25T14:00Z and began failing once that moment passed; it now uses a relative expiry (#14138). +- The Crux module's tests now pass when it is built standalone (the published `hivecommons/crux` copy): `crux/logscrub`'s relay secret-pattern parity test and `crux/agent`'s `deploy/entrypoint.sh` and `src/Dockerfile` checks skip when those hive-root files are absent instead of failing on a missing file; inside hive, `HIVE_TEST_REQUIRE_BEHAVIOURAL=1` still turns a missing file into a failure (#14138). +- SHA poller now backs off and logs once when a commit message can't be fetched (e.g. GitHub 403), and the fleet report classifies it (#14146) +- The automerge sweeps (queued, self-authored, trusted-author, contributor lane) and the close-on-merge ledger and backfill sweeps now skip repos whose `project.forge` / `project.repo_policies[].forge` resolves to GitLab or Gitea. Before, they looked those repos up on GitHub under the same slug ([#14150](https://github.com/hivecommons/hive/issues/14150), part of [#14096](https://github.com/hivecommons/hive/issues/14096)). Merging and closing on those forges is still to come. +- The supersession sweep's `needs-human` now clears with its cause: a contributor PR that only references the closed issue (`Refs #N`, `Part of #N`) is noted, not parked, and a park from an earlier pass is released when the supersession no longer holds (issue reopened, claim rewritten, reference-only link); a person's `needs-human` is left alone. The `stage/085-needs-decision` note names `needs-human` as the condition instead of "the lane condition named above" (#14155). +- A contributor websocket that ends without a close frame (code 1006 — relay killed, laptop slept, NAT timeout) is now logged at INFO as a dropped connection instead of a WARN `[contribute-ws] read error`, so routine contributor network drops no longer surface as `unclassified_error_repeated` fleet self-reports; close codes that name a protocol or policy problem still log at WARN ([#14163](https://github.com/hivecommons/hive/issues/14163)). +- Retiring the old `needs-decision` / `needs-direction` label definitions no longer logs a warning when its context deadline runs out: a timeout now defers quietly to the next cycle, and a pass whose caller's deadline is already spent makes no request (#14171). +- Unpark sweep and stage-label PR-link comments now skip repositories GitHub has archived (403 "Repository was archived so is read-only") instead of retrying and warning on every sweep tick (#14177, #14213). +- The fleet self-report feed no longer reports the contribute-ws "refusing task: contributor failure streak" warning as a repeated runtime error: the claim pause is a policy outcome re-logged on every poll from the paused agent, not a defect ([#14178](https://github.com/hivecommons/hive/issues/14178)). +- The CI-poll guard now exempts the quality lane's mandatory shared-CI baseline triage, alongside reviewer and CI-maintainer lanes, so cross-PR check reads do not trigger a stop-polling nudge or `ci_poll_nudge` self-report (#14188). +- **Blocked-on relations: state check before write, supersede re-targeting, and periodic sweep.** Posting a `hive:blocked-on` comment checks the target PR's state first and refuses to park on an already merged or closed PR (posting a verification note instead); closing a blocker as superseded re-targets relations to the replacement PR (or unblocks when the replacement is already merged); a periodic reconciliation sweep unblocks issues whose blocker merged or closed across cycles (#14194). +- fix(claims): a claim's GitHub side effects and the release of that same claim ran in independent goroutines, so a release that followed a slow claim re-read the issue before the claim's `hive/claimed-by-human` label had landed, skipped it, and the label was then applied onto an already-released issue — orphaned until a person noticed (hivecommons/hive#14065, 2026-10-25). The claim hooks now run one issue's transitions in ledger order; a release only reads the issue after its claim has finished writing. (#14216, fixes #14201) +- Agent claims clear a stale `hive/claimed-by-human` label when the latest human claim has a matching release marker, recovering from missed release label writes (#14239). +- Issue stage-label sweeps stop cleanly when their best-effort budget expires or the request pacer fails fast before the deadline instead of reporting a write failure for every unattempted issue; live-context request failures still warn once and unfinished work retries next cycle. PR sweeps also skip comments and adoption side effects for the unattempted batch tail. +- Fixed GitLab proxy repo scoping so nested group project paths (`group/sub/repo`) are no longer truncated to `group/sub`, both on `/api/v4/projects/...` and on git smart-HTTP pushes (`/group/sub/repo.git/git-receive-pack`, which previously extracted no repo and skipped the per-repo gates). The per-repo write gates (pause, agent scope, auto-merge, per-repo ACMM mode, repo filter) and the refusal audit entry now read a canonicalized form of the client's escaped path — every segment percent-decoded, with only `%2F` kept as the GitLab project separator — so `%2F`-encoded projects resolve exactly and neither escaped slug letters (`o%72g/repo`) nor escaped structural segments (`/r%65pos/`, `repo%2Egit`, `pro%6Aects`, `merg%65`) can slip past a pause, scope, allowlist or auto-merge entry. Git smart-HTTP slug extraction is also anchored to `info/refs`, `git-upload-pack` and `git-receive-pack`, so a `.git/` elsewhere in an API path no longer yields a bogus slug (#14250) +- `hive-open-pr` no longer folds a new PR into an open bot PR that is held, stalled, needs a rebase or has merge conflicts, since the hive cannot push to it; only the overlapping-files check skips such PRs, and a PR closing the same issue still counts as a duplicate (#14296). +- Dashboard feedback issue refresh: non-JSON (HTML) responses are reported with their HTTP status instead of a bare json decode error, and repeated failures back off instead of warning on every request (#14300). +- `claude` agents no longer stop on Claude Code's "WARNING: Claude Code running in Bypass Permissions mode" screen with "No, exit" selected. Hive seeds `skipDangerousModePermissionPrompt` into the shared Claude settings that `claude` agents read, so the screen does not appear. If it appears anyway, a kick selects "Yes, I accept" instead of restarting the CLI into the same screen, and the watcher's consent-stuck dismissal now covers `claude` agents as well as inference backends ([#14307](https://github.com/hivecommons/hive/issues/14307)). +- A wedged agent kick can no longer hold a hub-instructed self-upgrade for the full drain window. A kick whose turn-end signal never arrived stayed "in flight" forever, so the drain could never finish and every upgrade waited `hub.upgrade_drain_timeout_s` before it went ahead. Now a kick left unsettled for longer than the agent's `continuous_turn_ceiling` (45m by default, and also when the ceiling is unset or disabled) no longer counts toward the drain. Hive logs one warning per drain pass listing the wedged agents and kick ages, and the drain's deferred, timed-out and complete log lines list the ignored agents as `ignored_wedged` ([#14323](https://github.com/hivecommons/hive/issues/14323)). +- GitLab project paths with a subgroup or project named like a resource word (for example `group/packages/repo`) are documented as ambiguous in the unencoded spelling, with a test pinning the behaviour; nested-group git smart-HTTP pushes are covered by the repo filter tests (#14324, #14321). +- The dashboard's `jsonResponse`/`jsonError` no longer log a WARN when the client went away mid-response (broken pipe, connection reset, cancelled request, handler timeout); those are logged at DEBUG, and WARN is kept for genuine encode failures ([#14325](https://github.com/hivecommons/hive/issues/14325)). +- fix(agent): only selfreport ci_poll_nudge at 3+ CI polls so the kick's two-status-check allowance is not reported fleet-wide (#14327) +- The knowledge primer's "dropped facts over the byte cap" notice is now logged at INFO once per agent and cap (again only when the omitted fact count changes) and at DEBUG otherwise, instead of at WARN on every kick; the fleet self-report classifier already treats it as benign ([#14328](https://github.com/hivecommons/hive/issues/14328)). +- fix(ci-runners): bump pinned GitHub CLI to 2.103.2 (apt dropped 2.102.0) (#14341) +- An older, retracted `/hive decision` is no longer replayed after an issue is parked again; once a newer decision has been answered, earlier commands are treated as superseded (#14344). +- Expected per-agent GitHub hourly cap and soft-budget warnings no longer open repeated-error fleet self-reports; quota enforcement and diagnostic logs remain unchanged (#14346). +- Stale automerge `required_checks` configuration warnings remain visible in logs without generating repeated runtime-error self-reports; repository protection checks continue to govern merges. +- Issue-request consolidation no longer folds a finding into an open issue parked on a maintainer decision or owned by another `agent/<lane>`, and a consolidated result now reports `consolidated_reason` (`subject`, `file_set` or `component:<path>`) (#14360). +- The review swarm no longer deadlocks on verdicts whose `body_digest` or `head_sha` the reviewer miscopied, or when a PR's review runs out of redispatches ([#14361](https://github.com/hivecommons/hive/issues/14361)). The relay now stores every dispatched verdict under the head SHA and body digest its dispatch recorded, ignoring the reviewer's copy. Models had returned a prose summary, a `sha256:`-prefixed hash or a hash of something else. Each such verdict was filed apart from the PR's review, so its perspective never counted as delivered and its pending entry never cleared. Separately, under one review kick in flight per agent (#13794), every pending entry made its agent busy. That included entries an exhausted head deliberately keeps (so it is never re-kicked) and entries already past `pending_ttl` on a PR not yet reached this cycle. Three such PRs pinned every review head and the decision agent, and the swarm dispatched nothing for about 36 hours while every reviewer sat idle. Now only live entries (inside `pending_ttl`, on a head that is not exhausted) count as load. Pending entries naming agents the hive no longer runs (a replica or head removed by lowering `replicas`) are pruned so their perspective is asked again. An exhausted head is labelled with the `requires_human` verdict label instead of staying on `reviewing` indefinitely. Review prompts now tell reviewers to copy `head_sha` and `body_digest` verbatim or leave them out. `review.verdict_labels` fixes: a PR moving to a new state now loses its previous verdict label, even one the hive had already removed once. Before, the second removal was deduplicated as already done, so `hive-review/in-progress` and `hive-review/approved` could both show. A PR that merges or closes while carrying a verdict label now has it removed (at most 25 removals every 10 minutes). +- Repeated merge-request CI gate refusals remain visible in operator logs without generating spurious fleet runtime-defect reports (#14364). +- Pull request creation no longer refuses retries forever after an ambiguous GitHub failure; the unresolved op is reconciled against the open PR for the head branch (#14366) +- An agent the ACMM pack paused as "not in pack level N" is no longer resumed by the startup pack apply at that same level when an upgrade ships a pack that now lists it (e.g. `reviewer` joining the L2–L4 packs); it stays paused until the operator resumes it or explicitly re-applies the pack ([#14368](https://github.com/hivecommons/hive/issues/14368)). +- Classify timed-out Codex headroom probes as timeouts instead of unclassified closed-pipe or missing-response failures. +- Stop repeatedly retrying optional legacy decision label definition cleanup when GitHub denies the integration permission; retry after the client restarts. +- A burst of shadow-mode "shadow fence would have denied external mutation" warnings no longer files repeated runtime-error self-reports; the warning stays in logs and enforce-mode denials remain reportable. +- CI-poll self-reports now describe observed repeated CI-status commands and distinguish repeated reads from total reads, rather than claiming the agent was polling its own PR when PR ownership is unknown (#14384). +- Transient GitHub failures fetching PR review decisions no longer trigger repeated unclassified fleet defect reports; review decisions remain unknown until a successful poll. +- Spoke self-upgrades now raise stale startup probe thresholds to the hosted 10-minute budget in the same rollout, preventing older deployments from retaining the 160-second limit after upgrades (#14389). +- fix(entrypoint): keep the .codex/.gemini re-own off PID 1's startup path (#14390) +- hive-open-pr.sh stub-PATH test now provides dirname, which the script's SCRIPT_DIR line requires, so it passes on runner images that do not resolve it implicitly ([#14406](https://github.com/hivecommons/hive/issues/14406)). +- Hive Chat now answers agent questions instead of dumping the roster (#14409). `/agents stuck`, `/agents scanner status` and "Which agent completed last?" all used to return the identical 16-line agent list with a bare `BLOCKED` label and no reason. `/agents stuck|blocked|paused|running|idle|failed` now filter the roster, blocked agents carry the hive's recorded WHY (rate-limit cap, inference auth, policy stand-down, crash loop, failed starts) and since-when, `/agents <name> [status|why|last|history]` / `/agents status <name>` / "scanner status" return only that agent's card (state, block reason, current task, last completed turn and outcome, last kick, last PR/issue, restarts; unknown names list the valid agents), and natural-language questions — "which agent completed last", "what is scanner doing", "why is reviewer-2 blocked", "when did scanner last run", "which agents are idle" — go through a table-driven intent matcher. Unmatched agent questions reach the configured chat responder with the agent state attached rather than the roster. Bare `/agents` keeps the roster but appends the block reason inline. The reason and timestamp are exposed on `/api/status` `agents[]` as `blockedReason` / `blockedSince` (plus `kickOutcomeAt`) so chat and the Agents page agree. +- Spoke image self-upgrades reuse a single Deployment read for container images and startup probe backfill, avoiding a redundant Kubernetes API GET ([#14418](https://github.com/hivecommons/hive/issues/14418)). +- Backfill stale spoke startup probes when the Deployment already matches the requested image, without repeatedly restarting an in-flight rollout. +- Immediately remove PRs merged or closed by the hive from the stage tracker and governor snapshot, without waiting for a webhook or sweep ([#14420](https://github.com/hivecommons/hive/issues/14420)). +- Retry the pinned Pi coding-agent npm install in `Dockerfile.contributor` up to three times with a 30s delay, so a registry tarball that briefly 404s while a release propagates no longer fails the contributor image build. +- Stop reporting the expected post-restart kick hold (`failed to send kick` with `kick held after restart`, #7363) as an `unclassified_error_repeated` self-report; other kick send failures still report (#14422). +- Self-managed Kubernetes deployments and the manual provisioning template now allow the same ten-minute startup budget as hosted spokes, avoiding premature restarts during slow first boots. +- Hive Chat `/prs waiting on review` no longer lists pull requests whose review decision is changes requested; those wait on their author, not on a reviewer ([#14437](https://github.com/hivecommons/hive/issues/14437)). +- cmd/hive: the sidecar supervision boot test no longer hangs the test shard; waits are bounded. +- The adopted-PR stall escalation to `stage/085-needs-decision` ("adopted PR sits with nothing the hive can push") is now logged at INFO instead of WARN. It is designed behaviour (one stall note per PR), and the WARN made the `unclassified_error_repeated` classifier file fleet self-reports when several contributor PRs stalled together ([#14466](https://github.com/hivecommons/hive/issues/14466)). +- crux: the Makefile test note no longer points at a non-existent AGENTS.md; the tmux rule is stated inline with a link to hive's AGENTS.md ([#14468](https://github.com/hivecommons/hive/issues/14468)). +- Review backlog findings in files untouched by the reviewed PR are actionable immediately instead of waiting for that PR to close or merge. +- A relay resuming a task the hub holds no lease for (e.g. after a hub restart or lease expiry) is still told to re-ready, but the rejection is no longer logged as a repeated warning ([#14478](https://github.com/hivecommons/hive/issues/14478)). +- Adopted contributor PRs that were red only because of a shared-CI or base-branch flake fixed on the base since — their heads 15–22 commits behind `v5` with CI never re-run (hivecommons/hive#14430, #14440, #14456 after #14406 was fixed by #14415) — were escalated to `stage/085-needs-decision` as "nothing the hive can push". The 074 escape now tries one recovery first when the head's failing check is green on the base tip: it merges the base into the head (GitHub update-branch, also on a maintainer-editable fork) when the head is behind, or re-runs the failed workflow jobs when it is current, at most once per (head, base tip) and three times per adoption, recorded on the stage record; an escalation already in place for that head is released, and 085 waits until the attempt was made and the head is still red. One `adopted PR recovery` log line names the outcome (`update-branch`, `rerun-failed-jobs`, `skipped:<why>`) (hivecommons/hive#14500). +- Report runtime semantic classifier failures that withhold kicks in the dashboard ([#14509](https://github.com/hivecommons/hive/issues/14509)). +- fix(agent): document pacing-seam override rule (#14515) +- Fleet report: the pr-request watcher's repeated `head branch is not on the remote` ERROR is now classified as `pr_request_head_unpushed` (medium, component `github-relay`) instead of `unclassified_error_repeated` ([#14526](https://github.com/hivecommons/hive/issues/14526)). +- The hold guard's merge-from-base sync for held PRs is now pinned to the head it enumerated (`expected_head_sha`), so a contributor push landing mid-tick makes GitHub refuse the update instead of stacking the hive's base merge on unreviewed commits. A stale-head refusal is logged and skipped without a conflict notice, leaving the guard's baseline in place for the next drift check ([#14537](https://github.com/hivecommons/hive/issues/14537)). +- The activity-monitor merge gate now follows the live `sentinel-alert` label instead of the head's append-only sentinel evidence, so removing the label clears the "Sentinel alert · needs human" pill on the next tick; linked issues resolve their title and URL when the configured repo is a short name; and a trusted merger's approving review on a manual-merge lane (workflow path, tests removed, human-merge path) now routes the PR to `stage/090-ready-for-human-merge` with an "Awaiting human merge — approved by @login; click Merge" caption and comment instead of re-posting an open-ended needs-decision ([#14578](https://github.com/hivecommons/hive/issues/14578)). +- Held PRs now carry a body digest from the poll path, so review-swarm kicks for them name the digest and every head's verdict lands in one aggregate; a dispatched verdict whose dispatch record has no digest is stored with an empty digest instead of whatever the reviewer wrote ([#14594](https://github.com/hivecommons/hive/issues/14594)). +- A hive PR's pending fix now expires after 2h without a new head and is retried, and a posted decision request lands the PR in needs-decision instead of 070-fixing when it conflicts (#14604, #14607) +- Review-fix and relay fix-pr prompts now require Signed-off-by on every follow-up commit (#14605) +- The stage tracker now fetches a title and state for same-repo issues a PR links only softly (`refs`, title or mention references), so they no longer render as "(title unavailable)". Lookups are memoised per issue across tracker rebuilds and bounded per rebuild (at most 10 GETs within 3 s), so a status publish no longer re-queries GitHub while the tracker lock is held (#14606). +- **Weekly competitor report: renamed repos and engine relationship.** The 2026-10-27 report showed OpenHands' licence as "n/a (API error)" because the repository moved to `OpenHands/OpenHands` and the licence lookup did not follow the GitHub API's 301 redirect; the prompt now uses `curl -sL`, reads `full_name`, and names the current repository for each moved project (OpenHands, SWE-agent, Goose, OpenCode, archived Mentat and GPT-Engineer). The same report marked OpenHands "direct competitor" although Crux has an `openhands` backend; the prompt now states that any engine in the Crux `CLIBackends` list is "Hive runs it as a worker engine today" even when its vendor also sells orchestration. The gh-aw README records that the "Firewall blocked N domains" footer is an upstream gh-aw v0.89.21 false positive (github/gh-aw#63221, fixed in v0.89.22) (#14613). +- The self-report classifier now files the `ioscan classifier failed open` warning under `ioscan_classifier_unavailable` instead of as an unclassified repeated error ([#14620](https://github.com/hivecommons/hive/issues/14620)); the warning itself is already logged once per process. +- fix(ioscan): unavailable classifier must not consume the per-eval budget (#14629) +- The external-mutation boundary now gives each issue or pull request its own writer slot instead of one slot per repository, so label writes no longer queue behind a review, merge or comment on a different item; the per-target limit is configurable via `convergence.mutation.max_writers_per_target` (default 1) ([#14645](https://github.com/hivecommons/hive/issues/14645)). +- Agent transcript liveness scans now walk several agents in parallel and the slow-scan warning is classified, so hives with many agents no longer file it as an unclassified error ([#14649](https://github.com/hivecommons/hive/issues/14649)). +- **`weekly-competitor-report` now authenticates Copilot inference with the `COPILOT_GITHUB_TOKEN` secret instead of `permissions: copilot-requests: write`.** The first dispatch failed before the agent started with `awf-reflect: models fetch returned 403` because hivecommons has no Copilot seats assigned, so the org-billed Actions-token path is not authorized; the recompiled lock file now validates the PAT secret at activation and fails with a clear message if it is missing ([#14652](https://github.com/hivecommons/hive/issues/14652)). +- A hub project-config push that is refused for a misconfigured repo target is now logged at ERROR once per distinct misconfiguration instead of on every heartbeat ([#14661](https://github.com/hivecommons/hive/issues/14661)). +- Re-sign the contributor's commits when adopting a dco-missing PR, and make the fix kick for a no-dco adopted PR name the DCO re-sign first (#14666) +- The stage tracker no longer binds a PR to a sibling issue its first paragraph says it leaves for later (`#N … remain`, or a `#N` inside the parenthetical qualifying another reference such as `Part of #14550 (tracker; #14559 … remain)`), and drops links whose number is a pull request, open or closed (`Supersedes #N`), instead of drawing them as an issue "(title unavailable)" (#14667). +- A relay `fix-pr` task that fails right after dispatch is no longer reported as delivered: the stage-072 nudge comment says the relay could not take the task (with its reason), the fix is requeued with backoff and retried at the relay's next task boundary (three attempts before the re-nudge / adoption path takes over), and a conflicting contributor PR drops its stale `hive:unauthorized` mark so the conflict is the row's blocker ([#14668](https://github.com/hivecommons/hive/issues/14668)). +- **Weekly competitor report: curl was still refused.** Copilot CLI has a URL approval step separate from the shell tool allowlist and the firewall; without `--allow-url` every `curl <url>` was denied with "no one to approve", so run 40572955859 posted a partial report. The workflow now passes `--allow-url` for every host in `network.allowed` through `engine.args` (#14673). +- **Weekly competitor report records its Discord message ids.** The `post_to_discord` step posts each chunk with `?wait=true`, logs `Posted chunk N/M id=<id>`, writes the ids to the step summary and a `message_ids` step output, and appends them to the tracking-issue comment so a report can be deleted or replaced later (#14673). +- **Weekly competitor report content and search fixes.** The `weekly-competitor-report` gh-aw workflow's bash allowlist now uses `cmd:*` entries so `curl | jq` pipelines are permitted (Copilot CLI refused them before); DuckDuckGo is replaced by Google News and Bing News RSS plus HN Algolia; the prompt is grounded in what Hive and Crux ship; the "Who does what" table has category, relationship to Hive and SPDX licence columns; URLs are wrapped in `<...>` so Discord shows no link cards; SWOT filler is banned; a "Top 5 this week - stay ahead and stay integrated" section is added; and an `open_issues` dispatch input (default off) can file those items as `help wanted` issues (#14673). +- Dashboard no longer reports input/output token usage for bobshell sessions whose model calls all failed (e.g. a misconfigured model name). +- The ACMM level pack now places the reviewer on the inference gateway the operator moved the other agents onto from the dashboard, instead of leaving it on copilot (#14678). +- ACMM pack agents moved onto an inference gateway that has no default model now get the model the hive's other agents on that gateway run, instead of being left with no model, failing to start and being paused. +- A pack agent such as the L2 `reviewer` now follows the hive's inference gateway even when the operator's agents were put on that gateway without a `backend_owner` stamp (set in `hive.yaml`, on a hive older than ownership stamping, or via `POST /api/config/governor/agents`). Before, only operator-owned backends counted, so no gateway was found and the reviewer stayed on copilot. An unowned CLI backend still neither picks nor vetoes the gateway, and `POST /api/config/governor/agents` now stamps an explicitly named backend/model as operator-owned (#14678). +- Kubernetes Job sandboxes now receive the `env_allowlist` variables (with the same credential-name filter as Podman) instead of only `env_from_secrets` (#14691). +- Dashboard overview export no longer logs a warning when the client disconnects mid-download (#14696). +- Recording a review head's dispatched verdict now wakes the governor for an early cached-snapshot eval cycle, so the next head or the decision kick is dispatched right away instead of waiting for an unrelated webhook or `governor.eval_interval_webhook_s`; a burst of verdicts is coalesced to at most one wake per `governor.webhook_wake_min_gap_s` ([#14705](https://github.com/hivecommons/hive/issues/14705)). +- When ioscan fails closed and blocks a kick because the semantic classifier errored, the warning now names the underlying classifier error and the config to fix it (served classifier model/endpoint, `ioscan.classifier.enabled`, `ioscan.classifier.fail_mode`) instead of only "ioscan fail-closed blocked kick"; fail-closed stays the default (#14714). +- The automerge sweep now treats a 405 "review requesting changes" ruleset refusal like the other permanent review refusals, so a blocked PR is parked and remembered instead of logging a merge-failed WARN and retrying every sweep ([#14717](https://github.com/hivecommons/hive/issues/14717)). +- Pack apply now moves every late-added pack-owned CLI agent onto the hive's gateway when two or more operator-picked agents unanimously use it and most agents not waiting on the apply do too (#14721) +- Forward-merge PRs that are forced to a merge commit instead of a squash no longer raise a repeated unclassified runtime-error self-report ([#14727](https://github.com/hivecommons/hive/issues/14727)). +- Add opt-in `github.shared_uid_read_token` for App-authenticated shared-UID deployments, delivering refreshed read-only agent tokens so GitHub reads work without a personal login while writes continue through relays ([#14778](https://github.com/hivecommons/hive/issues/14778)). +- The scheduler's `ioscan fail-closed blocked held-PR coordination kick` warning is now classified as `ioscan_classifier_unavailable` instead of surfacing as `unclassified_error_repeated` ([#14742](https://github.com/hivecommons/hive/issues/14742)). +- The dashboard terminal now attaches to agents when the container runs as an arbitrary UID (e.g. OpenShift's restricted SCC) and agents share one tmux server: the attach helper looked for the default tmux socket only under dev's passwd uid (`/tmp/tmux-1001`), so it polled "waiting for agent to start" for every agent while all sessions were alive on `/tmp/tmux-<uid>/default`. It now checks the current uid's socket, dev's, and any other `tmux-*/default` under `$TMUX_TMPDIR`, picking the one that holds the requested session ([#14789](https://github.com/hivecommons/hive/issues/14789)). +- Keep superseded contributor PRs at the decision stage despite CI or rebase failures, show the closing PR and keep-open reason in the stage tracker, and let trusted maintainers close them with `/hive decision reject` or `/hive decision close superseded by #N`. Supplemental tests, docs and changelog files no longer block duplicate recommendations when implementation files overlap; held PRs remain visible without sweep writes, and closed issue snapshots cannot be offered as contributor work. +- A `pull_request` webhook now records the issues the PR claims (`Fixes #N`, branch name, references) into the duplicate-PR claim ledger and filters the cached actionable snapshot on the event, releases them when the PR is edited to drop them or closes unmerged, and converts them to merged claims on merge; the dispatch gate also refuses an issue the confirming read says is closed. Before, the PR→issue link was only made on the full reconcile pass (~1h apart on a busy spoke), so an owner PR opened with `Fixes #N` between passes left #N offerable and the `/contribute` lane handed it to a contributor minutes later ([#14814](https://github.com/hivecommons/hive/issues/14814)). +- Continuous agents receive due re-kicks between busy run-loop cycles without waiting for sweeps; busy kick deferrals no longer escalate continuous backoff or send more messages into the same agent lane ([#14820](https://github.com/hivecommons/hive/issues/14820)). +- Tracking/archive issues — label `hive/tracking`, body marker `<!-- hive:tracking -->`, or the sentence "Keep this issue open" — are no longer advertised as good-first-issue/help-wanted, are sidelined from the actionable set (`filtered`, reason `tracking`), are refused by every Hive close path including close-on-merge and the already-done sweep, and PRs that cite one with `Closes`/`Fixes` get a reviewer nudge; the weekly competitor report workflow now creates its tracking issue with the label and marker (hivecommons/hive#14826). +- Good-first-issue scoring counts size and help-wanted labels only when their latest application came from a verified human maintainer, preventing automation from endorsing its own advertisements (#14835). +- Governor: a delivered kick whose record is applied after the kicked turn already ended (a slower agent's lane ahead of it in the dispatch pass) no longer clears the continuous re-kick that turn end scheduled; `onDelivered` now carries the lane's delivery time and `RecordKickForRepoAt` keeps the schedule and stamps `LastKick` with the real delivery time, so continuous agents (scanner, reviewer-2 on the hosted spoke) stop idling until the turn-ceiling presumption. +- Sandboxed agents (`sandbox.runtime: job` or Podman) no longer render as "Stopped — see the agent's log" / "session down" with a red dot and empty TOKENS/SESSIONS between kicks. Their health now derives from the last run: green when it succeeded and the next cadence occurrence is still ahead, amber while a kick is in flight, red only when the last run failed/timed out or a scheduled occurrence was missed past a grace. Each run's outcome, summary and token usage are persisted under `<work_dir>/sandbox-runs/`, restored on restart, and ingested by the token collector so tokens, sessions, cost and the activity summary reflect sandboxed work. +- Issues managed by GitHub Agentic Workflows (any `<!-- gh-aw-… -->` body marker, the "automatically managed by GitHub Agentic Workflows" / "Do not close this issue manually" / "Do not assign to an agent" boilerplate, or the `agentic-workflows` label on an `[aw]` title) are now recognised as tracking issues without a `hive/tracking` label: they are no longer advertised as good-first-issue/help-wanted (labels already applied are withdrawn), are sidelined from the actionable set and the stage engine, are refused by every Hive close path, and `Closes #` references to them are downgraded to `Refs #`. hivecommons/hive#14646 "[aw] Detection Runs" sat in the Activity Monitor as actionable with `good first issue` for hours (hivecommons/hive#14919). +- Good-first-issue scoring now honours each repository's configured label-approval policy when checking who applied a size or help-wanted label, and logs a warning when that provenance lookup fails ([#14926](https://github.com/hivecommons/hive/issues/14926), [#14932](https://github.com/hivecommons/hive/issues/14932), [#14933](https://github.com/hivecommons/hive/issues/14933)). +- The Activity Monitor hover's "Trail:" clause names each hop by stage word (e.g. "CI / Review → Needs author → Needs human decision") instead of "undefined → undefined → …": the renderer read a `stage` field the `/api/stage-tracker` history entries never carried (they emit `number`/`slug`). Hops that cannot be named are left out and the clause is omitted when fewer than two remain ([#14928](https://github.com/hivecommons/hive/issues/14928)). +- Stale upgrade recovery preserves the original elapsed time when a release channel advances, so promotions cannot restart the silent-drain hold or postpone stuck-upgrade alerts. +- Headless contributor runs now report broken-environment verdicts as environment failures even when the CLI exits successfully, so unfinished issues can be reassigned instead of counted as completed. +- Activity Monitor: an issue the hive parked on a pull request (`<!-- hive:blocked-on pr=owner/repo#N -->`, the review backlog's spin-off issues) now names it — the payload carries `blocked_on_pr: {repo, number, url, state}` (state from the hive's caches, never a fresh GitHub call), the `blocked` pill reads `blocked on #N` and links the PR with a tooltip saying what lifts the block, and the caption reads `Blocked on PR #N` instead of `No stage recorded yet`. The hive's own `blocked` removal (blocked sweep, review-backlog block lift) now re-reads the issue live like an inbound label webhook, and a reconcile enumeration that started before such a re-read no longer overwrites it on publish — rows had stayed `blocked` for ~an hour after the hive itself lifted the label (#14952). +- Headless task failures now report the captured CLI output as evidence to the hub, so a failed headless task includes its final output (such as the verdict line) instead of an empty tail ([#14962](https://github.com/hivecommons/hive/issues/14962)). +- fix(gfi): apply the configured label-approval policy to GFI provenance and log lookup failures (#14963) +- The dashboard no longer marks an issue as Reviewing just because an open pull request mentions it: a PR found by search or by a timeline cross-reference counts as the linked PR only when its title or body closes the issue (Closes/Fixes/Resolves); a PR that names the issue only in a PR comment is still linked ([#14966](https://github.com/hivecommons/hive/issues/14966)). +- CI Go jobs (`v2-ci`, `v2-tests`, `go-security-analysis`, `testutil-guard`) now pre-fill the module cache through a shared `go-mod-download-retry` action that retries `go mod download` with exponential backoff, so a transient `proxy.golang.org` stream reset (`INTERNAL_ERROR`) no longer fails golangci-lint, govulncheck, gosec or the sharded tests; this completes the Docker builder-stage retry from #14990 ([#14976](https://github.com/hivecommons/hive/issues/14976)). +- Docker image builds now retry `go mod download` up to 3 times with short backoff, so a transient Go module proxy stream reset (`INTERNAL_ERROR`) no longer fails the build job (#14976). +- The Hive activity monitor's **Needs human** chip now counts and filters only rows a person alone can advance — stages 015/045/085/090, 071/072 with a human author, or a `needs-human` / `needs-decision` / `unauthorized` pill — from one predicate shared by the chip count, the filter, and the new `needs_human` / `on_hold` payload totals; held rows get their own **On hold** chip, and `hold`, `stalled`, `blocked`, handled regressions, covered 040 issues and auto-mergeable PRs no longer appear under Needs human. A hive PR that only references an issue (`Refs #N`, no closing keyword) is recorded as *addressing part of* the issue instead of *covering* it, in the relay, the claim-ledger backfill and the stage reason/caption; a bare cross-reference such as a shared-CI incident deferral never creates a covering relation ([#15008](https://github.com/hivecommons/hive/issues/15008)). +- A contributor PR with no linked issue no longer logs the "waits on the hive past the stage dwell — reviewer lane needs attention" warning; it is waiting on a person, not the reviewer lane (#15009) +- A busy hive whose reviewer lane is backed up no longer files a repeated unclassified runtime-error self-report for the one-shot "PR waits on the hive past the stage dwell" warning; the condition stays in the log and the dashboard's hive-held count ([#15009](https://github.com/hivecommons/hive/issues/15009)). +- Inference requests inherit a configured gateway default when the agent model is blank; if both are blank, Hive rejects the request locally and shows an actionable model configuration error instead of repeatedly sending an empty model to the provider ([#15032](https://github.com/hivecommons/hive/issues/15032)). +- Fast delegated decisions now settle their operator-action ledger entries reliably instead of leaving the activity monitor badge pending forever ([#15064](https://github.com/hivecommons/hive/issues/15064)). +- Inference requests canceled by the caller no longer report a backend failure or count against gateway health. (#15083) +- Inception uses its local knowledge wiki without warning about an unconfigured remote project endpoint, while retaining warnings for configured endpoint failures ([#15098](https://github.com/hivecommons/hive/issues/15098)). +- The merge-eligible list no longer includes contributor PRs the merge relay's contributor-lane policy refuses (for example newcomer-tier authors), so agents stop wasting a `hive merge` attempt on them every kick ([#15093](https://github.com/hivecommons/hive/issues/15093), [#15129](https://github.com/hivecommons/hive/pull/15129)). +- Rebase-then-merge refuses workflow-changing fork rebases before dispatching a fixer push the App cannot complete, and asks for a human rebase instead of timing out ([#15133](https://github.com/hivecommons/hive/issues/15133)). +- Close issues fixed by contributor PRs merged by the hive, including merges into non-default release branches, so covered-by-PR stage labels and activity rows do not remain stale ([#15148](https://github.com/hivecommons/hive/issues/15148)). +- Clear blockers when issues close through GitHub or the hive, so closed issues no longer inflate the capabilities blocked-item count ([#15155](https://github.com/hivecommons/hive/issues/15155)). +- Contributor PRs skipped for missing or unverified claims and other admission failures no longer read as waiting on the hive reviewer or trigger its dwell warning; running checks still count as waiting on the hive ([#15164](https://github.com/hivecommons/hive/issues/15164)). +- Dashboard evidence heartbeat refreshes now use the evidence root captured when the heartbeat starts, preventing a background data race when the default root changes ([#15169](https://github.com/hivecommons/hive/issues/15169)). +- fix(crux): make shared-pool watcher tests deterministic (#15172) +- *Let hive decide* on an untrusted author's PR at *Ready for human merge* now decides instead of answering "I can't merge this": a reviewed, green, mergeable PR is approved for the merge sweep to merge under its own number, and only a red, conflicting or unreviewed PR is adopted; the ✓ hover names the path and reason (#15173) +- fix(crux): split oversized files under the mirror's file-size ratchet and gate src/crux in hive CI (#15207) +- Re-adopting a pull request after the hive closed its earlier copy now merges the base branch into the new copy again, so the fresh copy no longer opens with the conflict the first adoption had resolved ([#15225](https://github.com/hivecommons/hive/issues/15225)). +- The dashboard's review-evidence loader no longer falls back to the package-wide evidence root from a background goroutine; every caller already resolves the root before loading, so behaviour is unchanged and a blanked root can no longer reintroduce the data race fixed earlier ([#15258](https://github.com/hivecommons/hive/issues/15258)). +- The Activity Monitor's merged toasts now render above the chat button: the `--z-merge-banner` / `--z-cue-flight` layer tokens were scoped to the section while the toast stack mounts on `<body>`, so the stack had no z-index and the chat FAB covered the lowest toast's close × and truncated its text ([#15288](https://github.com/hivecommons/hive/issues/15288)). +- Clarify that Overview counts open issues and PRs while the Hive activity monitor counts rows, showing how many PRs stand alone or share an issue row. +- The fleet self-report feed's diagnostics excerpt is now bounded at 4096 bytes instead of 512: the `agent-runtime` "pane content at timeout" warning logs a `head_500` attribute before `tail_500`, and at the old cap `head_500` alone (worse with multi-byte box-drawing characters) filled the budget and silently dropped `tail_500` — the pane's current state and the only field useful for diagnosing a stuck CLI — every time the warning fired. Self-reports for `agent_pane_timeout` now carry a usable excerpt ([#15311](https://github.com/hivecommons/hive/issues/15311), [#14586](https://github.com/hivecommons/hive/issues/14586)). +- The repeated-error feed no longer files the "kick undeliverable; busy-no-activity restart not yet attempted, not self-reporting" warning as a fleet issue; kicks that keep failing after the stall restart are still reported ([#15313](https://github.com/hivecommons/hive/issues/15313)). +- Fixed stale `src/pkg/` source citations in labels-and-control-signals.md and security-model.md that now point at `src/crux/` (#15318). +- Bound crash and consent-screen recovery before agent kicks with the shared restart-storm breaker, backing off repeated failures and pausing agents at the storm limit instead of restarting indefinitely. +- Repeated inference translator caller-identification refusals now report as `inference_caller_unidentified` under the inference gateway, with medium severity, instead of `unclassified_error_repeated`; the HTTP 401 identity guard remains enforced (#15333). +- fix: stop retrying shared-ci reruns the App may not perform (#15339) +- Restart-storm self-reports now carry the restart count in the window, the recent restart reasons and the agent's last error instead of repeating the title, so a paused crash loop can be triaged from the issue (hivecommons/hive#15342). +- Re-engagement kicks deferred by a busy shared CLI session pool remain in local logs without generating repeated runtime-error self-reports; undelivered kicks still consume no repair budget. +- Defer remaining PR-claim link work after GitHub rate limits and log the expected retry without triggering repeated-error self-reports. +- The issue stage-label sweep no longer emits one `PR issue-link safeguard failed` WARN per (issue, PR) pair while GitHub's secondary rate limit is active. The first rate-limited PR lookup pauses the safeguard for the rest of the sweep and one summary line records it, so the self-report feed stops filing `unclassified_error_repeated` fleet issues for it ([#15359](https://github.com/hivecommons/hive/issues/15359)). +- Downgrade expected GitHub rate-limit errors during PR claim label reconciliation to informational logs. +- Stop filing `unclassified_error_repeated` self-reports for GitHub 502/503/504 transient failures (e.g. the self-authored automerge sweep's `fetch-pr` skip); the caller retries on its next tick and the WARN stays in local logs ([#15365](https://github.com/hivecommons/hive/issues/15365)). +- Avoid reporting transient GitHub gateway failures embedded in log messages as repeated runtime errors. +- Log lines that merely mention "bad gateway", "service unavailable" or "gateway timeout" in prose are no longer classified as GitHub upstream-unavailable errors; only the `: <status>` forms match (#15370). +- A contributor review gate no longer emits repeated warnings before the first verdict exists; missing verdicts still prevent automatic approval. +- Path globs with a `**/` prefix and a second glob character, such as `**/*luks*` or `files/**/*luks*`, now match by basename at any depth instead of silently matching nothing. The shared matcher backs `intent.guardrail_path_patterns`, `auto_merge.human_merge_paths` and `sentinel.sensitive_paths`, so those gates were disarmed for such patterns; `**/*.ext` patterns behave as before ([#15386](https://github.com/hivecommons/hive/issues/15386)). +- The selfreport classifier now recognises the proxy's `plain HTTP forward refused — destination is not globally routable` WARN as its own log-fed class, `proxy_plain_forward_refused`, instead of letting repeats fall into the generic `unclassified_error_repeated` issue. The refusal is an expected policy decision (a client ignored its proxy bypass for a private address) and is still counted as a violation. (#15391) +- The queued auto-merge lane now remembers GitHub's "required status checks are expected" merge refusal per head, like the other lanes, instead of re-PUTting the merge every sweep pass and logging a false merge-failed ([#15419](https://github.com/hivecommons/hive/issues/15419)). +- Fix the tracker holder tooltip to identify local claims as coming from the claim ledger. +- Agents now bypass the hive proxy for the host of `OMP_AUTH_BROKER_URL` (added to `NO_PROXY`), so a credential broker on a private address such as the Docker bridge gateway is no longer refused by the plain-forward guard and the agent CLI no longer exits on start ([#15432](https://github.com/hivecommons/hive/issues/15432)). +- A combined review head's fan-out now splits the shared grounding tool-call budget across its per-perspective sub-agents instead of leaving each to read the whole-review cap as its own. +- fix(dashboard): share the PR link → lineage → base-pill assembly between tracker row renderers; correct the tracker.css shrink-priority comment (#15447, #15451) +- A kick ref withheld because the GitHub API budget is critical or the rate-limit caution window is engaged is now logged at INFO instead of WARN, so the designed back-off no longer files an `unclassified_error_repeated` self-report ([#15465](https://github.com/hivecommons/hive/issues/15465)). +- fix(hotspot): stop proposing source splits for generated files whose source is already split (#15471) +- Cache the dashboard tracker’s unfiltered issue closer once per issue and exclude the carrying PR per row, preserving correct sibling links without extra lookups. This defensively preserves correct links if merged PR rows are included; current open-only tracker behavior is unchanged ([#15495](https://github.com/hivecommons/hive/issues/15495)). +- Fix an extra separator before the base branch in dashboard issue rows when PR lineage is empty. +- Isolate TestFetchWebhookItemSnapshot_ClassifiesForGovernor from rate-limit caution left by earlier tests ([#15535](https://github.com/hivecommons/hive/issues/15535)). +- Dashboard settings help marks for the auto-merge, label-driven approval, sentinel, GitHub API budget and Delivery SLA settings now open the operator-reference section that explains them instead of the index page. +- A review-heads decision verdict no longer records as an advisory, undecided report when other review kicks in the same pass are delivered first, so the decision is not left to expire and run again; a verdict that falls back to advisory despite its agent having dispatch rows for the PR now logs the rows it was compared with ([#15559](https://github.com/hivecommons/hive/issues/15559)). +- The "review dispatch promoted" warning is now logged once per PR while it stays promoted instead of every cycle, so it no longer trips the repeated-unclassified-error self-report ([#15578](https://github.com/hivecommons/hive/issues/15578)). +- Activity tracker: the lit chevron no longer says "Merge queued · 1st" for a PR whose CI is still running or whose review verdict is pending ([#15580](https://github.com/hivecommons/hive/issues/15580)). The headline is stage-first ("CI / Review"), the merge-train slot becomes a trailing suffix ("· queued 1st once ready") until the PR reaches merge-ready, the gate reason reads "merges first once it is ready", and the server marks such train members `merge_train.provisional: true`. +- Empty-diff autoclose head age is floored at the PR's `created_at`, so a PR just opened from an old branch keeps its just-opened grace period, and a head already on the base is measured from its own commit date rather than the label-bumped `updated_at` ([#15603](https://github.com/hivecommons/hive/issues/15603)) +- When an issue has multiple merged same-repository pull request references, Hive now selects the most recently merged closer instead of depending on GitHub's node order ([#15606](https://github.com/hivecommons/hive/issues/15606)). +- The Activity Monitor's "Merge failed" chevron is scoped to the head GitHub refused: once the PR head moves (merge-from-base, new push) or the record falls back below 080 to wait on CI after the refusal, the chevron reads the live stage word and the refusal survives only as the hover note "merge attempt on previous head failed: branch protection", so the chevron and its caption never disagree about whether a merge is failing now ([#15611](https://github.com/hivecommons/hive/issues/15611)). +- A kick withheld because every ref failed the freshness check is now reported under its own fleet-report class instead of the generic unclassified-error class ([#15622](https://github.com/hivecommons/hive/issues/15622)). +- Dashboard: the scroll-edge fade at the bottom of scrollable dialog bodies (Settings and other long modals) now follows the theme — in light mode it fades to the light panel surface instead of painting a dark band over the last visible row; dark mode is unchanged ([#15625](https://github.com/hivecommons/hive/issues/15625)). +- The merge-hotspot advisor now caps the modularize issues it keeps open per repo (`governor.hotspot_max_open`, default 2; issues with a PR in flight still count) and files at most `governor.hotspot_max_per_pass` (default 1) per pass, filing the next-ranked hotspot only when a slot frees instead of opening five refactor issues in one pass ([#15682](https://github.com/hivecommons/hive/issues/15682)). +- Label descriptions Hive writes to GitHub now fit the 100-character cap: the over-long `origin/governor`, `origin/selfreport` and `has-open-pr` descriptions were shortened and every label create/edit clamps the description, so `CreateIssue` no longer logs `could not ensure label … 422 description is too long` and drops the `origin/*` provenance label ([#15683](https://github.com/hivecommons/hive/issues/15683), [#15681](https://github.com/hivecommons/hive/issues/15681)). +- fix: page through every closing PR reference when picking the latest merged closer (#15687) +- Already-landed auto-close now posts its "this issue is done" note only after the issue close goes through, so an issue that CloseIssue's tracking-issue or reporter-confirmation gate keeps open no longer carries a misleading note ([#15689](https://github.com/hivecommons/hive/issues/15689)) +- A stage/072 row under `maintainer_policy: never` no longer claims `hive adopts it in Nm` right up to the due moment for a maintainer's own PR, only to flip to `not adopted: maintainer_policy is never`: the engine does not read the author's repository permission until adoption is due, so the tracker names the exception (`unless the author maintains this repository`) instead of promising an outcome it cannot back for every author. +- The stage pass now posts the merge-commit note only after the `merge-method/merge` label actually landed; when the write-back gate keeps the hive's labels off a contributor PR, the election is refused with that reason and the PR takes the attribution fallback (re-home, or the stage/085 note naming the gate) instead of being told "nobody needs to act" while the squash-attribution check stays red ([#15710](https://github.com/hivecommons/hive/issues/15710)). +- The already-landed close now covers any author's PR, not only the hive's own: when the diff against the base is empty and a merged PR provably carries the change (the reviewer named it and it is merged, the linked issue was closed by a merged PR, or the head is contained in the base) the PR is closed as superseded with thanks instead of parking at 085 for a person; trusted authors are treated the same, and the "Let hive decide" preview gives the empty diff and the merged landing as its reason rather than the author's trust ([#15732](https://github.com/hivecommons/hive/issues/15732)) +- A stage/072 row under `maintainer_policy: ask` no longer claims `hive adopts it in Nm` right up to the due moment for a maintainer's own PR, only to flip to `adopt?`: the engine does not read the author's repository permission until adoption is due, so the tracker names the exception (`unless the author maintains this repository, then it asks`), the same hedge `never` got in #15738. +- Hive-authored PRs whose review fix dispatch is refused with `fix-attempts-exhausted` now move from `stage/070-fixing` to `stage/085-needs-decision` (reason `fixer-exhausted:<N>`) with a `fixer gave up after N attempts — <reviewer finding>` caption, a once-per-head decision comment and **Re-author** as the tracker's lead action; a 070 row no longer claims `Fixing · @bot` while no fix job is dispatched, a stale answered decision no longer clears `stage/stalled` while the fixer is excluded and the head is unchanged, and the `review fix dispatch excluded` warning is logged once per PR head instead of every cycle ([#15744](https://github.com/hivecommons/hive/issues/15744)). +- A recorded operator decision (dashboard Approve, `/hive decision …`) now follows a hive-authored PR onto the head the hive's own `require_current_base` refresh produced — a merge of the base by the App that leaves the PR's diff identical — so the reviewer route reads `decision_answered=true` instead of re-parking the PR at `stage/085-needs-decision`, and the review gate and hold guard accept the carried approval. Any other head change still supersedes the decision ([#15751](https://github.com/hivecommons/hive/issues/15751)). +- The stage tracker's "Hive:" note for a soaking PR no longer re-stamps itself every eval pass. The contributor lane records the soak head, start and window once on the stage record and reports the stable reason `contributor-lane:soaking`; the dashboard computes the time left from that deadline at request time (showing `soak complete — merges on the next pass` at the deadline instead of `0s left`), sends an explicit `note_changed_at`, and the SPA refreshes the countdown in place rather than opening a new line. `LastSeen` no longer counts as a record change and is persisted at most once per 10 minutes. Records written with the old `contributor-lane:soaking(remaining=…)` reason stay readable (#15758). +- Fixed the reconcile (enumerate) pass being starved by wake-driven cached cycles: a wake whose cached snapshot is older than the effective eval interval now enumerates, and the loop runs an owed reconcile pass regardless of which channel woke it, so the snapshot can no longer age for an hour while the ticker tick loses to webhook, verdict and re-kick wakes. The stage tracker's "since" for an issue the blocked sweep just unblocked now restarts at the lift instead of counting from issue creation ([#15779](https://github.com/hivecommons/hive/issues/15779)). +- Activity monitor: "⟳ Mergeable · merging now ⬡" no longer lingers for minutes — the sweep clock now marks only the PR actually under evaluation, and a merge call that returns patches the cached snapshot and nudges the SPA at once, so the row reaches ✓ within one poll. Every hive-performed merge (trusted-author, self-authored, contributor and stage-engine lanes alike) celebrates exactly once — toast with the PR number, bee flight, odometer +1 after landing — even when the row vanished before the SPA saw the merged state (reconciled by `recently_merged` / `recently_closed` on removal) — a merge whose row is not on the board (below the fold, filtered, already evicted; #15707) now flies its bee from the toast's ✓ to the counter instead of skipping bee and odometer; a row that vanishes because its PR was closed, not merged, shows a neutral "#N closed · <reason>" toast instead of disappearing silently. The merge-gate "Merging · merge landed" bridge is now a ceiling, not a fixed delay: `dashboard.stage_tracker.merged_hold_s` (default `8`, min `3`), with the celebration launching as soon as the merged fact arrives; a merge call or sweep in flight for over 60 s reads "merging · waiting for GitHub…" ([#15808](https://github.com/hivecommons/hive/issues/15808)). +- Repeated inference messages are no longer self-reported as `unclassified_error_repeated`: spending-limit refusals are benign because the budget notice and kick withholding already cover them ([#15809](https://github.com/hivecommons/hive/issues/15809)), the kick manager's own provider-error backoff is benign ([#15843](https://github.com/hivecommons/hive/issues/15843)), and `inference translate request failed` now lands under `inference_upstream_error` ([#15840](https://github.com/hivecommons/hive/issues/15840)). +- Review verdicts that land after a PR head moved are now accepted against the current head when the reviewer reviewed the live head or the new head is the same patch (rebase/merge-from-base), reviewer-role agents bind to a sibling reviewer's dispatch row, in-flight dispatch rows follow same-patch head moves instead of being re-dispatched, reviewer slots go to merge-ready PRs first (then starved heads, then age; pending-CI heads only with spare capacity, `priority` in the dispatch log), and the audit kick preview skips the security-canary preamble so operators see the real work ([#15823](https://github.com/hivecommons/hive/issues/15823)) +- The merge train now seats only PRs whose current head is green with every required review verdict recorded, mergeable and not held; a PR short of that is a candidate without a position and never the front. A member whose head moves, whose CI goes pending or red, who owes a verdict again or who conflicts is ejected on the next evaluation (`merge train: member ejected pr=N why=…`), the next ready member fronts, and the ejected PR re-enters at the back once ready. The stage engine and the Activity Monitor keep such PRs below stage 080 — in the CI / Review column, never the Merge queue column — with a caption naming what is owed and a gray "left merge train" lineage pill. A member being rebased shows "Rebasing · attempt 1/2" in the CI / Review column; the train header counts seated members only; a seated row always names its seat rather than "Ready for auto merge · checking now", which now applies only to the PR the sweep is evaluating ([#15825](https://github.com/hivecommons/hive/issues/15825)). +- The Governor RUNNING tile no longer shows a stray dot between "$" and the amount ("$.1,010") or clips the cost window label: the host's text-overflow ellipsis was being painted under the "$" when the agent count plus the cost rotor overflowed the tile. The tile is now a flex row whose rotor shrinks and ellipsizes on its own, window labels are shorter ("this hr", "today", "this wk", "this mo"), and the today / week / month amounts round to whole dollars while the hour window keeps cents ([#15826](https://github.com/hivecommons/hive/issues/15826)). +- Activity monitor merge notifications survive reloads without replaying delivered merges, resolve audit events for vanished rows, and cancel their countdown when evicted from the banner stack. +- dashboard: merge banners drain the toast countdown bar (#15880) +- CEL trigger rules on `issue.opened` and `pr.opened` now match each issue or PR once per hive process instead of re-kicking the agent every eval cycle. +- celtrigger: fire issue.opened and pr.opened once per item (#15889) +- dashboard: point operator-reference help marks at the section sub-pages (#15890) +- fix: tighten a pre-existing base-preparation directory to the intended mode (#15897) +- Tool approval now flags `rm -rf /..`, `rm -rf /./`, `rm -rf /./*` and `rm -rf ~/.` as destructive, matching the documented root/home spellings (#15952) +- The built-in destructive-command check now reads `rm` arguments the way `rm` does, so `rm -rf --no-preserve-root /` (the spelling GNU rm actually executes against the root), `rm -rf -- /`, `rm --recursive --force /`, `rm -r --force ~` and `rm -rfv /` are flagged like `rm -rf /` instead of passing clean to the host text scanner ([#15961](https://github.com/hivecommons/hive/issues/15961)). Option order, long options and `--` no longer matter; ordinary subpaths (`rm -rf -- /tmp/x`) and non-recursive `rm` still pass. +- Matrix lines that look like short `key=value` secrets (for example `password: hunter2`) are now dropped, and `Server.Close` now stops the Matrix line source goroutine (#15971, #15972). +- Matrix `GET /api/matrix/lines` now applies `max` after per-repo allowlist filtering, so paging with `max` no longer returns empty pages (and stalls) when the oldest lines in the window belong to repos the caller cannot see. +- fix: resolve sentinel repo privacy from the repository record (#15980) +- The display-mode 🔗 Copy link control now keeps `density=tv` and `shift=1`, so a wall screen opened with `?display=1&density=tv&shift=1` no longer loses its TV layout and burn-in shift when the link is copied; the flags are rendering-only, so no token or cookie can ride along (#15983). +- Removing a hive from the hub registry now also drops its in-memory activity digest instead of keeping it for up to 24 hours (#16002). +- A heartbeat racing a hive delete can no longer re-insert an activity digest after the hive was forgotten; the digest is now recorded and purged under the same registry lock ([#16010](https://github.com/hivecommons/hive/issues/16010)). +- An adopted (or otherwise hive-owned) conflicting PR no longer sits on "Rebasing · attempt 1/2" while the fixer is busy: each rebase attempt is routed once and gets `governor.labels.stage.adoption.rebase_attempt_timeout` (default 15m) to push before it counts as failed and the next attempt is dispatched, the row shows the wait ("Rebasing · attempt 1/2 · waiting for scanner 12m"), and an in-place adoption whose attempts are spent re-homes to a hive-owned superseding PR at once instead of after the 3h dwell ([#16023](https://github.com/hivecommons/hive/issues/16023)). +- `hive-open-issue` requests that declare `--parent` or `--blocked-by` are no longer folded into an older open issue on a shared file path, component or canonical title stem, and the create's idempotency replay keys on the exact title so same-stem siblings citing one file each get their own issue; a genuine create reports `consolidation_skipped_reason` (`parent` or `blocked_by`) and the watcher logs the skip (#16065). +- A declared DAG request (`--parent`/`--blocked-by`) now still reuses an open review-backlog issue whose title differs only by the leading agent tag, instead of filing a duplicate (#16074). +- Self-upgrade drain now logs a single warning per pass listing every wedged agent kick it is ignoring, instead of one identical-keyed warning per agent. The fleet self-report feed keys WARNs on the message alone, so a hive with many wedged lanes was tripping a spurious `unclassified_error_repeated` report ([#16079](https://github.com/hivecommons/hive/issues/16079)). +- RFC lifecycle notices now recognise an RFC issue whose title carries the RFC marker inside a leading bracketed tag (for example `📝 [v5 RFC] ...`), so newly opened RFCs written that way are posted to the RFC Discord channel and get a thread ([#16090](https://github.com/hivecommons/hive/issues/16090)). +- RFC duplicate detection now ignores leading bracketed title tags such as `[v5 RFC]` or `[v6]`, so `📝 [v5 RFC] Foo` and `RFC: [v5] Foo` are recognised as duplicates of `RFC: Foo` by the same author. +- **A wedged tmux server can no longer stall the whole governor tick through the watchdog** ([#16097](https://github.com/hivecommons/hive/issues/16097)). `watchdog.Reconciler.Tick` runs inline in the steady-state governor loop on the promise that every probe carries a deadline, but `WatchdogFleet.Observe` shelled out to `tmux has-session` and `tmux capture-pane` with no timeout — so one agent's hung tmux server (socket accepted, never answering) froze the eval cycle, rotation, automerge sweep and state persistence until tmux recovered or hive restarted, and shutdown could not interrupt it. Observe's tmux probes now share a short deadline (`agent.ObserveProbeTimeout`, 5s); a probe that times out reports the agent as unobservable for that sweep (never as "no session", which would trigger a restart), and `Tick` stops early once its context is cancelled. The `watchdog.Source` interface is unchanged. +- Expected hold-guard refusals for branches changed while held no longer generate repeated runtime-error fleet reports; local warnings and merge safety remain unchanged. +- The "merge train stalled" log line now repeats at most once per hour per stuck head PR, instead of once per planner train ID, so one stalled head no longer floods the log or files a repeated-error self-report ([#16107](https://github.com/hivecommons/hive/issues/16107)). +- The anonymous `/api/hub/activity/public` view is now built and marshalled at most once per 2-second window per parsed filter and shared by concurrent requests: query strings that parse to the default view (`?x=1`, `?hive=`) share its entry, filtered views live in a small bounded cache, builds are serialised so anonymous callers can drive at most one at a time, the ETag comes from the cached body so conditional requests return 304 without a rebuild, and toggling a hive's visibility drops the cache so a hive made private disappears at once (#16111). +- Sentinel findings on pull requests no longer generate repeated runtime-error fleet reports; the local warning and the PR alert remain unchanged, and sentinel sweep failures stay reportable. +- Throughput card: the Actor attribution matrix's Reviewed row now counts reviews people and other bots submit (human and other columns), read once per PR by the merged-PR settle scan when the PR merges or closes and recorded as `pr_review_observed` at each review's `submitted_at`; the hive's own reviews are not double-counted and each review counts once across rescans and restarts (#16116) +- The public activity cache is now invalidated when a hive is deleted ([#16117](https://github.com/hivecommons/hive/issues/16117)). Previously, deleted public hives remained visible in the anonymous `/api/hub/activity/public` endpoint for up to 2 seconds (the cache TTL) instead of disappearing immediately. +- The `min_head_age` merge gate no longer stalls green merges for an hour when GitHub's server-generated timestamps (`created_at`/`updated_at`/`pushed_at`) run ahead of the host clock. A head time in the future is treated as clock skew: instead of clamping to "head pushed 0s ago" for the whole skew, the automerge sweep and the `hive-merge` CI gate measure the hold from the host-clock time they first observed the head (`pending: head time ahead of host clock; head first seen … ago (< min_head_age)`), so slow check-runs are still held for one `min_head_age` window and the hold then clears. Heads whose age is zero or positive still wait as before ([#16143](https://github.com/hivecommons/hive/issues/16143)). +- Pushbroker newline normalisation now amends the normalised HEAD blob instead of the working-tree file, so uncommitted edits are never folded into the commit; staged edits to those paths are left unstaged after the amend. Broker git invocations now return stdout only on success (stderr is appended only on failure) and drop inherited `GIT_TRACE*`, so git warnings cannot be committed as file content (#16144, #16145) +- The merge-request CI gate now clears the min_head_age hold one window after it first sees a head whose GitHub timestamp is ahead of the host clock even when the merge request omits `expect_sha`, and both merge paths log when a head time is ahead of the host clock so a skew-handled head is distinguishable from a normally aged one. +- `hive-open-pr --issues 0` is now refused at the script (GitHub numbers issues from 1, so a `0` is the `<N>` placeholder left unsubstituted), and the pr-request watcher rejects a request that still declares `#0` by naming the placeholder as the cause instead of saying the body "never references" it — a remedy no re-run could satisfy, which had an agent retrying into five policy rejections in ten minutes ([#16162](https://github.com/hivecommons/hive/issues/16162)) +- Crux: `settledAt`, `since` and `expires_at` are now omitted from JSON when zero instead of serialising `0001-01-01T00:00:00Z` (#16165). +- Fleet report: an agent with no inference model configured (neither an agent model nor a gateway `default_model`) no longer self-reports `inference_upstream_error` — the inference translator now logs the refusal at WARN as `inference model not configured; request refused`, which the fleet report treats as an operator configuration condition; the agent's dashboard `LastError` still names the remedy, and other translation failures stay ERRORs under `inference_upstream_error` ([#16170](https://github.com/hivecommons/hive/issues/16170)). +- `toolapprove` now denies recursive `rm` of the filesystem root written with backslash escapes (`rm -rf \/`, `rm -rf /\*`), matching the quoted spellings it already caught; `\$HOME` and `\~` stay literal and allowed ([#16174](https://github.com/hivecommons/hive/issues/16174)). +- `toolapprove` now reads every backslash escape in an `rm` command word, option or target the way the shell does, so the alias-bypass `\rm -rf \/`, the escaped-dot root `rm -rf /\.` and the escaped or quoted options `rm \-rf /` and `rm "-rf" /` are denied like `rm -rf /`; `\$HOME` and `\~` stay literal and allowed ([#16176](https://github.com/hivecommons/hive/issues/16176)). +- `crux --server` / `CRUX_SERVER` now keep a URL path prefix (e.g. `https://ops.example/crux`) instead of silently dropping it; a query string or userinfo in the address is rejected with an error (#16186) +- The signed-commit reconciler now gives up on a PR head after GitHub refuses to sign it (a 4xx such as the 422 on the scratch ref) on three consecutive passes and posts its skip note once, with a remedy that fits (push a new head), instead of retrying and re-logging the same error every pass; a 5xx or network failure is still retried every pass (#16193). +- Made the proxy C3 terminal-authorization tests hermetic so ambient `HIVE_*` keys and ingress settings on a host no longer cause spurious 401 failures ([#16194](https://github.com/hivecommons/hive/issues/16194)). +- fix(pushbroker): the trailing-blank-line normaliser now keeps an agent's staged (index) state for a touched path. `git add` of the normalised blob used to replace the staged entry, so an uncommitted edit the agent had already staged came back on disk but silently unstaged; the broker now snapshots the index entry and puts it back with `git update-index --cacheinfo` after the amend (#16158, #16196). +- The automerge sweep now logs the "install the ok-to-test workflow" approval warning once per PR head instead of every tick ([#16199](https://github.com/hivecommons/hive/issues/16199)). +- Proxy test suite: `startProxy()` now spawns the proxy with `hermeticEnv()` so ambient `HIVE_*` auth vars on the runner cannot flip `IS_HOSTED` for the main suite ([#16203](https://github.com/hivecommons/hive/issues/16203)). +- fix(github): note signed-reconciler refusal path in errMissingHead doc (#16207) +- A relay that echoes a stale task generation on `task_progress` is now told to release the task (`task_revoke`) instead of being silently fenced, so a relay that missed its revoke stops reporting and the hub stops logging the repeated "stale-generation task_progress rejected" warning ([#16218](https://github.com/hivecommons/hive/issues/16218)). +- On Linux, permissions watcher chown/chmod errors now name the entry's path instead of its `/proc/self/fd/N` link, so operator greps on the `error` field match the `path` field and the #4488 once-at-WARN dedupe keys on a stable path ([#4488](https://github.com/hivecommons/hive/issues/4488)). +- The merge-request watcher now treats GitHub's "Changes must be made through the merge queue" 405 as terminal: it stops retrying the direct merge and logs one classified message per PR head instead of repeated warnings. (#16229) +- The spoke's hub activity digest (and Battle Log / Hive of the Week) now treats a public hive's own project repos as public again: config loading strips the org off `project.repos` and `primary_repo`, and the public repo set rejected the bare names, so every item was marked private and the hub's public fleet view showed "0 items" for every hive ([#16234](https://github.com/hivecommons/hive/issues/16234)). +- The sentinel's patch observation now names the repository as `owner/name` instead of the configured slug (a bare name once config loading strips the org), so `dashboard.matrix.repos` entries match and the Matrix view receives pushed lines instead of waiting forever; the repo privacy fallback lookup uses the same owner/name ([#16235](https://github.com/hivecommons/hive/issues/16235)). +- Merged-PR claim scan timeouts are now treated as transient and logged once per repo instead of a repeated warning on every tick (#16244) +- fix(toolapprove): treat positional parameters and empty substitutions glued to protected paths as protected targets (#16245, #16320) +- Hive-authored draft PRs carrying only prow's `do-not-merge/work-in-progress` mirror label are no longer filtered as "Exempt label" before the stale-draft rule runs, so deferred drafts surface in the scanner's "YOUR STALE DRAFT PRs" section instead of deadlocking with their `covered_by_open_pr` issue (#16246). +- All hive:status comment writers go through one serialised writer with compare-and-retry and duplicate reconciliation, so concurrent writers no longer lose sections or create duplicate status comments (#16263). +- Stop the permissions watcher from re-logging an unfixable (EPERM) chmod of bob's `.bob` state dir at ERROR every pass: skip dirs owned by another uid, and warn once with an ownership hint. +- Open-PR guard bounds its listing deadline and backs off per repo after a failure, logging a classified reason once per window (#16287) +- The copilot transcript activity scan overrun warning is now debounced: it fires once after three consecutive passes longer than the scan interval and re-arms only after a pass under 80% of it, so a marginal overrun on a many-agent hive no longer logs a WARN every ~25s and trips the fleet report ([#16292](https://github.com/hivecommons/hive/issues/16292)). +- Agent launch commands never emit a bare `--model` for an empty model: the flag is omitted (or falls back to `litellm.default_model` when LiteLLM is configured, with a one-time WARN), a launch-time check drops a dangling `--model` that would swallow the next flag, and the kick path now recognises Claude Code permission dialogs ("Read outside the working directories?"), auto-answers them when the agent runs with `--dangerously-skip-permissions`, and reports `CLI blocked on permission dialog: <dialog>` instead of "did not reach input prompt" ([#16295](https://github.com/hivecommons/hive/issues/16295)). +- Merge-queue-required refusals now raise an operator dashboard alert: `quarantineMergeQueueRequired` calls `raiseMergeFailureAlert`, and `classifyMergeFailureForOperator` gains a `merge-queue-required` category telling the operator to enqueue the PR via the merge queue, merge by hand, or drop the rule. Previously the 405 "Changes must be made through the merge queue" was only logged at INFO and never surfaced (#16322). +- fix(attention): release the episode store lock during GitHub delivery calls and prune resolved items so the ledger never fails closed (#16327, #16332) +- fix(automerge): route the engine status-comment create through the tagged notification primitive (#16344) +- `prstatus.Write` now edits only hive-authored status comments: a status marker pasted by a person is merged from but left in place, and a new hive-owned comment is created when none exists ([#16345](https://github.com/hivecommons/hive/issues/16345)). +- fix(prstatus): only treat status comments by this hive's own App login as editable or deletable (#16348) +- fix(github): a merge-queue-required operator alert now clears on its own once the base branch's rules no longer include a merge queue, instead of lingering until the PR closes (#16350) +- The post-merge refs sweep no longer treats an unreadable `hive:status` card as "no card": when the comments API call fails or returns something other than a JSON list of comments, `.github/scripts/hive-status-card.sh` now reports an error (exit 3) instead of absence, `upsert` writes nothing, and the sweep skips that issue with an `::error::` annotation and a non-zero exit rather than posting a possible duplicate note ([#16363](https://github.com/hivecommons/hive/issues/16363)). +- Reconciling a stuck GitHub label mutation (e.g. removing issue-claim labels) no longer fails with "context deadline exceeded" when the preceding read used up the attempt budget, so the claim retry loop stops repeating "op:… is Planned" until the entry ages out. +- Route normal-mode PR stage notes through the canary gate and effects journal used by other issue comments. +- The `stage/085-needs-decision` entry comment is no longer posted again on the same head when a different automerge lane observes the PR; maintainers get one explanation per decision ([#16405](https://github.com/hivecommons/hive/issues/16405)). +- Large task prompts (such as ~55 KB donated standby prompts) are no longer lost on claude relays: prompts over 8192 bytes are pasted through a tmux buffer, and a prompt that still cannot be delivered is reported to the hub as `task_failed` (#16423). +- The process-wide webhook tracker is now swapped and read atomically, removing a data race that failed `TestClosedDeliveryEvictsWithWebhookRefreshDisabled` under `-race` when a refresher flush from an earlier test was still reading it ([#16429](https://github.com/hivecommons/hive/issues/16429)). +- A spoke that boots from the ConfigMap seed (runtime overlay moved aside or missing) no longer drops `review.require_labels`, `project.paused_repos`, `writeback.per_repo` or `project.issue_filter.require_labels` in silence: each gate a previous overlay on the PVC carried that the effective config lacks or loosens is logged as `WARN safety gate dropped` with its previous value, listed in `/api/status` as `config.gate_regressions`, and shown as a Settings banner; `config.refuse_gate_regression: true` refuses to start instead. +- Fixed `manual-provisioning.md` to name the `hive.hivecommons.dev/*` namespace identity labels and annotation the hub actually stamps, instead of the legacy `hive.kubestellar.io/*` keys (#16459). +- The Activity Monitor tracker strip now shows a flask glyph for the CI track and keeps the eye for the Review track, so the two adjacent chevrons are no longer identical ([#16472](https://github.com/hivecommons/hive/issues/16472)). +- Activity Monitor CI track captions now explain themselves in plain language — `CI waiting · required check "test" hasn't reported for this head yet`, `CI running · 3/5 checks done`, `CI failing · "lint" red`, `CI green · all 3 required checks passed` — and each carries a longer explanation in the chevron tooltip via a new `detail` field; the fix-task CI-wait and CI-retry captions were reworded the same way ([#16479](https://github.com/hivecommons/hive/issues/16479)). +- The activity monitor no longer shows a decomposed parent issue that is waiting on open child issues as a stuck *Actionable* row "waiting for the scanner to pick it up": the lit step reads `Tracking · 3/4` (or `Tracking · N open children`), the caption and actor name the open children, and the item carries `open_children` ([#16481](https://github.com/hivecommons/hive/issues/16481)). +- Activity monitor tracker rows are compact again: the stage chevrons sit directly under the title line as a one-line (~20px) strip, the issue title stays inline after its chips instead of dropping to its own line, the row toolbar pills share that first line, and row padding is tightened — roughly 60px per simple row as before the two-line chevron budget ([#16485](https://github.com/hivecommons/hive/issues/16485)). +- The inference translator's "unidentified caller refused" warning now records why the caller was unidentified (no UID map, unresolved socket, or unmapped UID), the socket owner UID, and whether an `x-api-key` was sent; the refusal itself is unchanged ([#16474](https://github.com/hivecommons/hive/issues/16474)). +- The Activity Monitor's CI and Review chevrons now show counts instead of a bare glyph or a muted tint: `CI 12/14 passed`, `CI 11/14 · 1 failing (lint)`, `CI 0/14 · queued`, `Review 3/5 perspectives`, `Review 5/5 approved`, `Review 0/5 · re-review pending (new head)`. A track in progress on the current head wears the full active fill (both may be lit at once — the counts disambiguate, and the tooltip says which one the hive is waiting on), a finished track wears the done style, a red check or changes-requested verdict wears the error colour, and only a not-yet-started track is a glyph alone. The server now reports `checks_passed/total/failed/failing` and `perspectives_done/total` on every CI/Review activity ([#16493](https://github.com/hivecommons/hive/issues/16493)). +- Contributor assignments that race with an already-sent WebSocket close frame still release their undelivered claim, but now log at INFO instead of triggering repeated-error self-reports. +- Bound spoke cluster-health collection with a shared deadline so slow Kubernetes APIs return partial health reports without exhausting the hub heartbeat collection budget ([#16501](https://github.com/hivecommons/hive/issues/16501)). +- Heartbeat loops no longer accumulate blocked full or fresh-stats collectors after repeated collection timeouts; fallback liveness beats continue, and timeout self-reports include the slowest collector sections. +- Stop filing duplicate unclassified self-reports for the hub heartbeat's last-good cached stats fallback; retain local warnings and fleet reporting of collector timeouts, slow collectors, and heartbeat failures ([#16507](https://github.com/hivecommons/hive/issues/16507)). +- The claim-release valve no longer drops a covered issue to `stage/010-actionable` while the hive is still repairing its red covering PR ([#16522](https://github.com/hivecommons/hive/issues/16522)). A red+stale PR releases its issue only once the fix loop has given up on that head: escalated to a human, re-engagement budget spent, or red for the whole re-engagement window (`escalation.ClaimReleaseAfter`) with no owner reachable. Until then the issue stays `stage/040-covered-by-pr` narrating the PR's `070-fixing`, and the scanner is not offered work a live PR already owns. +- Add opt-in ordered fixer fallback agents, configurable in Settings, so review fixes and stale red-PR repairs can bypass an undeliverable primary without interrupting its turn ([#16536](https://github.com/hivecommons/hive/issues/16536)). +- Deferred PR fix kicks now retain their queue position until delivery or closure; the governor API exposes the queue and the dashboard review queue shows “fixer queued, N ahead” ([#16537](https://github.com/hivecommons/hive/issues/16537)). +- The code activity reader now accepts unchanged diff context lines (`op: ' '`) from a regions source and renders them in a neutral color with their space prefix, instead of dropping the whole region; the current published-checkpoint source still emits only `+`/`-` lines ([#16550](https://github.com/hivecommons/hive/issues/16550)). +- Activity Monitor stage chevrons are a one-line band again on phones and touch tablets; the chevron's info wrapper no longer inherits the 40px tap-target floor (and ring) that made every chevron a 44px box ([#16551](https://github.com/hivecommons/hive/issues/16551)). +- The Activity Monitor keeps the CI track lit on a 071/072 row whose pushed or checking head has checks running, instead of muting it as waiting on the contributor ([#16552](https://github.com/hivecommons/hive/issues/16552)). +- Stage controller: an issue a maintainer already decided (`approved-direction`) whose remaining work is human-only (`needs-human`) is no longer re-parked on `stage/045-needs-decision` with the ack stripped; it keeps `approved-direction` and is held out of the pipeline, ending the decide → re-park bounce loop; a newer, different `/hive decision` still lets an agent's park through and clears the stale ack ([#16579](https://github.com/hivecommons/hive/issues/16579)). +- Activity Monitor: a sign-off question naming `@clubanderson-bot` or `@clubandersonx` no longer reads "needs your sign-off" to the viewer `clubanderson`; the viewer's handle is matched on a word boundary. +- The automerge sweep reuses the stored re-author target on retry passes instead of fetching the exhausted PR's closing issue from GitHub each pass ([#16586](https://github.com/hivecommons/hive/issues/16586)). +- Stop-polling nudges no longer leave a `ci_poll_nudge` fleet report marked unrecovered: the next kick after a nudge now closes it as self-recovered, so the report stops accusing a healthy agent of being stuck ([#16588](https://github.com/hivecommons/hive/issues/16588)). +- The un-park sweep no longer posts the "What to reply" notice or the `/hive approve` hint on an issue held after a human decision (`needs-human` + `approved-direction`, no stage/045), while still answering `/hive decision`, `/hive help` and `/fixed` on it ([#16591](https://github.com/hivecommons/hive/issues/16591)). +- fix(github): log expected author self-approval verdict refusals at INFO instead of WARN so they no longer surface in repeated-error self-reports (#16605) +- Keep a not-yet-run current-phase CI/Review chevron visibly filled (#16625) +- Merged ledger writes no longer fail with "rename ... no such file or directory" when two writers race on the same temp file (#16629). +- Hub SHA poller backs off all commit-message fetches on a 403/429 and warns once per throttle window instead of once per SHA, so a rate-limited token no longer trips the `sha_poll_commit_message_unavailable` fleet report ([#16649](https://github.com/hivecommons/hive/issues/16649)). +- Opening a hosted hive from the hub when the hive cannot verify the hub's single sign-on now shows the "Sign-in didn't complete" page with a GitHub sign-in button, instead of being replaced by the gateway's "Hive is restarting" outage page ([#16652](https://github.com/hivecommons/hive/issues/16652)). +- Label the narrow dashboard's navigation drawer button so operators can find sidebar sections and version details without guessing what the menu icon does (#16654). +- API reference now lists the check-count and perspective fields of stage-tracker activity observations ([#16670](https://github.com/hivecommons/hive/issues/16670)). +- Clarify the `StageTrackerActivity` source documentation: CI activity uses the resolved required checks when branch protection is known, otherwise all check runs observed on the head. This corrects the description without changing runtime behavior ([#16674](https://github.com/hivecommons/hive/pull/16674)). +- In-place DCO repair no longer appends the App's Signed-off-by to a collaborator's unsigned commit on a hive-authored PR: only commits GitHub links to the App bot or a hive identity are re-signed, and a hive-authored PR carrying anyone else's unsigned commit waits for a person instead ([#16685](https://github.com/hivecommons/hive/issues/16685)). +- Honor ntfy Retry-After deadlines and use bounded exponential cooldowns after HTTP 429 without a usable header, while Slack and Discord delivery continue independently. +- All five quality policies distinguish prohibited work discovery from merged PR history reads, which remain conditional on wrapper and tier permissions ([#16700](https://github.com/hivecommons/hive/issues/16700), [#16715](https://github.com/hivecommons/hive/issues/16715)). +- A DCO split cached while no `project.ai_author` was configured is no longer treated as computed with the hive identity, so configuring it later re-reads the commits for in-flight heads ([#16707](https://github.com/hivecommons/hive/issues/16707)). +- A stale hive-identity DCO marker is now cleared when a new head is cached App-only, so re-adding `ai_author` after removing it re-reads the commit check instead of serving the App-only split ([#16710](https://github.com/hivecommons/hive/issues/16710)). +- Kick headers now describe merged PR history reads as conditional on wrapper and tier permissions while preserving governor-supplied work and discovery restrictions ([#16714](https://github.com/hivecommons/hive/issues/16714)). +- Staff agents can now list a repo's merged pull requests with `gh pr list --state merged` (any `--json` fields, no `--search`). Before, the gh wrapper refused every `gh pr list` from a non-contributor agent, so ci-maintainer could not run a repo's own agent-audit script (`gh pr list --state merged --json … | node scripts/ai-audit-report.mjs`) and parked "open the run summary and say which PR it flags" for the owner. Merged PRs are not work to pick, and the same set was already readable through `gh search prs --merged` and a GET of `repos/<owner>/<repo>/pulls`. Open, closed, all and `--search` listings stay refused, and the refusal now names the reads that still work. +- Contributor PRs with hive attribution now pass the merge relay's trust gate before being listed merge-eligible; trust refusals appear separately with their reason and maintainer unblock options ([#16717](https://github.com/hivecommons/hive/issues/16717)). +- Decouple the crux sidecar probe deadline from the poll interval so a fast test ticker no longer reports a live `crux serve` as unreachable (#16721). +- Clarify gateway model reconciliation logs by distinguishing the old model from the selected gateway model. +- Preserve pack-owned gateway models when runtime model overrides are lost and the gateway has no default model. +- Workflow auto-approval now retries a PR head on the next sweep when the approve call fails transiently (5xx, network error, cancellation, or a rate-limit `403`) instead of silently spending the head's single approval pass, and no longer trusts this hive's App as triggering actor on fork heads, since a public App installed on a fork pushes with the same bot login ([#16739](https://github.com/hivecommons/hive/issues/16739), [#16743](https://github.com/hivecommons/hive/issues/16743)). +- Pack agents added at higher ACMM levels keep the hive's inference gateway and model after runtime overrides are lost ([#16740](https://github.com/hivecommons/hive/issues/16740)). +- The `prow/lgtm` status warning comment is posted once per PR with its own live context instead of retrying on an expired one (#16753) +- Corrected the `bindProwLgtm` comment to describe returned reporting errors and best-effort warnings; runtime behavior is unchanged (#16761). +- Stage-label check digest no longer files a fleet self-report when GitHub answers the combined-status read with a 500 (#16778) +- Classify the issue-activity collector's REST reserve shedding ("github REST budget below reserve") as GitHub rate limiting so fleet reports no longer file it as a fetch failure; the local WARN logs and real fetch-failure reports are unchanged. +- Routine inference prose-only action nudges no longer trigger unclassified runtime-error self-reports; local warning logs and nudge counters remain unchanged. +- ACMM pack agents (such as strategist) now get their per-agent user, private group and pre-created token cache when the level comes from the config's `acmm_level` or the persisted hive state, not only from `HIVE_LEVEL`, so they no longer fall back to the shared full-privilege token ([#16803](https://github.com/hivecommons/hive/issues/16803)). +- The dashboard no longer shows an obsolete superseded-upgrade notice after a later roll; it shows the running commit and its age instead. +- A tooling-failure blocked verdict now releases the `blocked` label only when the hive applied it; a human-applied `blocked` label is left in place ([#16841](https://github.com/hivecommons/hive/issues/16841)). +- The self-report feed no longer files a GitHub 5xx on the review-request watcher's review POST (retried with backoff by design) as an unclassified repeated error; 4xx and non-5xx failures stay reportable (#16844). +- The ntfy rate-limit cooldown now caps a server-sent `Retry-After` at the same one-hour ceiling the fallback backoff already uses. Before, a single 429 carrying a large value (a day, a year) set a deadline the cooldown logic never shortens, so ntfy notifications were silently dropped until the process restarted; the default server is the public ntfy.sh, so that value was not under the operator's control (#16871). +- `crux.frontmatter.Split` now recognises front matter blocks in files that start with a UTF-8 byte-order mark (BOM), fixing silent loss of `skills:` metadata in AGENTS.md and skill files written by Windows Notepad or PowerShell (#16878) +- Stabilize inception question categories and IDs for list labels containing multiple category keywords by preferring the longest match and breaking ties lexicographically ([#16882](https://github.com/hivecommons/hive/issues/16882)). +- The documentation for disabled `/mcp/knowledge` now correctly describes the response codes: anonymous callers receive 401, and authenticated callers receive 404 ([#16916](https://github.com/hivecommons/hive/issues/16916)). +- A hive without `project.org` no longer reports its repos as `/name` in the dashboard status ([#16917](https://github.com/hivecommons/hive/issues/16917)). +- Defensive guard: the dashboard PR-queue repo check and kick-message repo list no longer join `org + "/" + repo` when `project.org` is empty, so they cannot emit `/repo`. Such a config is still rejected by the validator at startup; the guard only hardens the two remaining join sites ([#16923](https://github.com/hivecommons/hive/issues/16923)). +- `native-queue-policy` no longer spends its ~22-minute evidence wait on label flips it never reads (`size/*`, `dco-signoff`, `hive/claimed-by-*`, `copilot`, stage labels); instead it replays the latest successful `native-queue-policy` run on the same head rather than fabricating a pass, still applies the live hold/draft/head-move check, and falls through to the full exact-head evidence wait when there is no prior success to replay (the head was never evaluated, or the last wait failed or timed out) or GitHub returns a 5xx, so a stale red verdict is never pinned onto later cosmetic flips. Flips of `hold`, `needs-human`, `release-in-progress` and `do-not-merge` always run the full wait ([#16945](https://github.com/hivecommons/hive/issues/16945)). +- A self-report relayed through the hub now joins an open `hive/selfreport` issue of the same keyworded class instead of filing a new one when its message differs from the existing issue's, matching what spokes posting directly already did; an operator now gets one issue per class per defect rather than one per message, as when one spoke's `ioscan_classifier_unavailable` produced two issues five minutes apart; classes without keywords still never join by class alone ([#16954](https://github.com/hivecommons/hive/issues/16954), [#16955](https://github.com/hivecommons/hive/issues/16955)). +- The push broker's outgoing-diff gate now consults every exact-shape credential pattern `logscrub` knows — the hive canary marker, GitHub tokens, JWTs, AWS access keys, Slack and Discord webhook URLs, Slack tokens and private-key blocks — through the new `logscrub.FindSecret`, instead of only the GitHub-token/JWT `TokenPattern`. A committed AWS key, private key or planted canary used to be brokered and published; it is now refused, and the error names the category (`contains a private-key-shaped secret`) without echoing the value. The heuristic shapes `ScrubString` masks in logs (`sk-…` keys, `Bearer …`, `Basic …`) stay out of the gate because they match fixtures and documentation too readily to block a push on (#16966). +- fix(dashboard): merged-ledger test is deterministic across the UTC midnight boundary (#16972) +- Automerge stage reconciler: prevent stage oscillation on PRs parked at `stage/085-needs-decision` by preserving 085 against pending check-runs re-triggered on the same head without a human decision or new push, and add a per-(repo, number, head) transition dampener in `stagelabels.Store` that caps rapid transitions between two stages within 30 minutes ([#16974](https://github.com/hivecommons/hive/issues/16974)). +- Agent panes that show hive's own login-pattern source or grep output (for example `file.go:NN: "Please run /login"`) are no longer misread as a login screen, so reviewers that read loginscan/watchdog code stop raising a false "needs login" banner; the watchdog also only checks the bottom of the pane for login prompts ([#17006](https://github.com/hivecommons/hive/issues/17006)). +- Dashboard GitHub login requests **no** OAuth scope again — #11051 had switched the device flow to `public_repo`, which pushed every viewer through GitHub's "read and write repository data" consent page just to look at a hive. Dashboard feedback no longer files the issue with any hive-held credential: the hive stores the diagnostic bundle on a `hive-feedback` branch using its GitHub App installation token and opens a prefilled `issues/new` page (summary ≤ 6 KB plus a link to the bundle) that the user submits as themselves. Operator PATs still never author feedback. A source-level guard test keeps the login path scope-free ([#1927](https://github.com/hivecommons/hive/issues/1927)). +- Activity Monitor "Accept triage" now moves the issue to 010 Actionable in the same request: the handler writes `stage/010-actionable` alongside `triage/accepted` when the issue has no stage label or wears `stage/015-triage-needed` (never regressing a later stage, never on a held issue), and the tracker no longer reads an issue carrying `triage/accepted` with no stage label as 000-new while waiting for the engine's next pass. +- Recognize install, boot, and explicitly named E2E GitHub Actions workflows in the ACMM E2E prerequisite, retaining web/configuration and directory alternatives without treating unrelated CI workflows as E2E coverage. +- Activity monitor: stage chevrons are again only as tall as their caption (one line of text → a one-line chevron, two lines → two, never more) with the caption centred instead of flush-left in a fixed two-line box, and the CI / Review lanes are notched chevrons like the other stages (state shown by fill and text colour) rather than bordered boxes. +- Hive activity monitor: a PR whose closing reference names an already-closed issue (a superseded PR whose body still says `Fixes #N`) no longer shows a bare `#N` in its issue slot. The issue's title is rendered struck through with a `closed` chip — `(closed issue)` when no title is available — and a number-only reference is completed by the eval cycle from the forgestate cache or one issue read per issue, memoised for 24 hours, never once per cycle. +- The hub activity event ring now also drops any event held longer than 24 hours, so a low-volume hive that keeps heartbeating no longer keeps old events in hub memory indefinitely after the fair-share eviction change ([#16072](https://github.com/hivecommons/hive/issues/16072)). +- The fleet-wide activity event ring now evicts the oldest event of the hive holding the most events, so one spoke can no longer evict every other hive's events ([#16050](https://github.com/hivecommons/hive/issues/16050)). +- Restore activity issue/PR header spans and far-right action controls; keep truthful current-phase highlights across parallel CI/Review, wrap all chevrons within two lines with complete hover/keyboard details, show unknown track states as icons rather than verbose panels, and label observed PR remediation “Remediating” without renaming native states or implying work during waits. +- Activity Monitor: the "Needs human decision" popover now opens on an issue row whose one covering PR is parked for a decision (stage 085); the trigger was keyed on the issue instead of the PR, so clicking or hovering did nothing. +- Activity monitor: "Needs human: …", "Current blocker", "Next move", "Claimed by" and optional-delegation lines under an item are hive notes again — they open, tuck left into the ⬡ icon after the same 30 s as other hive notes, re-open on click, and a re-render never re-opens a line the tab already showed. The row's Let hive decide / Sentinel alert controls still carry the decision state. #16011 had drawn these as static rows that never left. +- The merge sweep now re-runs cancelled or failed workflow jobs (or refreshes the branch) on an operator-approved contributor PR whose only blocker is a red check that is green on the base, instead of standing down from adoption and nudging the fork author to push a new head for a shared-CI flake they cannot re-run; cancelled runs now count as re-runnable in the adopted-PR recovery too. +- A hold added after Adopt now no longer leaves the row captioned as queued; it reads 'release the hold first' (#15665) +- An operator's Adopt now takes over any PR, a hive owner's or maintainer's included: the stage engine honours the forced adoption instead of refusing it as person-authored on every sweep, which left the row at "adopting… (queued)" forever. The hive still never adopts a person's own PR on its own initiative; the audit names the author taken over from. +- Approve no longer deadlocks a contributor PR the hive cannot merge as-is: when the approved head is on a fork the App cannot update and sits behind the base (`fork-not-editable`), conflicts, or lacks a sign-off, the admission no longer records `not adopted: a maintainer approved this head; the hive merges it as-is` — the hive adopts and carries the approval to its copy. Adopt now always wins over an earlier Approve: recording it clears the admission blocker at once, the row immediately reads *adopting… (queued)* with the Adopt now action gone from the menu and popover, and the decision response says `adoption-queued` instead of promising the running pass when the copy has not opened yet. +- A delegated `adopt-supersede` decision no longer reports "done" when only the request label landed: the Activity Monitor ✓ now reads "decided: adopt-supersede · executing…" until the adoption engine records the copy ("adopted as #N") or definitively cannot ("could not adopt: <reason>", with what a person can do). A PR that edits `.github/workflows` is decided as a capability gap and routed to the `capability:workflows-permission` blocker instead of flipping back to a bare Needs human decision; re-adoption after a closed copy surviving the mutation journal landed in [#15209](https://github.com/hivecommons/hive/pull/15209) ([#15188](https://github.com/hivecommons/hive/issues/15188)). +- Keep adopted contributor PRs with review-requested changes in the fixer's work list until a new head lands, and surface exhausted fix attempts instead of silently idling. +- Fix adopted contributor PRs so review changes-requested verdicts route to Hive-owned fixer retries instead of sitting behind stale no-verdict or maintainer-approval waits. +- Adopted contributor PRs no longer dead-end at `stage/074-adopted-by-hive`: an in-place adoption whose hive fix the squash sign-off gate strips, or whose head sits past the 074 dwell with a blocking review-swarm finding and CI idle, converts to a superseding `hive/adopt-<n>` App PR (`reason=signoff-rehome` / `in-place-stalled`) carrying the contributor's commits and the open finding; an adoption nobody is working (unchanged head past the dwell, or a failed re-home) moves to `stage/085-needs-decision` as `adoption-stalled:<lane reason>` with one comment naming the exact blocker. Existing 074 store records are re-evaluated every sweep. Red-PR fix kicks for adopted PRs now say green CI is not done while a finding is open and never report "only tide / maintainer lgtm remains" below stage 080. +- Stalled contributor PRs whose diff trips the contributor lane's diff fences (tests removed, CI workflow / action files edited) are adopted instead of being refused on every sweep (`adoption due but refused by diff fence`, hivecommons/hive#13212): adoption is not a merge. The fence is carried forward — recorded on the stage record (`adopt_diff_fence`), named in the adoption comment, and stamped into a superseding App PR's body as `<!-- hive:carried-fence reason=… -->` — so the fix lane repairs CI while every merge lane (contributor, self-authored, trusted-author, queued) still routes the green head to `stage/085-needs-decision` for a manual merge. The dco-rehome second takeover carries the fence too instead of releasing the adoption back to 072. Only a head that moved since evaluation or an unreadable / incomplete file list still defers adoption to the next sweep. +- Stage-074 adoption escalation: a red optional check alone no longer escalates an adopted PR to 085; records written before the adopted-head clock existed start their dwell at first sight instead of reading back to the original adoption; the escalation releases back to 074 when its reason clears (comment still once per head); the stalled note reports the head's real dwell (hivecommons/hive#13040). +- The hive no longer parks an adopted `role/trusted` PR at `stage/085-needs-decision` as `adoption-stalled:hive-signoff-attribution` because of its own self-signed fix commit: when the head mixes the contributor's commits with App-signed ones, every commit self-signed and the repo not in the new `auto_merge.squash_only` list, the lane elects a merge commit (`merge-method/merge` label, one `<!-- hive:merge-commit -->` note, `Sign-off survives the squash` honours the label, merge sweeps use `merge_method=merge` and record the reason on the claim). A PR already parked on that reason is released on the next sweep; a refused election stalls with the refusal named. ([#13800](https://github.com/hivecommons/hive/issues/13800)) +- Adoption: when the hive's superseding copy of an adopted PR is closed without merging, the stage-label pass now re-adopts (fresh copy from the same head, new `hive:adopted` marker), reverts the adoption with a `hive:adoption-reverted` note when the head moved or the copy cannot be opened, and parks the PR as `adoption-child-closed-twice` if copies are closed twice within an hour; "Let hive decide" re-adopts instead of answering "no change", and the tracker shows "Adopted → #N (closed) · recovering" instead of "Needs human decision" (hivecommons/hive#15052). +- Activity monitor: an issue whose only PRs are a contributor's original and the hive's adoption copy of it no longer offers "Let hive decide — all 2 PRs" or reads "fell back to Covered by pr — Covered by PR #N — …; PR #M — … changes requested". The pair is one logical PR: the caption reads "Covered by #N (adopted from @author's #M) — in CI / review", the superseded original's verdict never gates the issue, the feed says "moved to" when an issue stops mirroring its PR, and the copy's body carries the original's annotated `Refs #N` lines so it keeps the issue link. (hivecommons/hive#15549) +- Adopted contributor PRs now supersede automatically when confirmed push-access loss or squash sign-off attribution prevents in-place repair (not on API errors or unrelated base workflow drift), and idle rebase work falls through to a hive-owned branch instead of parking for a human; fixer instructions preserve contributor authorship and sign-offs (#13975). +- Adopted fork PRs are now closed (with a note linking the superseding PR) when the superseder merges, regardless of which stage the original has since moved to; when hive cannot close the original it is marked superseded so the activity monitor drops the row (#14471). +- Contributor adoption (stage `074` and its re-home / DCO re-home) no longer takes over a PR whose author has admin or maintain permission on the repository (backport of [#14305](https://github.com/hivecommons/hive/pull/14305), [#14301](https://github.com/hivecommons/hive/issues/14301)). The permission is read once per repository and author per 10 minutes; a failed read is not cached and defers, neither adopting nor releasing; an existing adoption of such an author is released, closing a still-open hive superseder with a note first. +- A PR superseded by a hive adoption now closes promptly and reads as one muted line in the Activity Monitor (hivecommons/hive#15511 listed hive's #15574 *Merge queued* and, under it, the still-open original #15526 whose greyed note "· Adopted → #15574 · superseded (hive re-authored with sign-off)" wrapped to two lines; the close-first close had been refused by the write-back gate with `needs-opt-in-label`). New `governor.labels.stage.adoption.close_superseded: on_adopt|on_merge` (default `on_adopt`): a clanker- or hive-authored original closes in the adopting pass by policy — the gate admits the close as `superseded-agent-pr` without the `contributor_adopt` opt-in label once the copy carries its commits and sign-off; a human-authored original still needs the label, else it closes when the copy merges. The tracker marks the original `superseded_by: M` (cleared when the copy dies, omitted for in-place adoptions) and the copy's `adopted_from.state` / `lineage.from_state`; the muted sub-row's note is now "superseded · hive adopted → #M" ("superseded · closed · hive adopted → #M" once closed) on one line — the title ellipsizes first, the hover carries "re-authored with the same commits and sign-off" and whether it closes when #M merges or is already closed — and the line stays only while #M is open and listed. +- Advisory digest posts to archived (read-only) repositories are no longer retried every cycle or self-reported as failures (#13570) +- Hive advisory checklists (the dedupe agent's `<!-- hive:dedupe-checklist -->` issues) are now worked by the hive itself: the close-on-merge sweep ticks each `- [ ] #N …` item as #N closes or merges and closes the advisory as completed once every item is resolved (`dedupe.advisory_autoclose`, default on); the Activity Monitor never parks an advisory at 045 (chip *Advisory · hive is working the items (k/N resolved)*, optional **Close now** lead); and the delegated-decision plan for issues says *Approve the direction of #N and let the hive pick it up* (or, for an advisory, *Close the advisory* / *Keep open; hive is working k/N items*) instead of the PR merge-queue wording (#15754) +- Advisory digest: when the newest digest comment on the advisory issue is not App-authored, re-pin to the App's own digest comment (or create one) and persist that anchor; log the foreign-comment warning once per issue per process (Debug thereafter) with the action taken, and skip the edit when the digest's material content is unchanged for the anchor. +- Repo pause now silences every hive-originated write to the paused repo, not only agent-requested ones: the advisory digest comment is neither edited nor re-created while the repo is paused (logged once per update interval as `advisory digest skipped: repo paused` with the pause's `by`/`reason`, and never counted as a post), the write-back containment gate refuses every kind — own items included — with reason `repo-paused`, and the duplicate-PR, closed-issue stage-label and hard-suppress sweeps skip paused repos. A paused `torch-spyre` spoke had kept editing its pinned `## 🐝 Advisory Digest` on every restart while the auto-merge sweeps correctly stood down. +- Dedupe advisories with nothing to act on are no longer filed as issues, and advisory issues no longer look like stalled work ([#15381](https://github.com/hivecommons/hive/issues/15381)): the dedupe lane's prompt files a new checklist only for an action-required row, and the issue-request relay refuses an `issue-create` whose dedupe-checklist body has zero near-duplicate pairs, zero resolved candidates, zero missing PR↔issue links and no task lines (audited as `agent_issue_empty_advisory_refused`, summarised in a knowledge bead). In the Activity Monitor an issue wearing `triage/advisory`, carrying the dedupe-checklist marker or a `Decision required: no` line is an advisory: the Open chevron reads **Advisory · read & close** (or **Advisory · nothing found · safe to close** when its own counts are all zero) with no "· since Nh" or stale tint, the caption is *Advisory for maintainers · read, then close*, it is excluded from Needs human / Needs attention, and the row menu leads with **Close (read)**, which closes the issue as completed through the existing decision path (`close-read`). +- The agent channels list now escapes repository names before rendering them, matching the other channel fields ([#15907](https://github.com/hivecommons/hive/issues/15907)). +- Agent Channels now offers only supported kick channels, explains GitHub issue triggering through CEL rules and signed webhooks, and shows actionable save errors without retaining rejected edits; signed issue-opened deliveries now wake the existing governor/CEL evaluation path. +- Each per-UID agent now gets its own real `~/.claude`, `~/.gemini` and `~/.bob` with only the login/settings files bridged to the shared home, so Claude Code auto-memory, transcripts, user-level CLAUDE.md, history and todos are no longer readable and writable by every agent on a hive; the dashboard token scanners also walk the per-agent `/data/home/agents/*` trees (hivecommons/hive#17031). +- Every issue the hive files now starts with its `[<agent>]` tag, with no producer left out: one `issueshape.AgentIssueTitle` function is the choke point for every issue-creation path — `CreateIssue`, the review-backlog, dedupe, hotspot (`[ci-maintainer]`, matching its `agent/ci-maintainer` label), self-report, upstream-watch, advisory and recommendations filers, and the proxy's `gh issue create` — puts the tag first (ahead of any emoji), never doubles it, and a guard test fails any new raw create that skips it. The Activity Monitor draws the tag as a chip ahead of the title instead of repeating it. Existing issue titles are left as they are; dedupe ignores the tag so they still match their tagged successors. +- Dashboard agent "Now:" line tests report when their JavaScript fixture cannot run because Node.js is missing from PATH, instead of failing the test run ([#12924](https://github.com/hivecommons/hive/issues/12924)). +- Explain how to resume a paused agent in its dashboard pause details and keep the tooltip within the viewport. +- `go test ./pkg/agent/...` no longer orphans its per-run tmux server (with `-zsh` panes spinning on deleted cwds and `sh -c … pluk watch` pipe-pane children): TestMain now kills every server under the run's `TMUX_TMPDIR` before removing the socket dir, a detached reaper covers panic/`-timeout` exits, and a post-run guard fails the run if any of its tmux or pluk processes survive. +- The hive closes its own already-landed PRs as superseded instead of asking a person: a hive-authored PR (an adoption included) whose reviewer verdict says the change is already on the base — by the `hive-redundant-of` marker or by naming the landing PR in words — is closed with the superseded comment, its adopted originals are settled and closed too, and the parent issue gets the usual closing; the empty-diff freshness guard no longer reads the hive's own label bumps as a fresh head. Logged as `self-authored:already-landed` ([#15647](https://github.com/hivecommons/hive/pull/15647)). +- Agent GitHub API hourly cap now warns once per agent per window instead of on every rejected request (#14118) +- **Trusted-author tier hands App-authored PRs off under its own reason** — the sweep logged `reason=contributor-lane:app-authored tier=trusted-author` and recorded a trusted-author stage observation carrying the contributor lane's reason, which read as if the contributor lane had routed the App's own PRs. The tier now skips them as `trusted-author:app-authored`; `contributor-lane:app-authored` is emitted by the contributor lane only. Stage derivation treats both as no-opinion hand-offs, so the self-authored lane's `review-gate:no-review-bundle` keeps owning the stage; merge gating is unchanged ([#14482](https://github.com/hivecommons/hive/issues/14482)). +- `/hive approve` on a hive-authored or trusted-author-lane PR is now acknowledged only for trusted mergers; anyone else gets the same "not a trusted merger" reply the contributor lane gives instead of a false acknowledgement (#13093). +- The dashboard's Approve result toast now leads with the outcome in plain words ("Approved #510 as @user · sentinel alert cleared by your review"), names the concrete next step and who merges (hive's merge sweep with the soak figure, or "merge it on GitHub yourself" on the human-merge lane), repeats the ⚠ sentinel paragraph only while the alert is still open after the action, lists what was posted on a muted secondary line, and on Prow-managed repos says the approval is recorded in hive while Prow approval still needs an OWNERS reviewer — instead of "`/lgtm` + `/approve` posted (released: …) … the merge gate takes it from here; the dashboard merges nothing" ([#15212](https://github.com/hivecommons/hive/issues/15212)). +- Adoption of a stuck contributor-clanker PR is automatic: the predicate that makes the activity monitor offer Adopt (`automerge.AutoAdoption`) is the sweep's trigger, so a PR at 072 whose author is offline past the grace (one heartbeat buys one window, `mode=queued` nudges count as offline) is adopted by hive on that sweep for conflicts, requested changes, failing required or optional checks and `fork-not-editable` forks; the row says when (`hive adopts it in 3m unless a new head lands`), names the fork blocker, and the log carries the trigger. Adopt now stays as the override. +- Superseded hive PRs no longer park on a person. A **hive-authored** PR whose closing targets are all closed, one of them by a different merged PR, and whose head conflicts with the base (or whose files that PR already covers) is closed by the hive itself as `hive/superseded` with a notice naming the superseding PR — in the self-authored auto-merge lane before any review is dispatched, in the supersession sweep when GitHub refuses the rebase for a conflict, and in close-on-merge of the superseding PR — under the new `governor.auto_close_superseded` knob (default on; human-authored PRs are never auto-closed). A contributor PR adopted in supersede mode (stage 074) now leaves `stage/085-needs-decision` in the adopting pass when the park was only the review swarm's `requires_human`: the original renders in the CI/Review column with an "Adopted → #N" pill instead of "Needs human decision", and the duplicate-fix sweep no longer closes the superseding App PR as a duplicate of the PR it supersedes. Evidence: #14965 (closed by #14957 for #14952, parked >1h), #14975 → #14980, #14947 → #14977. +- The fleet selfreport feed no longer files the automerge sweep lanes' (queued, trusted-author, contributor) `base-refresh:merge-guard` skip ("destination merge already in progress") as an `unclassified_error_repeated` issue; it is an expected, self-limiting outcome and stays in local logs (#16520). +- hub: Auto-pick on "Approve provision" now falls back to any other registered non-GPU pool (most available first, tie-break by cluster ID) when the request's preferred pool has no available placeholder, instead of returning 409 while capacity exists elsewhere; private requests stay pinned to the GPU pool and an admin's explicit placeholder choice remains strict. +- Activity Monitor: a PR parked on a person who must act on the PR itself (rerun CI, approve workflow runs, resolve a GitHub permission, answer open review findings) now lights the PR in progress chevron — "Waiting for @who · rerun shared ci on GitHub" — and leaves the Merge queue column empty; only rows actually queued / merging, or a merge-ready PR parked on a merge decision, sit in Merge queue. +- The dashboard backend switch (`POST /api/switch/{agent}/{backend}`, `PUT /api/config/agent/{name}/models`, and ACMM pack backend moves) now clears a `launch_cmd` that launches the previous CLI instead of persisting `backend: codex` next to `launch_cmd: /usr/bin/bob …`; `hive.yaml` and per-agent overlay saves refuse that contradiction with a 400 and a dashboard alert; and when a hive boots with the contradiction already in its base config the loader drops the stale `launch_cmd`, keeps the backend, logs an ERROR and raises a per-agent dashboard alert instead of exiting — a stale `launch_cmd` used to crash-loop the hive until someone hand-edited the PVC. +- The reviewer now carries a person's recorded decision across up to five consecutive hive base refreshes, not just one, so two App merge-from-base commits landing before any gate reads the PR no longer force a re-decision; every hop must still be an App-authored merge of the base that leaves the diff unchanged ([#15766](https://github.com/hivecommons/hive/issues/15766)). +- Stage engine / fix loop: a PR whose every failing check is also red on the base branch tip (and whose diff does not touch workflows, Dockerfiles or go.mod) stays at 050/060 with reason `base-branch-red:<checks>` instead of 070/071/072, consumes no fix-loop attempts, posts one hold comment per head, and a hive-raised `needs-human` over such a head is removed automatically; kick builders list these PRs separately from repair targets. +- Dashboard: a blocked issue waiting on another issue now names it in the stage tracker caption +- **Blocked on an issue, not only a PR.** The blocked-on marker now has an issue form, `<!-- hive:blocked-on issue=owner/repo#N -->`, read from the issue body or its newest marker comment: the blocked sweep keeps `blocked` while that issue is open (stripping only `help wanted`), lifts it with one `<!-- hive:unblocked -->` note once it closes, and never lifts it as marker-less; a malformed issue marker counts as no marker and PR markers behave as before. The contributor prompt asks an agent that prints `blocked` on a GitHub issue to put that marker on its comment. Before, a hive-applied `blocked` for an issue dependency was lifted as marker-less, so projectbluefin/utah#10 and #855 went back to triage and were re-verified "still blocked" again and again. +- bob 2.x's busy indicator ("⠇ Processing… (Enter to steer, Tab to queue)") is now recognised as an in-progress turn. Previously a kicked bob turn was classified as ended ~30s after delivery while bob was still working, so the kick outcome settled early and the turn-end kick log archive under 🕘 past kicks was a mid-run snapshot rather than the full run. +- Report boundary enforcement as demonstrated when observed writes were blocked, not a refusal-rate grade; keep zero, Sentinel detections, and coverage limitations informational. +- Keep historical terminal-PR accounting off current-work claim evaluation with cancellable bounded review batches, retained retries, and idempotent timeline persistence; preserve synchronous fail-closed claim safety and durable first observations. +- The image CA-distrust check parses only the probe's stdout, so the arm64 lane built under QEMU no longer fails on docker's platform warning; unexpected docker errors are now printed. +- "Let hive decide" on an issue parked because the GitHub App lacks a permission (the scanner's "cannot push `.github/workflows/*` (no `workflows` permission); needs a human") no longer un-parks it only for the next sweep to re-park it: the report is recorded as a structured blocker (`<!-- hive:blocker kind=capability:workflows-permission -->`, inferred from the prose when the marker is missing), the delegated decision returns no-effect with the plain-words reason and the ways out (grant the permission with a link to the App settings, re-check permissions, mark partially addressed and close, keep waiting), a loop guard disables the delegate once the same reason comes back after a delegated un-park, `stage/045-needs-decision` and `approved-direction` no longer coexist, the tracker row reads "Blocked · App lacks workflows permission", and ⚙ → Security plus `/api/status.capabilities` name the missing permissions and how many items wait on them ([#15099](https://github.com/hivecommons/hive/issues/15099)). +- Activity Monitor: the merge celebration (✓ glow, token to "Merged today") now plays for a PR drawn inline on its issue's row — before, only the counter ticked because such rows carried no sub-row key; rows stamp the PR keys they draw and ⚙ → Merges gains a **Test celebration** button. Reported by @clubanderson. +- Dashboard Channel card: when the last spoke-side upgrade was superseded by an external roll (`kubectl rollout restart`, image bump, floating-tag pull), the `↷ Running <sha>` headline now ages the running build (`releaseStatus.attempt.runningSince`, flagged `rolledExternally`) instead of the day-old superseded upgrade; the superseded note moves to a secondary line with its own timestamp, and the version menu's "Last upgrade" says "superseded (rolled externally, now <sha>)" rather than a bare "succeeded". +- Hive Chat now answers the question it was asked instead of a canned dump. The server used to tokenise every message into a bag of words and match on keywords alone, so `/agents stuck`, `/agents scanner status` and "Which agent completed last?" all returned the full agent roster and `/prs waiting on review` returned per-repo PR counts, with the arguments silently discarded. A new router keeps the arguments: a bare `/agents`, `/prs`, `/beads` or `/status` still prints its summary, while a command with arguments or a plain-words question is answered by one read-only model turn over a compact, scoped snapshot of the hive state the dashboard already holds (agents with blockers, last kick and last completed action; open PRs with stage labels, review state, CI and age; actionable issues; items awaiting a decision; governor; alerts; version and last upgrade), instructed to say "I don't have that data" rather than guess and to cite the items it used. The turn runs on the governor reviewer endpoint with a timeout and in-flight cap, writes one `chat_grounded_answer` audit line, and can never trigger an action. When grounding is unavailable a scoped question gets the command's usage, never the bare dump. New setting `chat.grounded_answers.enabled` (default on) and `chat.grounded_answers.model`. +- The action-pins CI gate (`src/scripts/check-action-pins.sh`) no longer reports `action pin check FAILED` with no finding when a workflow directory contains no SHA-pinned `uses:` lines (pipefail turned grep's empty match into a failure), and its `NOT-PINNED` message now names the workflow file rather than the line number where the file name belonged. The resolver reports every missing SHA instead of stopping at the first, and the gate now has a hermetic self-test, `src/scripts/test-check-action-pins.sh`, covering each of its failure branches. +- Hive activity monitor: the stage-chevron pulse and needs-human breathe now animate only the opacity of an overlay (compositor thread) instead of `filter` / `background` on the chevron, so an idle dashboard tab no longer restyles the page every frame. +- Hive activity monitor: stage chevrons no longer pulse for Open, Open · hold, Claimed or any other waiting step; only a step the hive is acting on (gentle pulse) or one waiting on a person (slower amber→red breathe) animates, and `prefers-reduced-motion` silences both. +- Activity Monitor stage tracker: a PR head whose checks are still reporting now reads `CI running · 4 checks pending` (chevron `CI 7/11 · 4 running`, or the last one or two unfinished names) instead of `CI activity unknown · last observed missing` / `CI unknown · no check results observed` / `no verdict yet`; a required check with no run while others still execute is one sentence in the tooltip rather than the "missing" verdict; the "no check results observed" wording is reserved for a head with zero check runs; and the chevron tooltip states each fact once (count word, detail sentence, head, source, observation time) instead of repeating the unreported check four times (#16630). Check names embedded in captions and chevron text are wrapped in single quotes. +- CI_FAILING repair queue keeps non-adopted fork PRs comment-only even when the fork allows maintainer edits; only stage-074 adopted fork PRs are listed as push-repairable, and those name the contributor branch. +- Retry CI-failure webhook kicks with bounded backoff when the owning agent is busy, then drain a bounded per-PR/check pending queue on governor evaluations; discard resolved signals when checks pass or PRs close. +- `TestBootDashboardWithClassifier` no longer races: `bootDashboardWith` starts the merged-PR lifecycle backfill in a goroutine that logs through the boot logger, so the test's log sink is now the goroutine-safe `syncLogBuffer` instead of a bare `strings.Builder` ([#13168](https://github.com/hivecommons/hive/issues/13168), [#13169](https://github.com/hivecommons/hive/issues/13169), [#13170](https://github.com/hivecommons/hive/issues/13170)). +- `TestCampaignDeleteRemovesArchiveOnly` is order-independent again: it now resets the process-wide lifecycle timeline store before listing campaigns, so completed-run journeys recorded by earlier tests in a shuffled run no longer appear as a third campaign ([#13167](https://github.com/hivecommons/hive/issues/13167)). +- `TestGFISweepReleaseAndConvertWiring` no longer flakes: it now waits for the release goroutine's final state transition (labelled key cleared, `Released` stat bumped) instead of only the forge side effects, which could be observed before the stats were updated ([#13048](https://github.com/hivecommons/hive/issues/13048)). +- The goose ACP probe seam (`runGooseACPProbe`) is now guarded by an RWMutex, mirroring the copilot SDK helper seam, so a background CLI-model refresh started by one test can no longer race with the next test swapping the probe (`TestQueryCLIModels_GooseUsesProvider` data race) ([#13047](https://github.com/hivecommons/hive/issues/13047)). +- `TestKickHitsTheEscapedEndpointExactlyOnceAndRendersTheQueuedStatus` now gates the fixture's kick response while the three `K` presses are delivered, so the `kickPending` bound is asserted inside the in-flight window instead of racing the first response ([#13191](https://github.com/hivecommons/hive/issues/13191)). +- Activity Monitor: a CI ring that is not yet full now renders the CI chevron active ("CI 13/19 · running") beside a running Review instead of a silent part-green glyph; check-run motion on the head leads red, unreported or ambiguous neighbours, and icon-only green is reserved for a complete ring (hivecommons/hive#16631). +- Prevent repeated scanner sweeps from being reported as CI polling by counting repeated reads within each kick, excluding earlier kicks' reads ([#14061](https://github.com/hivecommons/hive/issues/14061)). +- CI failure log reads (`gh run view --log` and `--log-failed`) no longer trigger stop-polling nudges or fleet reports while agents diagnose failed jobs. +- The CI-poll stop nudge and `ci_poll_nudge` self-report now also skip replica and variant names of the exempt `ci-maintainer` and `quality` lanes (e.g. `ci-maintainer-2`), not only the exact lane name (#14719). +- The `ci_poll_nudge` fleet self-report now fires only when an agent polled CI more than once since the kick; a single post-push check still gets the in-session nudge but no longer files a report. +- Stop the CI-poll wall-clock nudge from interrupting a long scanner sweep that reads each PR once; a lone poll or a repeated read past the wall clock is still nudged ([#14066](https://github.com/hivecommons/hive/issues/14066)). +- Detect verified current-head GitHub Actions workflow/check reporting stalls after bounded consistency observations, expose exact run/attempt provenance and owner action without changing CI gates or automatically rerunning workflows. +- CI runner image: bumped the pinned `gh` to 2.103.3 (the apt repo only serves the latest), and the daily CLI pin bump now keeps that pin current, including `gh` patch releases. +- A PR hive opens now records its issue claims in the duplicate-PR claim ledger immediately, so a contributor can no longer be admitted to an issue that PR already covers in the window before the next claim scan (#14472). +- The duplicate-PR guard no longer drops a PR claim the webhook recorded after the claim scan's listing began; the issue stayed covered until the next scan re-listed the PR instead of being re-offered and getting a second PR ([#15559](https://github.com/hivecommons/hive/issues/15559) saw #15561 and #15567). +- Issue stage records no longer regress to `010-actionable` on a claim release while the duplicate-PR claim ledger holds an open PR that covers the issue: the out-of-cycle stage facts consult the ledger (not only the store's memory) and re-derive `040-covered-by-pr`; a merged `pull_request` webhook now runs close-on-merge for that PR's issues at once instead of waiting for the next reconcile pass; and every eval cycle (cached ones included) backfills store records that sit below 040 under an open ledger claim, so the scanner stops being re-offered issues an open PR already fixes. +- Claim-hook retry settings are now read under a lock, fixing a data race between a lingering claim-effect goroutine and a test swapping them ([#14839](https://github.com/hivecommons/hive/issues/14839)). +- Activity Monitor: a clanker-authored PR that a trusted human sends back with a CHANGES_REQUESTED review now shows **Returned to contributor** (072, actor the owning contributor, caption `Returned to @thatguywob's hive — @clubanderson requested changes`) instead of `Sentinel alert · needs human` — the human's review on the current head is the human the sentinel, hold and workflow-path parks were waiting for, so the sentinel pass no longer re-asserts 085 over 072 until a new head re-arms it (per head, like the dashboard Approve release). The same holds for a return placed by hand: when a trusted maintainer removes `stage/085` and adds `stage/071`/`stage/072` themselves, the reconciler reads the label event, records it against the head and keeps the stage instead of logging `added=[stage/085] removed=[stage/072-returned-to-contributor]`. "Needs author" (071) stays a person's PR. The dashboard **Give direction** decision is accepted on clanker PRs too: the direction is posted to the contributor's hive as a change request and the row moves to 072; the 409 "the hive did not open this pull request" is kept only for a person's PR, which no hive can carry direction to. The 071/072 chevron keeps its routing word with any sentinel finding as a ` · sentinel` suffix ([#15159](https://github.com/hivecommons/hive/pull/15159)). +- Stage labels: `needs-triage` is now removed in the same label write that moves an issue to 020-claimed or later (including a direct claim from 015), open issues already claimed and still wearing it are reconciled on the next sweep, and the Hive activity monitor no longer reads a stale `needs-triage` as "Triage needed" on a claimed row — it shows the stage and lists the leftover label as `stale_labels` in a muted tooltip line (#14644). +- Hive and contributor image builds retry Cline installation with fresh npm metadata up to four times to tolerate transient registry propagation failures ([#16666](https://github.com/hivecommons/hive/issues/16666)). +- Close-on-merge backfill now reads a pull request that cross-references an issue from another repo in that PR's own repo, instead of looking up the same number in the issue's repo and logging a 404 warning every pass. +- close-on-merge no longer closes a pull request as a "fixed issue" when a merged sibling-repo PR mentions it (#14744). +- A merged pull request from another repository listed under `closedByPullRequestsReferences` is no longer reported as a same-repo closer, so tracker chips cannot link an issue to an unrelated PR ([#15494](https://github.com/hivecommons/hive/issues/15494)). +- Kicks are no longer silently lost when a Codex agent's TUI is sitting in a menu or modal ([#13765](https://github.com/hivecommons/hive/issues/13765)). Codex menus such as `/hooks` keep a `›` selection caret that the readiness check mistook for the input prompt, so the manager typed kick after kick into the menu, each turn "ended" with no output, and the review swarm spent every retry on a pane that never received them. Before typing a kick the manager now recognises known Codex menu footers (`esc back`, `esc close`, `enter details`), sends `Escape` (up to three times, re-checking after each) and only types once the prompt is back. If the menu does not close, the kick is marked undeliverable with the reason `prompt-not-ready: menu footer "…"` — shown in the logs and the dashboard busy reason — and is not recorded as delivered. Backends without known menu footers behave exactly as before. +- With `review.combined_perspectives: true`, review kicks are now spread across every eligible reviewer instead of always going to the first one in name order. Each combined kick goes to the reviewer with the fewest PR heads still pending on it, counting kicks planned in the same cycle. Before this, every combined review queued on one agent, so additional reviewers and `replicas:` copies sat idle and raising `review.max_parallel_reviews` only lengthened that agent's queue. +- `hivectl hives web` and `hivectl tui --hives` contribution tree, from a first-time / power-user / keyboard-and-screen-reader sweep: membership is discovered on load, errors show beside Apply instead of far down the page, repeated buttons carry their target in their accessible name (roving Tab stop, skip links, `<main>`), unrestricted Hives read "can receive all N" instead of "0/N selected" and no longer mask restricted siblings in a hub headline, Collapse/Expand all, `/` to search with a result count, "Select N matching repositories", plain-language receipt and diff, a glossary, readable contrast in light and dark mode, and no horizontal scroll at 320 px. +- `hivectl hives web`: the page embedded its session token double-quoted, so every API call sent `X-Hive-Commons-Token` with literal quote characters and was rejected with 401 — the contribution tree and profile table never loaded, showing only "unauthorized". The token is now embedded as a single JS string literal. +- Ground weekly competitor reports in revision-pinned upstream source and dated evidence, and block publication or automatic work when provenance or existing-work checks fail. +- Editing a disabled or ACMM-gated agent's configuration no longer reports a missing runtime process as a repeated sync failure ([#16798](https://github.com/hivecommons/hive/issues/16798)). +- Restart an agent on a non-inference backend whose live CLI pane stays on a consent or blocking-prompt menu after repeated undeliverable kicks, instead of leaving it wedged with every kick failing as "CLI did not reach input prompt" and never reported (#12921). +- Continuous-mode agents no longer idle forever when the manager misses a turn-end signal: the governor presumes a kicked turn over after `continuous_turn_ceiling` (default 45m) and re-arms the next kick, so a stuck reviewer resumes instead of leaving PRs at `stage/050-review-pending` until a pod restart. +- Local-mode contributors no longer start with a sandbox that cannot run anything, and `just contribute-stop` now stops local relays. `just contribute-hive claude local` (and `litellm`) runs a sandboxed `true` through bubblewrap before the relay connects; on Ubuntu, where the `bwrap-userns-restrict` AppArmor profile or `kernel.apparmor_restrict_unprivileged_userns=1` makes every agent command fail, it stops with that cause and points to container mode. A `HIVE_VERDICT` whose reason says the agent's own environment is broken (for example "environment failure", "Bash tool broken", `apply-seccomp`) is classified `blocked` and handed back as an `environment` task failure instead of being booked as a completed task. `just contribute-stop` also stops the relay named in `~/.config/hive/contributor-relay.pid` and its tmux session, and a local start refuses to run beside a live local relay instead of starting a second one under the same contributor ID ([#14832](https://github.com/hivecommons/hive/issues/14832), [#14833](https://github.com/hivecommons/hive/issues/14833)). +- Dashboard: the no-OAuth `/contribute/register` page now HTML-escapes the request host when rendering the example curl command (#13353). +- A contributor relay PR reported for a dispatched issue now gets `Fixes #N` appended (when its body neither closes the issue nor says it stays open) and the GitHub sidebar link, so the PR-claim ledger and the issue list see the issue as covered instead of leaving it Actionable while the PR waits in review as "no linked issue" ([#14763](https://github.com/hivecommons/hive/issues/14763)). +- `contribute-hive` / the contributor relay no longer point a clanker at the retired `*.hive.kubestellar.io` hosted-hive domain: a `contributor.env` saved before the move is relocated to `*.hive.hivecommons.dev` in memory with a one-time warning naming the file, and a TLS "does not match certificate's altnames" error now parks the hub with a single remediation line (re-resolving a hosted hive once via the hub registry) instead of reconnecting every 16 s forever ([#14609](https://github.com/hivecommons/hive/issues/14609)). +- Contributor dispatch now reads every spelling the scanner uses for an issue's release-line declaration — `**Target branch:** \`v6\``, `Target-branch: v6` and an inline `… Target: v6 (open the PR with --base v6)` — so the task prompt names the declared base instead of the hub branch and the contributor no longer has to answer `wrong_base` ([#14764](https://github.com/hivecommons/hive/issues/14764)). +- The Commons contribution editor reports partial staging failures honestly, prevents overlapping batch actions, and explains runtime uncertainty, offering status, selection provenance and exclusion recovery. +- Keep TUI contribution reviews within terminal height, with wrapped target identities, keyboard scrolling, persistent Apply/Back hints, and Apply paused when the terminal is too small to review. +- Contributor images now select Bob 1.x/2.x launch flags at runtime and accept both `BOB_API_KEY` and legacy `BOBSHELL_API_KEY` credentials, matching hub-side agents (#14334). +- Contributor drop cool-off is scoped per contributor: a relay that repeatedly drops an issue is cooled off from that issue for the cool-off period, while other contributors are still offered it. The resume cool-off refusal and the resume claim re-assert paths now have test coverage (#13763, #13767). +- Contributor-lane PRs no longer park at `stage/085-needs-decision` on a reviewer decision marker or bare `requires_human` while they are in CI/Review. The only early exit is a concrete security / trust finding (`review.IsSecuritySensitiveFinding`: reviewer high-risk marker, security perspective hold, security-class question, finding on a sensitive path — `sentinel.sensitive_paths` plus the new `security.sensitive_paths` — or insecure behaviour flagged), recorded as `decision_finding` and printed by the 085 comment and tracker as `the review found: …`. Everything else goes back to the clanker or is advisory and the PR moves on to the merge gate, where an untrusted author's PR parks at `stage/090-ready-for-human-merge` for the operator's merge — never auto-merged (#15640). +- Review swarm verdicts recorded with an abbreviated `head_sha` (e.g. `98489e7`) are now widened to the full head at the relay and matched by prefix everywhere the lanes look them up (contributor-lane verdict gate, merge-eligibility aggregate, dispatch planning, review queue), so contributor PRs whose current head the swarm already judged get that verdict instead of sitting at `contributor-lane:no-verdict`; the CI-snapshot evidence bundle is keyed by `owner/name` and carries `base_sha` from the GraphQL batch, so it no longer fails validation as `repo "hive" must be owner/name` / `base_sha is required`; and the stage tracker caption names the head it awaits ("awaiting review of head <sha7>"). +- Kept the Contributors sidebar count and cards on one roster snapshot, and replaced relay IDs in its online tooltip with GitHub usernames without repeated ClankeR labels. +- Avoid filing repeated-error reports for contributor-lane sweeps deferred by GitHub combined-status HTTP 500 responses; the sweep still fails closed and retries. +- Every contributor trust-tier change (operator trust/revoke, newcomer→contributor auto-promotion, registration) now appends `{tier, prev, at, by, reason, source}` to the contributor's `tier_history`, writes a `contributor-tier-changed` audit event, and is shown as "tier since … · by … · reason" on the Contributors view and in `GET /api/contributors`; same-tier writes are no-ops. The stage lane re-reads the author's registry tier every sweep — including for PRs parked on needs-rebase/hold/excluded labels — so a promotion or demotion reaches parked PRs on the next pass instead of sticking to the stale `role/*` label ([#15177](https://github.com/hivecommons/hive/issues/15177)). +- Expected contributor concurrency, hourly, and daily tier-limit refusals no longer generate repeated runtime-error self-reports; the warnings and task limits remain intact (#14414). +- Repeated copilot sniff upstream read timeouts now log one WARN per window instead of one per request, so transient network timeouts no longer trip fleet self-reports ([#15356](https://github.com/hivecommons/hive/issues/15356)). +- Cost chart and daily rollup keep large session-flush steps that reach a new high instead of discarding them at the $500 discontinuity floor; only restores of already-reached ground are dropped (#13497) +- The dashboard Cost panel's cost / PR and cost / issue tiles no longer show "—" (or fall back to the merged-by-hive counter, which is 0 at ACMM L5) on hives with many repos: the hive-attributed count reconciled every configured repo in one burst — 38–76 Search API calls for 19 repos against GitHub's 30/minute limit — so it failed every hour and never produced a baseline. The reconcile now asks about a budgeted slice of repos per paced pass, direct search counts batch `repo:` qualifiers into a few queries, partial progress is served and labelled (`count_partial`) instead of discarded, a refusal keeps the last attributed count stale, and the reason is surfaced as `count_error` in `/api/cost` and the tile tooltip. +- Cost chart: an increment is now spread back only over the stretch its own model's counter sat flat, never past that counter's previous rise, so a model recorded in real time (the proxy's Copilot capture) no longer smears each 5‑minute step across the previous 24 h — the first day of live recording had drawn ~$860 on the day before it (whose own record was $1.19) and left the earlier ~$1 days under a pixel; bars with any spend now keep a visible minimum height beside a much taller day, and the hourly view places spend in the hour it was recorded. +- cost: price `claude-fable-5.1` at the Fable 5 list rate and prune per-agent `/data/home/agents/<agent>/.copilot/session-state` trees with the same retention as the shared tree (#13488, #13491) +- Cost section: the bar chart, "spend in selected range" and the run-rate now all derive from the one window the range selector names — hourly = 24 one-hour bars, daily = the last 7 calendar days as weekday bars, weekly = the current Mon→Sun week as weekday bars, monthly = the current calendar month as one bar per day, custom = hour bars up to 2 days and day bars beyond. The run-rate is the window's spend over its elapsed length (per hour for hourly bars, per day otherwise) instead of a fixed trailing 6 h, so switching the selector updates the chart and both summary figures together. Previously weekly/monthly drew 12 multi-week bars across 84/360 days. +- The Cost card now warns when the running agents' models have recorded no usage for over 24 hours and marks the run-rate "(recording incomplete)", backed by a new `recording` block on `/api/cost` ([#13485](https://github.com/hivecommons/hive/issues/13485)). +- CI coverage job now allows 30 minutes for two sequential `go test` passes, up from 20 minutes, to prevent cancellations on green runs (#15266). +- crux `logs -f` / `run` streaming and the server `follow=1` log endpoint now stream by ring-buffer offset, so repeated lines and bursts are no longer dropped or duplicated. +- `crux` `agentsmd.ParseNearest` now resolves and confines the starting directory to the repository root before its first `os.Stat`, so a relative path escaping the root (or a sibling such as `repo-other` next to `repo`, which the old separator-less prefix check admitted) falls back to the root `AGENTS.md` instead of parsing a foreign file as the repository's own ([crux#50](https://github.com/hivecommons/crux/issues/50)). +- crux: `governor.bob.api_key_file` is now resolved through the same managed-secrets-directory check as the LiteLLM, gateway and inference key files. +- `crux serve` now honours `n` on `GET /v1/agents/{name}/logs?follow=1`, replaying only the last `n` buffered lines (none for `n=0`) before streaming, and `crux --server ADDR logs -n N -f` sends it, so the follow no longer prints the whole 200-line window regardless of `-n`; without `n` the replay is unchanged ([hivecommons/crux#70](https://github.com/hivecommons/crux/issues/70)). +- crux proxy: `topLevelMutationFields` now reads block strings and `#` comments inside GraphQL argument lists the same way it does in selection sets, so a `"""..."""` holding a lone quote (or a commented quote) in a mutation's arguments can no longer desynchronise the scan and hide later top-level fields from the capability check (hivecommons/crux#54) +- Crux guardrail path matching now normalises redundant separators and `.`/`..` components before matching protected paths +- Distinguish durable lane broker initialization conflicts from unavailability without exposing backend details, and expose stable lane error-code constants while preserving existing HTTP responses. +- `crux logs` now rejects a negative `-n` with a usage error instead of panicking (hivecommons/crux#59). +- crux: the permissions watcher now chowns and chmods each walked entry through the descriptor it opened, mirroring fixModeFile, so the entry it reported is the entry it changes. +- The crux proxy's canary scan of GitHub write bodies now refuses a request whose body could not be fully read, matching the Linear gate and the oversized-body path. Before, a read error consumed the body and still let the request through, so it reached GitHub empty and unscanned. +- The Crux publish script no longer deletes `runbooks/` in `hivecommons/crux` on every sync +- `crux-publish.sh` now rewrites relative `../docs/` links in the published `docs/MODULE.md` to absolute hive URLs pinned to the synced hive commit, fixing dead links in hivecommons/crux. +- crux/pushbroker: successful pushes now record `finished_at` in the audit result (previously only failures did) ([#14529](https://github.com/hivecommons/hive/issues/14529)). +- The `crux` module README (published as `docs/MODULE.md` in hivecommons/crux) now shows `crux logs -n 50 scout` instead of `crux logs scout -n 50`; `crux logs` parses flags with a standard `flag.FlagSet`, which stops at the first positional argument, so the documented order exited with the usage error instead of printing output ([hivecommons/crux#72](https://github.com/hivecommons/crux/issues/72)). +- `crux serve --listen` now refuses a non-loopback bind (`0.0.0.0`, `::`, `:port`, or a remote address) even when a bearer token is set, and `crux/api.ParseAddress` refuses `http://` or bare `host:port` for a non-loopback host: the TCP listener is plain http, so the token would otherwise cross the network in cleartext. Expose the API remotely through a TLS-terminating proxy that dials the loopback listener, or reach it with `https://`. The shared rule is `api.LoopbackHost`. +- Collect review outputs for open PRs without rereading every historical report, request only missing current-body perspectives, settle reviewer slots only from fresh report receipts, preserve newer verdicts against late collection/restamps, and log collection lag plus pending versus delivery-confirmed occupancy. +- Hub dashboard: the Hives table's "Showing N of M assigned hives · K filter(s) active" summary now lists each active selection as a removable chip (`Alert: Stale advisory ×`, `Search: kalantar ×`, `Location: cluster-a ×`, …) beside the count, so a table narrowed by a filter set from outside the collapsed FILTERS drawer — an alert-type chip in Attention needed, a usage-rollup row writing the search box, or a saved default view restored on load — is never a one-row mystery; clicking a chip removes just that filter. The Fleet quadrant card above the table no longer claims "N hives in view": its median is computed server-side over the whole fleet and never followed the table's filters, so it now reads "all N hives" and, while the table is narrowed, adds "(table filters not applied)" (#13079). +- Dashboard: the infinite "pulse" indicators (working-agent dots, status dots, stale agent cards; the activity monitor chevrons are handled separately) now animate only `opacity` on an overlay instead of `filter`, `box-shadow` or `border-color`, so they run on the compositor thread. An idle dashboard tab with the activity monitor open was spending ~70% of a CPU core re-styling, painting and layerizing the whole page every frame; measured with ~70k DOM nodes and 113 running animations, animations accounted for the bulk of main-thread time. Knowledge-base fact cards also use `content-visibility: auto`, so the thousands of cards scrolled out of the 500px list no longer get laid out and painted. +- The dashboard header bug button now opens the feedback form directly (the form tab is labelled "New report" instead of "Submit"; "My reports" stays one click away), and a failed feedback submission now shows the HTTP status and the server's error message (or the trimmed response body) in the toast, with every rejected report also logged server-side, instead of an uninformative error ([#13144](https://github.com/hivecommons/hive/issues/13144), [#13145](https://github.com/hivecommons/hive/issues/13145)). +- Dashboard header: the feedback and theme buttons no longer overlap the ACMM level badge on ~900-1400px viewports ([#13135](https://github.com/hivecommons/hive/issues/13135)). +- Dashboard history APIs now bound chart responses, accept timestamp cutoffs, and support conditional requests; cost polling transfers only new full-resolution samples, launch-cost detail is bounded without changing totals, and status snapshots support ETag revalidation ([#13789](https://github.com/hivecommons/hive/issues/13789)). +- Dashboard idle-CPU remainder (#13764): `stage-tracker` SSE nudges from status publishes and webhook invalidations are now coalesced to at most one frame per ~2s (a burst collapses into one trailing frame with the newest seq), and `/api/stage-tracker`'s ETag no longer hashes `generated_at`, so an unchanged tracker revalidates as a 304 instead of a full 200 on every rebuild. Open tabs stop refetching and re-rendering the tracker once per webhook. The 304 carries `X-Hive-Stage-Tracker-Generated-At`, `Last-Modified` and the source header so the "updated" chip stays truthful on a quiet hive. +- Dashboard tabs pause registered refresh timers while hidden, reuse date formatters, and release finished sparkline animation effects to reduce idle CPU and retained rendering work. +- dashboard: "PRs by model" rank now uses a confidence-weighted score (Wilson 95% lower bound of first-pass merge rate × (1 − fail) × (1 − no ship)) instead of raw first-pass %, folds model-id spellings (provider prefix, `:variant`, `5-5`→`5.5`) into one row with the raw ids in the tooltip, lists unattributed rows unranked at the bottom, renders the metric column labels once in a sticky header with `?` tooltips, and explains the formula and each column in the help text (#15618). +- Fix dashboard clipping and overflow on desktop and phones: wrap complete navigation, repository, issue/PR, model and knowledge labels; adapt activity pipelines, agent cards, overview legends and readiness rows to their actual width; keep settings tabs and wide tables locally scrollable; and fit chat panels, pressure/timeline labels plus cost, audit and diagnostics controls inside their available space. +- dashboard: a long-open tab no longer freezes on an old snapshot (wrong Overview pill/card and activity-monitor counts beside a fresh tab that is right) when its `/api/events` stream dies silently. The server now sends a `keepalive` event every 20s on idle streams and drops clients whose socket is dead; the page reconnects and refetches `/api/status` after 90s of silence and whenever the tab becomes visible again. +- Hive activity monitor sounds no longer go silent after a reload: when the browser's autoplay policy holds the audio engine back (every reload — including the dashboard's automatic reload on a new hive version — starts without user activation), the 🔊 chip turns amber and a one-time toast with an **Enable sounds** action says a click or key press on the page is needed, instead of each zap/buzz being dropped silently. Gesture plays (▶ Play, turning sound on) now start their voices inside the click itself so Safari unlocks the engine, a `resume()` that settles before the state flips waits for `statechange` rather than counting as blocked, and priming also listens for click/touchend. +- DCO checks now treat commits linked to `project.ai_author` as the hive's in both the unsigned split and the squash-unsafe count, and a split cached before hive identities counted is read again once, so an in-flight hive-authored PR is re-signed instead of waiting for a person ([#16701](https://github.com/hivecommons/hive/issues/16701), [#16703](https://github.com/hivecommons/hive/issues/16703)). The docs now state that this login linkage comes from the commit email and is trusted only because the in-place path needs base-repo push access ([#16702](https://github.com/hivecommons/hive/issues/16702)). +- The post-merge DCO trailer check (`src/scripts/check-dco-trailers.sh`) no longer fails a squash commit whose author is a GitHub noreply address (`<id>+<login>@users.noreply.github.com`) signed off under the same contributor's real email, when the branch's own history shows the two identities belong to one person; such commits are reported as informational `same-person-noreply` lines naming the evidence commit, with no GitHub API call. The v5 squash of #15315 (`687c3cb0`) is waived until that evidence exists on v5 ([#15401](https://github.com/hivecommons/hive/issues/15401)). +- Adopted contributor PRs whose unsigned commits are the hive's own no longer hold at stage 074 with `dco-missing`: the stage engine re-signs them itself (in place on base-repo heads, re-homed onto `hive/adopt-<n>` on forks) and the replay now carries merge commits from a base sync instead of refusing to re-sign (#14666) +- Waive the post-merge DCO trailer check for `fb153585e` (squash of #13548 dropped the author sign-off that both branch commits carried); maintainer disposition recorded in #13607. +- "Let hive decide" no longer calls a PR's CI red when only a non-required context (tide) is pending: the plan reads the head's own checks, derives its WHY from the recorded stage-entry reasons (reviewer requires_human / high-risk), and on a PR the hive adopted in place hands the finding to the hive's fixer instead of "sending it back to its author". +- "Let hive decide" no longer fails with a bare "hive unavailable": the preview retries transient GitHub failures (an intermittent 500 on check-runs failed it outright), answers a merged/closed item or an unrecoverable GitHub read as 409/424 with the reason instead of a 502 the hosted Ingress replaced with its generic outage page, and the dialog now names the hive, says why it could not preview (merged since the row loaded, GitHub failed after N attempts, no GitHub client, gateway 502) and that "Let hive do that" stays off until a preview loads (hivecommons/hive#16776). +- Dashboard: the *Let hive decide* preview is one clear decision instead of a wall of text — one verb-first sentence (no doubled "Hive would:"), one short why, at most two "then" items, the sentinel finding / rails / ruled-out rungs under a collapsed Details, and **Approve & merge as-is** offered only when the head is mergeable as it is. +- Activity Monitor: a row the operator sent to *Let hive decide* now follows one post-decision state machine instead of showing a green ✓, a *Hive is deciding…* spinner and the stale striped *Ready for human merge · untrusted author* pill at once. The ✓ is the decision badge (tooltip names who chose, what hive decided, when and what comes next — never a merge celebration); the pill and chevron move to where hive actually is (*Adopted · opening hive copy…* at the merge gate, *Fixing · hive is addressing @reviewer's review* at 070), progress text names the recorded decision (*Approving…* only for an approve); toasts lead with the outcome in one line. *Let hive decide* previews first (`POST …/decide-delegated/plan`, no side effects) with **Let hive do that** / **Approve & merge as-is** / **Cancel**, and the chosen button is recorded. Adoption pairs render explicitly (dimmed *Adopted → #N · superseded* original, *↳ adopted from #N* chip on the copy; a closed original is one dimmed cached-title line, never a blank numbered row). Any recorded decision lifts `needs-human` and the 045/085 stage labels in the same write and the projection never leaves a decided row in 085. All operator-facing strings use the chevron's stage vocabulary through one shared mapping (no raw `060 reviewed` / `stage/…`); 060 *reviewed* is drawn in the CI / Review column as *Review passed · CI in progress* (the lane's recorded reason) — the merge gate column starts at 080. "The author's hive" is now "the author's clanker" everywhere; no-effect popover times are local relative times and *Merge as maintainer* is the in-tracker action when available. +- A recorded `/hive decision` (or trusted CHANGES_REQUESTED review) on a PR head is now folded into the reviewer verdict for that head as a durable, head-scoped answer, so the stage-label reconciler's verdict route treats the `requires_human` / decision-requested verdict as **answered** on every tick and after a restart: instructions route to `070-fixing` with reason `contributor-lane:decision-answered`, a bare approve clears the hold, and only a new head with a fresh `requires_human` verdict asks again. Ends the 070↔085 flap seen on hive#14628, where the fix planner or a maintainer moved the PR to 070 and the next reconcile tick put it back ([#14679](https://github.com/hivecommons/hive/issues/14679)). +- A maintainer's `/hive approve` / `/hive decision <text>` on an issue the hive itself parked with `needs-human` now lifts that source label along with `stage/045-needs-decision`, so the stage engine derives `stage/010-actionable` instead of re-deriving 045 from the surviving `needs-human` two minutes later and silently undoing the un-park (seen on [#12984](https://github.com/hivecommons/hive/issues/12984)). The rule is one function, `stageengine.DecisionLiftsNeedsHuman`: the un-park sweep reads the label timeline and lifts `needs-human` only when the last account to add it was one of the hive's own — the maintainer's decision is the human input the hive asked for; a `needs-human` added by a person, or one whose timeline cannot be read, stays exactly as before ([#12680](https://github.com/hivecommons/hive/issues/12680)), and `hold` is never touched. The accepted reply now says which happened and, when the label stays, who added it. Same rule on label-driven repos' `/hive approve` ([#13075](https://github.com/hivecommons/hive/issues/13075)). +- Dashboard: approving a PR from the activity monitor no longer answers "Hive's merge sweep merges it…" — the decision `Next` sentences, the *Approve and let hive merge* consequence and the GitHub approval note now say "Hive merges it on its next merge pass once CI is green and the head has soaked", the user-facing wording from #15575; a ratchet test keeps "sweep" out of decision text (#16767). +- Preserve maintainer decision intent through PR decision paths: `/hive decision approve <rationale>` stays an approval (`yes, but …` stays an instruction), `/hive decision` is read at 070 as well as 085, a later same-head trusted APPROVED review releases a standing metadata-only request (and is dropped again if dismissed), edited non-closing issue references stay non-closing, and trusted contributor change requests return to the author (#14816). +- Dashboard: the Activity Monitor decision pills ("Let hive decide", "Approve and let hive merge", "Merge now as maintainer") no longer flash grey and unclickable on a page reload while the viewer's role is still loading; the tracker treats an unknown viewer as pending rather than read-only and repaints once auth resolves. +- "Let hive decide" no longer reports an item as "decided, but it hasn't taken effect" when a scanner parked it again (`needs-human`, `stage/045-needs-decision`, `stage/085-needs-decision`) after the recorded decision; a park applied after the decision is a new ask and is decided anew instead of posting the decision-stalled comment ([#15276](https://github.com/hivecommons/hive/issues/15276)). +- **Let-hive-decide toast: an issue decision no longer reads as "approved for merge".** On hive's own spoke, issue #15021 (`approved-direction` applied, `stage/045-needs-decision` never removed) produced the toast "Hive decided on hivecommons/hive#15021: decided, but it hasn't taken effect … Hive decided **approved for merge** at 2026-10-28T20:41:22Z". Nothing merges on an issue. The decision glossary (`pkg/delegatedecision`) now carries issue words beside the PR words for every decision kind that differs — `approve` → PR "approved for merge" / issue "approved to proceed — an agent may claim it"; `direction`, `close-superseded` and the `hold` reason likewise — and `ActionPlainOn` / `PlainOn` / `DetailOn` select by item kind in the toast, the `/hive decision` comment and the stalled follow-up (the SPA mirror `stageTrackerPlainWords(slug, detail, itemKind)` does the same). The headline no longer says "decided … decided" ("no effect yet"), and the SPA rewrites the server's RFC3339 stamps into the operator's clock ("2h ago (4:41 PM)") through the shared timezone helper. When the hive can see the real cause — the 045 park label still on an issue that already carries `approved-direction` — the toast says so ("stage/045-needs-decision is still on the issue; the scanner skips it until that label clears") and offers the fix first: **Lift the park (remove stage/045-needs-decision)** runs the audited issue-decision path that removes the label and tells the stage engine the park lifted, followed by Re-evaluate now, Re-run decision and Give direction. +- A trusted merger's `/hive decision` on a hive-authored PR parked at `stage/085-needs-decision` now moves the PR: the whole comment (not just its first line) is recorded as the instruction and quoted verbatim in the fix kick, a decision on the current head supersedes the swarm's decision-requested verdict so the PR derives `stage/070-fixing` in the same pass as the acknowledgement, a bare `/hive decision approve` is recorded as an approval that releases requires_human instead of kicking a fix that says "approve", and an acknowledged decision whose record did not survive a restart is rebuilt from the comment thread ([#14679](https://github.com/hivecommons/hive/issues/14679)). +- Delegated issue decisions now use the blocker ledger's shared capability inference, keeping repository-write, branch-protection, secret, and workflow permission gaps parked instead of approving ineffective directions, while retaining the park for other missing App permissions (#15217). +- Delegated decisions to supersede an offline contributor PR now queue the existing adoption engine immediately, preserving contributor commits, sign-off, credit, and issue closing references. +- Delegated decisions keep hive-authored superseding PRs parked when a reviewer policy sign-off question is recorded, showing the exact question for confirmation while scope and follow-up questions remain eligible for automatic approval. Scope and follow-up questions still auto-decide under the superseder rule. +- Dispatch never opens a second PR for an issue that already has one + ([#15469](https://github.com/hivecommons/hive/issues/15469)): an open PR's + webhook that covers an issue now preempts a contributor task already in + flight on it (the author's own PR excepted); the duplicate-fix sweep tells + a registered relay contributor's PR from a person's, so its one superseded + notice passes the write-back gate instead of being suppressed; and a PR + the merge train holds as `duplicate-of#<winner>` is parked with its author + (072/071/070, "Duplicate of #winner") without nudge or adoption, never + "Approved; waiting its turn". +- Image builds now fall back from `mirror.gcr.io` to `docker.io` (via the new `BASE_REGISTRY` build-arg) when the mirror throttles with 429, and the docker freshness guard no longer rejects fresh images when git lengthens the 7-char short hash (#13208, #13226). +- Dashboard stage tracker: a PR whose drawn_under issue is filtered out or on another page is now drawn under a listed issue instead of disappearing (#15116). +- Label mutations left `Unknown` or `Planned` in the effect ledger no longer fence retries forever when the reconciling label read keeps failing; after an hour the operation expires and the idempotent label write replays. +- Branch updates and review submissions left `Unknown` in the mutation journal no longer refuse retries indefinitely: the next attempt reconciles the operation from GitHub (the PR head for `branch_update`, the PR's reviews for `review_submit`) and, when GitHub cannot be read, expires it after one hour so the retry can run ([#13870](https://github.com/hivecommons/hive/issues/13870), [#13873](https://github.com/hivecommons/hive/issues/13873)). +- `LoggingBoundary` now forwards `LookupApplied` to its wrapped boundary, so idempotency lookups through a logging wrapper see the journal. +- A hive-authored PR whose diff against its base is empty (an adoption whose fix already landed through another PR) is now closed by the hive as superseded by the PR the reviewer named, through the writeback gate, instead of parking at "needs decision"; a person's empty PR still gets the prompt. Adoptions' dispatch records now carry `hive_authored`, so their decisions route through the self lane rather than the contributor lane. A reviewer decision question re-asked on a new head (including a merge-from-base, which no longer triggers a review round for an empty PR) is identified by its `hive-redundant-of` PR or normalised wording and refreshes the standing review in place with no second 085 comment. The tracker's decision popover quotes the reviewer's question from the newest verdict on any head, shows a "redundant of #N" chip and leads with "Close as superseded" ([#15499](https://github.com/hivecommons/hive/pull/15499)). +- Activity Monitor: a stalled merge train's chevron no longer renders as an empty amber chevron — the stall words were painted ochre on amber; they now inherit the chevron colour and read `Merge queue · stalled — waiting on #<head> (needs maintainer merge) · 1h21m`, every `merge_train.state`/`head_state` maps to words, and an unmapped state falls back to its humanised name plus place instead of `''` +- Evidence CI-gate panel: bundle snapshots are now judged against the required checks the merge gate would use for that repo (`auto_merge.repos.<repo>.required_checks`, else the global default) instead of the global list alone, and green merges missing a config-required check are queued for GitHub confirmation so branch protection can clear or confirm them; on a multi-repo hive the primary repo's gate check no longer produces spurious `missing_required` suspicions for repos that never had it (#13225). +- The Evidence card's "Outcome by author kind" no longer reports a PR this hive reviewed but did not merge as "outcome unknown": the governor's review-outcome ledger pass now stamps the PR's newest evidence bundle with the forge outcome it already fetched (`outcome` block: merged by someone else, with an `unrecorded` merge naming the merger, or closed without merge), and `GET /api/evidence/summary` applies the ledger's rows at read time for PRs whose bundle has no stamp. The summary adds `merged_elsewhere` per author kind and `missing.prs_outcome_from_ledger`; `missing.prs_outcome_unknown` now means truly unresolved. No extra GitHub calls. (#13186) +- Evidence: the "Issue reopen rate · rolling 30 days" card now uses the shared panel chrome (collapse toggle, ⓘ explainer, n= chip of distinct issues closed, grade pill) and a compact, overflow-contained table instead of unstyled browser defaults that bled into the next card. +- An owner's approval of a contributor PR that edits `.github/workflows/**` or `.github/actions/**` now survives the hive's own base refresh: when the only commits since the approved head are App-authored merges of the base branch and the PR's diff is unchanged, the workflow-path fence stays released instead of re-arming, so a strict up-to-date branch rule no longer needs a fresh approval every time the base moves. Any contributor push still re-arms it. +- The Hive activity monitor's chevron column now follows a PR's current state, never the highest stage it once reached: a PR under repair (070 fixing, 071 needs-author, 072 returned-to-contributor, 074 adopted-by-hive, or a red required check) lights CI / Review even while a stale `merge-failed` gate or planner-ordered merge train still rides on its record — hive's own #15574 read "Fixing · conflicting" under Merge queue. One predicate decides both the column and train membership (`stageTrackerItemColumn` / `stageTrackerUnderRepair`), `left_train` is mirrored onto `linked_prs[]`, and ratchet tests pin every stage × gate × train state to its column A covered issue's list place now follows the same live work its strip draws — an open covering PR with no stage yet counts as 040 covered-by-PR for sorting too, so a just-filed issue with an open PR no longer sinks to the bottom among the New rows (hive's own #15654) ([#15656](https://github.com/hivecommons/hive/issues/15656)). +- Hub dashboard Fleet quadrant: the median now runs over active hives only (assigned and online — the table's own predicates), unassigned placeholders and offline hives are counted as excluded rather than as zeros, "Finds its own work" no longer scores Productivity for a hive that has reported no activity, each fleet axis tile says "n of N measured", every scored axis gets its own summary line (a 0 names the criterion behind it), and the header reads "N active hives · M offline or unassigned excluded" instead of "all N hives". +- Standalone `Fleet report:` issues are fully retired: an ACMM shortfall now opens or rolls up onto the hive's `[selfreport]` tracker (with owners, spoke link and diagnostics), the hub relay folds a legacy standalone payload from an old spoke onto that tracker or answers `410 Gone`, and the hive watching the report repo closes any bot-filed `Fleet report:` issue that still lands with a pointer to the self-report design. +- Governor section shows the fleet `running N · $X this hour` figure as a visible stat; it previously rendered only inside the hidden compact governor strip +- A fork pull request red only on a fork-guard check (such as a required `Canary` that cannot run on forks) is no longer nudged ("Failing checks: Canary") or adopted on each new head before it is parked: the guard's checks are remembered on the PR, a later head red on nothing else goes straight to `stage/085-needs-decision`, the nudge never lists a fork-guard check, and automatic adoption refuses a head whose only blocker is the guard (projectbluefin/utah-packages#862, #869). +- A fork pull request whose only failing checks refuse forks (for example "a fork pull request cannot publish…; a maintainer must push this branch to the repository") is now parked at `stage/085-needs-decision` with the check named, instead of being returned to its contributor or adopted, since only a maintainer can clear it ([#14273](https://github.com/hivecommons/hive/issues/14273)). +- Serialize automatic final base refreshes per repository/base across merge lanes, preserve pending preparation outside ready train seats, and allow already-current, CI-green, reviewed successors to merge without waiting for a preparing front. +- Good-first-issue curation no longer advertises blocked, time-gated or operations-tracking issues: the sweep re-reads live labels before labelling, skips issues carrying `<!-- hive:ops-tracking -->` / `<!-- hive:recheck-after … -->` or soak-checklist phrasing, withdraws `good first issue` + `help wanted` with a correction comment when a labelled issue turns out to be blocked, held, parked or ops tracking, the blocked sweep strips `help wanted` from blocked issues with no tracked PR, and `promote-stable.yml` stamps its emergency follow-up issue with both markers (#13304) +- Governor eval cycles no longer take 10-20 minutes on hives with several due agents: kicks are now delivered to different agents concurrently (still in order per agent), so the tick waits for the slowest agent's input prompt instead of the sum of every agent's wait, and a webhook wake reaches the activity tracker within one short cycle. +- A host with no codex account no longer warns "provider headroom probe failed" and gets flagged as a repeated unclassified error: the codex app-server's "account authentication required to read rate limits" refusal is now classified as `no_credentials` (headroom stays unknown/fail-open) and logged at info. Fixes #16078. +- Hub heartbeat: the evidence-bundle summary (a walk of every review-evidence JSON under /data — ~22k entries, ~27 s on the hosted hive's NFS) no longer runs inside the 10 s collect budget; it is refreshed in the background and read from cache, so the spoke sends a full beat instead of an identity-only MINIMAL one every cycle. A collect that still overruns now logs its slowest sub-collectors and, once it finishes, is cached as last-good for the next beat. The heartbeat-delivered App key is skipped when unchanged and otherwise written atomically (temp file + rename), fixing the per-beat "failed to write github app key from heartbeat: permission denied" on root_squash NFS. +- Hub heartbeat collect no longer times out on hives with many accumulated Copilot sessions: `AllStatuses()` used to walk every `~/.copilot/session-state/*/events.jsonl` under the agent manager (one stat per session, ~16k sessions on NFS = 8–12 s cold), which starved the 10 s collect budget, so the hub saw only MINIMAL/LAST-GOOD stale beats and reported the hive unhealthy for stable-promotion soak. The transcript-liveness walk now runs on its own refresher goroutine with hot/cold session caching, and status snapshots read only the cached result. +- Stop filing duplicate unclassified self-reports for the hub heartbeat collect-timeout outcome notices (minimal liveness beat, skipped beat before identity is known, and stale stats without fresh agent overlay); retain local warnings and fleet reporting of collector timeouts, slow collectors, panics, and heartbeat failures ([#16516](https://github.com/hivecommons/hive/issues/16516)). +- Fixed the stage tracker and the governor's cached actionable snapshot keeping a pull request the hive had merged or closed itself listed as open until GitHub's `closed` webhook came back round through the hub, the closed-row sweep ran on the next status publish, or the next full enumeration replaced the snapshot. On a hosted hive in webhook cadence hivecommons/docs#469 was merged by the automerge sweep at 18:25 and still read "Sentinel alert - needs human" an hour later, with the governor re-evaluating it as merge-eligible seven more times from the cached snapshot while the hub relay was dropping deliveries. Every hive merge path records a `pr_merged` / `pr_closed` audit event; that record now applies the same closed snapshot a webhook delivery would, so the row leaves both stores the moment the hive performs the write, with no GitHub call and no dependence on the webhook round-trip (hivecommons/hive#14420). +- A hive-authored PR whose issue a different merged PR closed — or that a merged PR's body declares it `Supersedes` — is now closed as superseded (ledger reason `superseded-by-merge`) instead of parked at `stage/085-needs-decision` on the reviewer's `requires_human`, sent to 070 to rebase a conflicting head, or left wearing `needs-rebase`; the self-authored sweep asks the superseded rule before the needs-rebase label block, and a closing claim closed as not planned with no merged closer also closes the PR ([#15276](https://github.com/hivecommons/hive/issues/15276)). +- The hold guard no longer re-applies `hold` over a dashboard Approve: when a trusted merger approved the PR's current head through the hive's own decision record and the hive removed the sentinel/hold gate label on their behalf, the guard accepts that head instead of reading the hive's lift as unreviewed drift ([#15644](https://github.com/hivecommons/hive/issues/15644)). +- Hold on an Activity Monitor row no longer fails with a misleading "hive unavailable" on a hive whose id makes `hive-pause/<hive-id>` longer than GitHub's 50-character label cap: the label is shortened with a hash suffix so it can be created, `EnsureIssueLabel` no longer swallows a non-`already_exists` 422, the hold toggle answers GitHub failures with 424 and the reason (never the 502/503 the hosted Ingress replaces with its outage page), and a row action that does get the gateway's placeholder says so with the status instead of repeating it as the hive's word (hivecommons/hive#17037). +- Hold guard no longer merges the base branch into held Renovate/dependency-bot PRs (a `renovate/*` head branch or a `renovate[bot]`, `dependabot[bot]` or `mergeraptor[bot]` author); the bot keeps those branches current itself, and a hive commit made Renovate stop rebasing them. +- The hub's SaaS auth-check now waves `/api/webhook/github` through to hosted spokes, so relayed GitHub App webhooks reach the spoke's HMAC-verified receiver instead of being answered by nginx with a login redirect; hosted hives no longer report `webhooks.healthy=false` / `events_1h=0` while the hub relays events ([#13231](https://github.com/hivecommons/hive/issues/13231)). +- Fixed the hub and hive image builds failing once Alpine's `ca-certificates-20261020-r0` and Debian trixie's `20250419+deb13u1` dropped the withdrawn emSign ECC Root CA - G3 / Comodo AAA Services entries: the distrust step now rewrites each entry only when it is still shipped and keeps asserting the roots are absent from the regenerated bundle. The contributor (bookworm) and OSS-scanner (trixie) images received the same tolerance pre-emptively. +- Search engines no longer crawl or index the hub's auth-gated and API routes. Google Search Console had been reporting hub pages as "Blocked due to unauthorized request (401)" / "access forbidden (403)" because `robots.txt` said `Allow: /` and hosted hives' `/robots.txt` 302'd to the hub login. `GET /robots.txt` on the public hub now disallows every gated route group (`/api/`, `/login`, `/dashboard`, `/metrics`, `/openapi.json`, …) while keeping the landing pages and sitemap crawlable, any other host gets `Disallow: /`, every 401/403/login-redirect and every `/api/*` response carries `X-Robots-Tag: noindex, nofollow`, the login pages carry a `noindex` meta tag, and hosted spoke dashboards serve `/robots.txt` (`Disallow: /`) ahead of the auth gate and mark all their responses `noindex`. +- hub: the Assigned hives table's Version column is now width-bounded and wraps as a two-line block (channel · SHA · behind · drift / status · actions · auto-upgrade select); the "why not now", drain-agents and missed-window explanations moved to hover titles, the Repos "as:" line wraps, and cell side padding tightened, so the table fits a 1600px viewport without horizontal scroll. +- Automerge review gate: a trusted human's APPROVED review on the exact head now clears every non-approved swarm outcome, `changes-requested:<perspectives>` and the new `requires-human` included, and the `review_evaluated` audit line records `human_approver=<login> overrode=<outcome>`; the gate classifies the head from the same normalized aggregate verdict the contributor lane and `stage/085-needs-decision` read, so a `requires_human` head no longer shows as `changes-requested:style` to the merge gate (rationguard#296). Review-plan fix kicks — a maintainer's changes-requested review or `/hive decision` text — are delivered ahead of the governor kick for the same agent instead of timing out behind it every cycle, and an undelivered review/fix kick is logged and audited by PR (`review_kick_undelivered`) (hive#13100). +- A PR a person pushed themselves — an owner or maintainer in `dashboard.authorized_users`, or any `author/human` PR — is never adopted by the hive ([#15202](https://github.com/hivecommons/hive/issues/15202)). The contributor-lane "contributor offline" rule now applies only to clanker and registered-contributor PRs; a `requires_human` or changes-requested verdict on a human-authored PR routes to 071 Needs author and tells the author what the reviewer asked (or that the branch conflicts and needs their rebase) instead of parking at 085; and "Let hive decide" on such a PR can only approve-admit a reviewed, green head, return it to its author with the reviewer's question or the fix, or hold. The adoption path itself — the engine's `adoption/supersede` label handler, the delegate executor and the 090 "ready for human merge" decider from #15181 — refuses a person's PR with a logged reason that the stage tracker row shows as "not adopted: the hive asks them, not adopts". Folded from #15191: a DCO-less clanker head at 090 adopts in supersede mode rather than waiting on a person. +- A PR whose App-linked commits are signed off as the hive App while the author is a person or a clanker now goes back to its author by kind (`stage/071-needs-author` / `072-returned-to-contributor`, reason `hive-signoff-attribution`) with one comment per head giving the exact `git commit --amend --reset-author -s` fix, instead of parking at `stage/070-fixing` where no hive lane can rewrite a contributor's branch; and a trusted-author PR the enforcing review gate holds (`review-gate:no-review-bundle` / `awaiting-review-approval`) reads `stage/050-review-pending` at once rather than carrying no stage until the swarm's verdict lands. +- Inception ignores echoed clarification-question placeholders, including kick-template instructions, and waits for real questions before advancing to clarification ([#15153](https://github.com/hivecommons/hive/issues/15153)). +- Run governor maintenance sweeps on independent, non-overlapping timers using immutable configuration snapshots; report sweep cadence in `/api/health` and governor tick stage durations so slow maintenance no longer delays unrelated sweeps or evaluation ([#16286](https://github.com/hivecommons/hive/issues/16286)). +- A watchdog "agent not producing" stall caused by the inference provider refusing requests (`blocked: inference (...)`, e.g. a 429 `budget_exceeded` hard cap) is no longer filed as an `unclassified_error_repeated` self-report; the cause is upstream and already shown as a blocked agent, so the fleet issue tracker stops collecting it as a hive defect (#15986). +- Serialize inference and live Copilot token updates through atomic file publication so concurrent responses cannot race over the shared temporary usage file or overwrite newer cumulative totals with an older snapshot. +- Input Defense settings saved from the dashboard now actually unblock kicks at ACMM L5+ ([#16973](https://github.com/hivecommons/hive/issues/16973)). Saving ioscan fail mode "open" was stored as unset, which at L5+ falls back to the ACMM pack's fail-closed default, so the setting snapped back to "closed" and kicks carrying untrusted text stayed withheld. "open" is now stored as given, and every ioscan save in Settings → Security → Input Defense rebuilds the semantic classifier from the new backend and fail mode immediately, clearing the blocked-kick alert when it no longer applies. A runtime ACMM level change (for example L4 → L5 in the dashboard) rebuilds the classifier the same way, so the level's classifier requirement and fail mode apply without a restart. The alert and the Classifier backend help text no longer tell operators to restart for changes the dashboard now applies live, and the alert names the `ioscan.fail_mode` key the Security tab actually exposes. +- An agent whose held-PR coordination kick is blocked by ioscan fail-closed now logs the WARN once per agent and demotes repeats to Debug, matching the main fail-closed kick path, instead of warning on every tick and tripping an `unclassified_error_repeated` runtime self-report ([#14442](https://github.com/hivecommons/hive/issues/14442)). +- An ioscan classifier that could not be constructed (no model endpoint for the hive's CLI, e.g. a Copilot-only hive at ACMM L5+) no longer consumes the per-eval classifier budget ([#14629](https://github.com/hivecommons/hive/pull/14629)). Previously the first 64 strings per governor eval were withheld under fail-closed and every later string passed on unclassified as `budget_exhausted`, so whether an agent's kick survived depended on its render position. The fail-open path now also logs the classifier error once per distinct error instead of once per string, which stopped a hosted hive from self-reporting 64 "ioscan classifier failed open" warnings every eval. +- An unconfigured ioscan classifier (no model endpoint) now logs a one-time "not configured" warning instead of the fleet-reported "failed open" runtime error; genuine backend errors still warn as before ([#16748](https://github.com/hivecommons/hive/issues/16748)). +- Issue-claim side effects on GitHub (the `stage/020-claimed` write, the claimed-by / preempted labels and their removal on release) now retry transient failures — timeouts behind the per-repo label writer, network errors, rate limits, 5xx, or a journaled attempt whose outcome was uncertain — up to four times with a doubling pause, instead of giving up after one 15s attempt and leaving an issue an agent is already working at `stage/010-actionable`. Claim, takeover and release comments are still posted once, so a timed-out comment is never duplicated (hivecommons/hive#14766). +- Stage tracker: an open issue carrying a hold-class label (`hold`, `do-not-merge*`, `hive-pause/<id>`) now shows as "Open · on hold" instead of 045 "Needs a human decision", even beside `needs-human`; the issue stage reconciler walks the Hold list, removes a stale `stage/045-needs-decision` and forgets the store record, and `needs-human` / `needs-decision` / `needs-spec` without a hold still park at 045. PR holds are unchanged (#13012) +- Issue-stage lane marks its merged-full-fix close comment with `<!-- hive:closed-by-merged-pr pr=N -->` and checks for it first, so a failed close is retried without posting the note again. +- **A PR that names an issue in its title, body or a comment now counts as linked to it** ([#14859](https://github.com/hivecommons/hive/issues/14859)). The contribute view's issue→PR resolver checked only the PR title and body, so it dropped any search hit that mentioned the issue elsewhere. The same title/body-only view let a scanner note claim that a PR "does not reference" an issue when two of its commits said `Fixes #N`. The resolver now also reads the issue's timeline `cross-referenced` events (up to five pages of 100, under the existing 4s lookup timeout), which cover title, body and comment references (a commit-message-only reference is a `referenced` event and is not matched). The scanner and dedupe policies now tell agents to check that timeline and the PR's commits and comments before saying a PR does not reference an issue, and to say "no closing keyword in the PR body" when only the body lacks one. The added policy section grows the largest shipped policy past the 2x headroom the prompt-size cap requires, so `promptsrc.DefaultMaxPromptBytes` rises from 64 KiB to 96 KiB; `HIVE_PROMPT_SOURCE_MAX_BYTES` still overrides it. +- `hive-open-issue --no-consolidate <reason>` lets a caller file a separate issue instead of being folded into an open one; the watcher records the reason as `consolidation_skipped_reason` (#14360) +- `hive-open-issue` relay: a placeholder or made-up `--repo` can no longer put the hive into a retry loop. The script now validates `--repo` before writing anything (must be `owner/name`, not a documentation placeholder such as `owner/repo`, and inside `$HIVE_REPOS`) and exits 2 with the reason, including under `--dry-run`; the watcher classifies failures as permanent (invalid/placeholder/unconfigured repo, GitHub 404/410/422/401, non-rate-limit 403 → quarantined `.failed` on the first tick with one `ERROR` naming the path) or transient (5xx, network, rate limit, ledger *Unknown* → backoff), reconciles an *Unknown* effect-ledger entry against the repo's open issues and expires it after 1h if the lookup keeps failing, and gives up a `kind: issue` create after 3 consecutive reconciliation failures or 8 identical errors instead of 24h. Eleven identical `owner/repo` smoke-test requests from three agents, all sharing one content-derived idempotency key stuck in *Unknown*, had retried for 3+ hours on the hive's hive. +- Every issue the hive files now carries the filing agent in its title (`[reviewer] Review backlog (security): …`, `[governor] refactor: … is a merge hotspot …`): one shared `issueshape.TitleFor` helper tags titles idempotently at `CreateIssue`, in the review-backlog, hotspot and upstream-watch title builders, and in the egress proxy for an agent's raw `gh issue create`; open-issue title dedupe ignores the tag so items filed before it still match instead of being refiled. +- Record validated operator approvals before optional GitHub reporting, bound reporting waits, and keep mutation-journal readers responsive during ordered durable writes without weakening merge gates. +- The mutation journal now clamps the timestamp used for retention pruning to its own clock, so a skewed or forged future timestamp on a commit can no longer age out other journal entries early (#14830). +- Kick freshness self-reports include counts by refusal category, making repeated withheld kicks diagnosable without exposing refs or raw errors. +- A kick's log is now archived to `/data/logs/kicks/<agent>/` as soon as its turn ends, not only when the next kick, a restart or a graceful shutdown rotates the scrollback out. A daily-cadence agent whose container crashed hours after its turn finished (exit code 17, OOM — no SIGTERM, so the shutdown snapshot never ran) used to lose the run entirely and show nothing under 🕘 past kicks. The later rotation snapshot of the same kick replaces the `turn-end` archive, so each kick still has exactly one file and retention still counts kicks. +- Kiosk mode (`?kiosk=1`) always renders the dark theme unless `&theme=light` is given, so a fresh headless streamer profile no longer broadcasts light mode. +- Completed Kubernetes Jobs are now immediately deleted even if the caller's context expires during pod log collection, preventing them from lingering for the full TTL ([#16547](https://github.com/hivecommons/hive/issues/16547)). +- Sandbox Job pods no longer receive the ServiceAccount token and now run with a restrictive security context, and an unreadable completed pod no longer reports a guessed exit code 0 ([#17021](https://github.com/hivecommons/hive/issues/17021), [#17022](https://github.com/hivecommons/hive/issues/17022)). Previously the kubejob manifest left `automountServiceAccountToken` at its default and set no `securityContext`, so a contained run could read the cluster token; it now sets `automountServiceAccountToken: false`, `allowPrivilegeEscalation: false`, drops all capabilities and uses the `RuntimeDefault` seccomp profile. When a Job completes but its pod can no longer be read, the result keeps the unknown exit code (`-1`) instead of claiming 0; the kick log shows `exit_code: unknown`, the transcript's trailing status line and the dashboard's job terminal show the code as `-1`, and neither the publish gate nor `publish.verify` withholds the PR for it. +- The issue stage reconciler now removes this hive's `hive/claimed-by-<agent>` label from any issue it sees with no live claim (no live `hive:claim` marker or assignee and no live ledger claim), parked, blocked and held issues included. A label written without a ledger claim — a `claim` request on an issue no kick listed, `governor.claims` off, a failed release write — had no other remover, so parked issues kept a lapsed agent's label indefinitely (projectbluefin/utah#10, #855; projectbluefin/utah-packages#882). Human labels and other hives' agent labels are never touched, an unreadable claim keeps the label, and nothing is kicked. +- The launch-cost collector now caches each settled day's sorted per-ref list for its persisted store, rebuilding only days that changed instead of re-listing the whole retained rollup every tick (#14834). +- Activity Monitor: a row parked on a human decision now shows "Let hive decide" inline beside the server's lead (e.g. "Re-author") instead of hiding it under ⋯ → Decide…, and inline action pills are filled buttons with a ▸ glyph and a consequence tooltip so they no longer pass for record pills like "adopted from #N". +- Issue claims: the enumeration-time claim read and the in-progress sweep now fall back to the hub's own claim ledger when the forge carries no live `hive:claim` marker, so a claim whose 🔒 comment was suppressed by the per-issue comment budget no longer has `stage/020-claimed` stripped and the issue flipped back to `stage/010-actionable` ("waiting for the scanner") while the ledger still withholds it from kicks. +- "Let hive decide" now walks a decision ladder for contributor PRs — already fixed by a merged PR → mergeable as-is → rebase-then-merge → return to a connected contributor → adopt-supersede as the last resort — so a PR whose issue was already fixed and merged is closed as superseded with a note naming the merging PR instead of being adopted (#15219 / #15240). The decision names the author's tooling truthfully ("the author's clanker" vs "the author's hive"), the toast and PR comment say why, and the decide API exposes `decision.ladder {decision, reason, ruled_out}`. +- "Let hive decide" no longer un-parks an item whose blocker is a missing GitHub App permission (such as `workflows`); it recommends granting the permission and keeps the item parked, so the needs-human is not re-applied in a loop (#15099). +- The `agent_login_required` selfreport now names the backend that lost its login: the login scanner's `login required detected` record carries `backend`, `login_hint` (the CLI's login command) and `credential_valid`, so the operator knows which provider to re-authenticate on which agent instead of being told only the agent name; `codex` gets a login hint (`codex login`) ([#16953](https://github.com/hivecommons/hive/issues/16953)). +- A new head on an in-place-adopted PR pushed by someone other than the author with write or higher on the repository, or by another App, no longer hands the PR back to the offline author or nudges them: the hive keeps the adoption. A push by the author, or by a read-only third party, still yields as before (projectbluefin/utah#919, projectbluefin/utah-packages#804, #812, #822). +- Matrix kiosk no longer goes stale for the length of a governor tick: an incremental sentinel pass now reads only new PR heads in the allowlisted repos every two minutes, independently of the full 15-minute sweep, and `/api/matrix/lines` reports `last_ingest_at` / `next_ingest_in_s` so the footer can tell "nothing pushed" from "nothing ingested". The set of already-evaluated PR heads now persists under `/data/sentinel-heads.json` and is restored at boot, so a hub-triggered restart no longer re-diffs every open PR; the first ingest also runs at boot instead of waiting for the reconcile timer ([#16276](https://github.com/hivecommons/hive/issues/16276)). +- Matrix kiosk: the freshness HUD and get-started CTA now stay pinned above the canvas in every effect, including `mx.effect=terminal`, and typed rows stop above the HUD band. +- Stopped the unbounded memory, thread and connection growth in the hive process that OOM-killed hosted hives ([#14681](https://github.com/hivecommons/hive/issues/14681)): `/api/stage-tracker` held its cache mutex across the whole tracker build (one review-evidence lookup per open PR, each a glob of the repo's evidence directory on NFS — tens of seconds), and every webhook delivery and every status publish invalidated that cache through the same mutex, so webhook handlers, the governor's publish and every dashboard poll queued behind back-to-back rebuilds that never drained. Invalidation is now a flag flip that never waits, at most one rebuild runs at a time outside the lock, concurrent polls get the previous body as `source: stale`, a poll whose client went away stops waiting, and the evidence-directory sibling listing is memoised per repo directory for 60 s instead of re-read per PR. +- Dashboard: the merge celebration bee is drawn at `--fs-3xl` (≈32 px, was ≈17 px) with a theme-aware halo so it reads on dark and light panels, and the Activity Monitor's Merged counter now rolls visibly like an odometer — the rightmost wheel (and any wheel right of the changed digit) spins a full turn on every increase, the day/week counts roll with the same mechanism, the day/week line no longer disappears mid-roll on the dark theme, and a reload rolls up from the values the tab showed before. +- Activity Monitor: a PR merged by anyone — a maintainer's `gh pr merge --admin` as much as the hive's own sweep — now leaves the board with the bee fly-off and a merge toast naming the merger (`#16644 merged by @clubanderson` / `merged by 🐝 hive`); `recently_merged` is the union of the audit log and the merged ledger with `merged_by`, an `issue_comment` on a just-merged PR no longer reads as "closed", and a closed-not-merged exit keeps its quiet toast (hivecommons/hive#16658). +- Activity Monitor: a merge outcome ("Merging", "Merge failed", "Waiting for CI") always renders in the Merge gate column, whatever stage the lane fell back to; the merge-failed chip is a fixed short phrase (GitHub's refusal translated to plain words — "4 required checks haven't finished", "branch protection blocks it", "needs rebase", "not allowed" — with the raw text only in the tooltip's Details line, clamped by CSS), "retrying" while the sweep is on it; pending CI reads "CI running", never "CI is red"; cues say "back to Reviewed" instead of a stage slug; and the automerge sweep remembers GitHub's "required status checks are expected" refusal per head so it stops re-PUTting /merge every pass while the PR is still blocked (hivecommons/docs#512). +- Activity Monitor: an issue row whose covering PR is at the merge gate no longer concatenates its lane reason ("open PR #15090 covers it (PR at 060-reviewed)") into the merge-gate pill as a two-line clipped label; the pill is the stage word plus a gate fact only, the issue row reads the gate from the nested PR so it agrees with the PR sub-row, and the cover reason leads the glyph tooltip as "Open PR #15090 covers it · at 060-reviewed" (#15101). +- Activity monitor: the Merge gate column now reads one word per state in pipeline order — Awaiting merge gate (what holds it) → Ready for auto merge (next sweep in Ns) → Soaking (time left) → Merging → Merged — instead of "Ready for auto merge" for 060/080/100 alike; every row at the gate carries a leading glyph (spinning while hive's sweep is on the PR, a clock while it waits) whose tooltip and aria-label say in plain words what is happening and when the next sweep is, and the agent-working spinner names the agent. New `merge_gate` field on `/api/stage-tracker` PR items and nested linked PRs. Legend in docs/dashboard-sections.md ([#15073](https://github.com/hivecommons/hive/issues/15073)). +- A human-gated (085) PR that is approved on its current head now stays in the Merge queue column while CI on that head is queued or re-running, instead of flipping to PR in progress and back as checks cycle; failing CI or an unapproved review still moves it out ([#16595](https://github.com/hivecommons/hive/issues/16595)). +- The merge-request relay (`hive-merge`) now evaluates the same contributor-lane policy as the auto-merge sweep before merging a contributor-authored PR: a verified claim tier outside `require_tiers`, an unfinished contributor soak, a head under `min_head_age`, a missing reviewer verdict, or a `hold`/sentinel/needs-decision label refuses the request terminally, surfaces the gate in the agent's result, and is audited as `merge_request_refused`. Previously an agent's merge request bypassed those gates, so an untrusted-tier contributor PR with green CI could be merged minutes after it was opened. Hive-authored PRs keep the relay's existing behaviour, and `merge-eligible.json` no longer lists PRs parked on a human decision. +- Show the tracker's existing repository chip on merge notifications, keeping same-number PRs in different repositories linked to their own merge and row. +- The Activity Monitor no longer draws a merge train over PRs that are still at CI / Review: the merge train is a merge-queue concept, so only PRs at 080 and beyond ride one and the header counts only them. A PR short of the queue whose files overlap another open PR's now shows a muted "overlaps #N" badge ("overlaps #15637 (sidebar.html, index.html) — will queue behind it") instead of a rail, ordinal or "1st:" header ([#15653](https://github.com/hivecommons/hive/issues/15653)). + +The train header no longer says "not in this view: 7 more" over PRs that were never in the merge queue: `size`/`members` count only the PRs riding in this payload, and when the page does not draw every member the header says why — `on another page: #N`, `hidden by the filter: #N`, `not in this payload: #N`. The header's hover explains the mechanics (members touch the same files, merge one at a time in order, each rebased onto the base only after the PR ahead merges) and a member's hover says its slot, `Position: 3rd of 4 · after #X merges`. +- Merge train: a PR GitHub reports conflicting on its own, or one at 072 returned-to-contributor (label or stage record), is no longer admitted to or counted in a merge train and draws no train idle comment — hive's own conflicting #15307 read `queued-behind#15424:4/6`; a conflicting PR rides only while the train itself is repairing it (#15395). +- Activity Monitor: the merge-train header now counts the rows actually drawn under it — members shown as sub-rows of their linked issue join the train run, and members a filter hides are named (`1 of 3 PRs here · not in this view: #…`) instead of the header claiming `3 PRs` over one row; a PR that needs a person's merge (untrusted author, no linked issue, human-merge rule) is no longer a merge-train member or head, so PRs behind it no longer wait on a merge that cannot happen. +- Merge trains now order their members by readiness first: PRs the lane knows are merge-ready (080 admitted, soaking, merge queue) lead, members it has not evaluated follow, and members still in CI/Review trail — re-sorted every pass, so a PR going green moves up and one going red moves back. A PR still in CI/Review renders in its real column with a "train · joins behind #N when green" chip instead of a Merge-queue chip, and a train with no ready member says its front is provisional ([#15761](https://github.com/hivecommons/hive/issues/15761)). +- The Activity Monitor's merge count no longer resets on reload: a persistent merged ledger under `/data` records every pull request the hive tracked that reached merged (whoever merged it) and `/api/stage-tracker` carries `merged{today, total_7d, total_30d, all_time, recent}`; the chip, now **Merged** (all-time, with today / this week beneath), is pinned at the top of the tracker with the column header strip, opens a popover of recent merges, and a merge raises a bee (or "+1") from the row's ✓ cell to the chip or off the top of the screen plus a dismissible bottom-right banner with a *Show row* link ([#15147](https://github.com/hivecommons/hive/issues/15147)). +- Dashboard: the Merged pill's odometer now rolls only after the celebration bee lands — the day/week line, a total the server had already raised, and merges over the flight cap no longer move the drum while a glyph is in the air; several merges in one flight are a single roll to the final value after the last landing, reduced motion sets both at once (#15568). +- Dashboard: the Activity Monitor's Merged counter is a mechanical odometer at rest, always (only the wheels that change roll) — #15409 had sized only the flying glyph and drawn the roll as a transient overlay over plain text. +- Dashboard: the Merged pill's odometer is drawn at the chip's own type size on one quiet inset track — no 18 px bevelled drum cells, no glow — so it sits level with the other topbar chips, and the pill's icon is the dashboard's bee glyph rather than a filled hexagon; the roll animation is unchanged (#15543). +- Activity Monitor: the bottom-right "merged" toast shows the PR number again ("#15122 merged" instead of a bare "# merged") — the number was a Number and the page's HTML escaper drops non-strings (the "All merges" list had the same blank numbers and counts); it now also falls back to the nested pr record or the GitHub URL and never renders a bare "#". +- Merges the GitHub forge adapter performs are now audited as `path=forge` instead of being attributed to the merge relay (`path=relay`), and the dashboard's PR throughput counts them as hive merges. +- Activity Monitor: the Merge gate column now shows **Merging** (with `merging_since` and who is merging) for every merge path the moment the GitHub merge call starts, holds it for at least the merge toast's lifetime (30 s) before the row advances to ✓, and reads **Merge failed** with GitHub's reason when the call is refused — rows no longer jump from CI/Review straight to merged. +- Retire stale missing-required-check merge banners only after successful exact-current-head evidence, preserving required App identity and other PRs' unresolved blockers. +- Dashboard: on phones, dialogs with long bodies (the **What changed** release notes after an upgrade, alerts, the export viewer, the Level 6 auto-merge notice, settings bodies) now open as full-screen sheets with a fixed title and ✕, a scrolling body and fixed buttons, honouring the safe-area insets; every long modal body shows a bottom fade while there is more to read (cleared at the end) and a thin always-visible scrollbar on desktop, so content no longer looks cut off +- Overview KPI tiles no longer overflow the phone viewport right after a restart: the "refreshing after restart" pill wraps inside the card instead of widening the headline grid, tile sublines and sparklines stay within the tile, and the `--fs-2xs`/`--fs-2xl`/`--fs-3xl` type tokens are now defined at `:root` so they no longer fall back to the 16px body size (hivecommons/hive#16601). +- Stop filing a fleet self-report when copilot model discovery fails only because the operator has not completed the dashboard Copilot Login; the condition is still written to the local audit log and warn line, now with `state=credential_missing` and a `recovery` field naming the Copilot Login, and any earlier real discovery failure is cleared from the tracker so it cannot file with stale text (#12947). +- The dashboard no longer WARNs on every poll when an inference backend returns no models (once per backend per hour); the fleet report names the flapping case `models_endpoint_empty` (#16369) +- Stage every issue a hive PR closes as `stage/040-covered-by-pr` the moment the PR opens, not just the one the hive-open-pr request declared: the relay now unions the request's issues with the body's `Closes #N` list, and the `pull_request` webhook emits the same CoveredBy fact for each hive-authored closing claim it records in the claim ledger. Scanner-filed sub-issues closed alongside their parent no longer sit at `010-actionable` with the scanner as their actor for the PR's whole CI run. +- Bound the convergence mutation journal: terminal (Applied/NotApplied) operations age out after 7 days and the oldest terminal entries are evicted past 20k entries, so `journal.json` — reloaded and fully rewritten on every label/comment/merge transition — stops growing without limit (53k entries / 56 MB on the hosted hive, ~60% of all Go allocations). Planned/Unknown entries are never pruned. +- native-queue-policy workflow checks out the base branch head instead of the PR's stale recorded base sha, so the policy test file is always present. +- The native queue policy check now passes as a no-op instead of failing when a `pull_request_target` run lands on a pull request that is already closed or merged ([#16128](https://github.com/hivecommons/hive/issues/16128)). +- Native merge queue withdrawal now also triggers on a release in progress and on a human-merge path, so a Hive-enqueued PR no longer keeps merging through GitHub's queue during a release freeze or after `human_merge_paths` changes (#15517). +- Activity Monitor rows parked on a person now state why on the row itself: the hive-note line reads `#N — Needs human: <blocker> — <ask> · requested by … · lead: <first enabled option> ▸ · @author is pushing it in #PR`, the issue's decision column keeps `Blocked · App lacks workflows permission 👤` while a covering PR drives the strip, the `needs human` pill carries the full reason and reveals the line on click, the 085 chevron reads `Needs human · <short reason>` (e.g. "edits CI workflows"), an issue blocked only by its PR's pending decision reads `decision on #PR`, the first enabled blocker option leads when the server disables "Let hive decide" (shown muted with its reason), and the "owed — blocked: …" caption double space is gone ([#16623](https://github.com/hivecommons/hive/issues/16623)). +- Quiet notification mode (`github.notifications.mode: quiet`, the default) now folds the remaining per-event comments the hive posted into the single edited `<!-- hive:status -->` comment: the post-merge evidence pointer, the `hive:unblocked` note (now also idempotent per issue and settled PR in either mode, and skipped when the same merge closes the issue), the review backlog summary, the contribute hub's claim marker and an agent's relayed `hive/awaiting-ci`, `Parking on stage/045…` and `Already fixed` status notes. Closing an issue leaves one closing comment: the close-on-merge sweep and the issue-stage lane no longer both post `Fixed by #N`. The GitHub client logs `github notifications created=N edited=M suppressed=K` once an hour so the effect can be measured ([#15918](https://github.com/hivecommons/hive/issues/15918)). +- The Activity Monitor's Merged odometer no longer rolls before the bee lands: a merge the merge-gate hold still masks as "Merging" is held back from the count like a flight to come, so the number waits through the hold and the flight and rolls once when the glyph reaches the chip. Successive merges queue their rolls and the display ends on the server's value; a reload still shows the server's number at once ([#15762](https://github.com/hivecommons/hive/issues/15762)). +- Adoption now resolves merge conflicts for a returned-to-contributor PR whose clanker is offline instead of handing the PR back: when the supersede's replay of the base onto `hive/adopt-<n>` conflicts, the hive opens the copy anyway and the fixer's rebase-resolve episode (`requested_by: adoption`, two attempts) resolves it; after two failures the PR parks at `stage/085` with `rebase-failed-twice` (copy) / `adoption-stalled:rebase-failed-twice` (original) offering *Adopt into fresh branch* / *Close as superseded*. An attempt that opened nothing is re-admitted once the clanker has stayed offline for `governor.labels.stage.adoption.offline_grace` (default 30m), and its branch push is a fresh journal claim so the branch an earlier attempt deleted is recreated. Tracker row reads "Adopting · fixer resolving conflicts" while the fixer works. +- Activity monitor: a contributor PR whose `stage/*` labels the write-back gate kept off GitHub (fork PR, no opt-in label) no longer reads as an unclassified "PR in progress · @x's clanker" when the stage engine holds it at `stage/085`: the stage record carries `labels_suppressed` and the tracker trusts it instead of treating the missing park label as a lifted park. An unclassified clanker PR now carries its author's `presence`; when the clanker is offline the chevron reads `PR in progress · @x's clanker · ■ offline 3h` and the caption names the next automatic step (a green PR is reviewed and merged without its author; hive adopts only once it is returned and nothing is pushed for `adoption.after_offline`). Human-authored PRs are unchanged and never adopted. +- automerge: `/ok-to-test` is now posted at most once per head SHA (durable comment marker, survives restarts), is skipped entirely when Prow replies that the App is not a trusted commenter and the repo has no `hive-ok-to-test.yml` workflow, and such PRs park at `stage/085-needs-decision` with a single `needs-human` note instead of looping. +- Dashboard: the Overview tile totals, the left-nav Overview `issues/PRs` pill and the Hive activity monitor list now all derive from one canonical server-side open-items set (`/api/status.openItems`), so the three can no longer disagree; the activity monitor's sidebar counter is now that total (needs-attention moved to the header suffix and the counter tooltip); totals count listed items (extra reported-but-unlisted items show as "+N not yet listed"), ForgeState cache items seed tracker rows, and a boot-restored snapshot is marked stale until the first fresh enumeration instead of being served as current. +- The hub orphan sweep no longer abandons an upgrade 20 minutes in when the spoke is alive, still on its old build and reports no drain: a spoke on a build that predates drain reporting drains in-flight kicks silently for the default 45-minute window, and clearing the latch there left the instruction only in memory, so the next merge-driven hub restart lost it and daily-window `:stable` hives missed every window. The latch is now held for the default drain window plus the usual grace, which keeps re-delivery alive across hub restarts ([#14856](https://github.com/hivecommons/hive/issues/14856)). +- Dashboard Overview: after a restart the stale badge reads "⟳ refreshing after restart (<n>m ago) · N/M repos scanned · showing snapshot from <t>" while the governor still serves the snapshot restored from disk, instead of "⚠ stale since <previous pod's time> (1h ago) · serving last-good". `/api/status` carries `restartRefresh` (restore time, snapshot read time, scan tally); it clears with the first completed enumeration. +- Dashboard: the left-nav Overview `issues/PRs` pill now mirrors the Overview tile's **Total open issues** / **Total open PRs** exactly — same `/api/status` snapshot, same render pass, same last-good figures when GitHub refuses an enumeration — instead of counting Hive activity monitor rows, which omitted items outside the tracker (e.g. `24/11` beside tiles reading `31/18`). The pill's tooltip now carries the tile equation. +- Dashboard: a repo whose issue list came back empty beside open pull requests is no longer published as "0 issues · N PRs". The enumeration verifies the empty list against the repository record and serves the last-good enumeration or reports the missing issues as an unlisted, stale remainder; the Overview marks such repos "issues syncing" instead of printing a confident zero. +- Activity Monitor: an owner's Approve (either variant) on an untrusted-author PR is now a trust override for that head — the stage record carries `admitted_by: operator-approval:<login>`, the contributor lane merges the head as-is after checks and soak, and the adoption engine refuses to adopt or supersede it while the admission stands (before, the approval was reduced to a comment and the claim-tier rule adopt-superseded the PR). When the head cannot merge as-is (commits without a Signed-off-by) the popover and both Approve confirms say so before acting and offer "Re-author as hive PR" as a separate choice. Fixes #15136 (#15156). +- Dashboard *Decide… → Approve* on a parked pull request now records the person's approval against the PR head (the auto-merge lanes and the stage engine read it as the answer to a `requires_human` / decision-requested verdict, like a trusted merger's Approve review), lifts the hive's `needs-human` park, removes the `sentinel-alert` label and records a head-keyed `sentinel_acknowledged` action in the review evidence bundle so bundle-only sentinel alerts clear too, re-derives the stage and drops the tracker cache. Before, it only posted the `/lgtm` + `/approve` comments, which no lane read, so the row stayed at stage/085 *Needs human decision*; the delegated *Let hive decide* path is unchanged (comments only, never clears a sentinel alert). The activity monitor's lit chevron for a detour (085 on the Merge gate column) now names the parking stage in its hover instead of borrowing "Awaiting merge admission … Next move: human" from the column. +- A pack agent that an ACMM level adds to a hive whose operator moved their agents onto one inference gateway (e.g. the L2 `reviewer` on a LiteLLM hive) now joins that gateway with its default model instead of the pack's Copilot CLI, and a pack-owned agent that already exists on a CLI — or on a gateway the hive has since moved off — is moved there on the next restart. The gateway is the one every operator-picked backend names, provided the agents already on it are a majority of the other enabled agents; pack-owned CLI agents such as the L2 `supervisor`/`brainstorm` do not veto the move and follow it, and once moved they count toward that majority so the next level's agent (the L3 `ci-maintainer`) follows too. A hive with an operator-picked CLI agent, or with only a minority of agents on a gateway, is left as is, and an operator-owned or legacy unowned `backend:` is never moved (#14678). +- Applying a pack no longer seeds its model id onto a kept hand-set non-gateway backend such as `codex`; the agent keeps its own model ([#13288](https://github.com/hivecommons/hive/issues/13288)). +- Auto-merge sweeps no longer call merge on every pass when GitHub refuses it with a 405 that no retry cures: "At least N approving reviews are required" (`merge-refused:review-required`, retried when the head or the PR's mergeable state changes, or after 30 minutes) and "Merge commits / Squash merges / Rebase merges are not allowed on this repository" (`merge-refused:method-not-allowed`, per repository and method). Both park the PR at `stage/085-needs-decision` with a comment naming the rule instead of showing it as merge-imminent at 100, and the merge-queue-only base memory now applies to every sweep, not only the self-authored one. +- Keep the dashboard navigation button label visible on phone-sized screens. +- Retrofit Hive-authored `Refs #N` pull requests from the claim-label sweep too, so existing open implementation PRs gain GitHub's issue-list link even after their issue has moved out of the in-progress stage lane. +- Retrofit Hive-authored default-branch PRs that used `Refs #N` so issue-stage sweeps add GitHub issue links, and unstick open issues whose claiming PR already merged. +- Ensure Hive-authored default-branch PRs that cover issues get closing-keyword links, while partial or non-default PRs leave issue-stage comments explaining GitHub link limitations. +- Hive PR notifications no longer spam authors and watchers: the stage stalled/regressed notes, the trusted-human 071 note and the duplicate-PR redirect share one `<!-- hive:status -->` comment per PR that is edited in place instead of appending a comment per event; "**Reviewed** — no findings" reviews are recorded as verdicts without a GitHub review and a head carries at most one hive review; the 071 note @-mentions the author once per cause instead of once per head; a check returning to pending after a push is no longer a regression and a merge-train queued/rebasing wait is never stalled. New knob `github.notifications.mode` (`quiet` default, `normal` restores the old behaviour) ([#15875](https://github.com/hivecommons/hive/issues/15875)). +- The open PR overlap check now fetches the exact API-reported head when GitHub has not exposed a PR's pull ref, so an available sibling commit no longer blocks unrelated PR checks. +- Activity Monitor: the PR in progress chevron is the row's fallback — it defers (settled, icon only) whenever CI or Review runs, so CI + Review is the only pair ever active together — and its words are the PR's lifecycle (`Unassigned · next: scanner`, `Waiting for @author · fix owed`), never the CI / review verdict — and an active CI / Review chevron has exactly one fill: the stalled-blocker track no longer renders a darker amber, and running checks stay active whatever the poll's age (hivecommons/hive#16643). +- The pr-request watcher now reports an unpushed head branch once per request instead of once per retry, states the exact ref and repository it checked and what the push relay recorded for that branch (queued, pushed, failed, or no record) rather than asserting a push-authentication failure, and logs when the request later succeeds on retry; `hive-open-pr` warns at request time when the head is not on the remote, naming the branch, remote and push step; fleet-report fingerprints no longer treat a possessive apostrophe as an opening quote, which truncated this report's scope to "the agentQ" ([#16969](https://github.com/hivecommons/hive/issues/16969)). +- Avoid duplicate unclassified fleet reports when a PR request head branch has not been pushed. +- Activity Monitor: every nested PR sub-row under an issue now has its own ⋯ menu and checkbox, so Let hive decide, Approve, Close as superseded (pre-filled with the one sibling), Won't fix, Give direction and Hold act on that PR rather than on "the issue's nested PR"; an issue with two or more open PRs offers "Let hive decide — all N PRs" and the delegated decision decides each PR on its own, listing every outcome (`items`) instead of silently picking one; the selection bar gains "Let hive decide (N selected)" with a "3 sent · 2 decided · 1 no-op" tally ([#15009](https://github.com/hivecommons/hive/issues/15009), [#15017](https://github.com/hivecommons/hive/pull/15017), [#15020](https://github.com/hivecommons/hive/pull/15020)). +- `hive-open-pr` now corrects a PR-title emoji that contradicts the Conventional Commits type (`📝 docs: …` → `📖 docs: …`, `📖 fix: …` → `🐛 fix: …`) before the PR is opened, the agent instructions spell out the convention (✨ feature, 🐛 fix, 📖 docs, 📝 proposal, ⚠️ breaking, 🌱 chore) and the review-priority classifier names 📝 as the proposal emoji, so a hive-authored docs PR no longer fails the repository's required `PR Type` check on the emoji swap. +- Run the pinned ARM64-only PR verifier on native ARM64, preserve GitHub-hosted isolation for forks, and report incompatible or failed verification explicitly instead of leaving stale optional results unexplained. +- Group complete preparation issue/PR row units into a front-first FIFO block with an uninterrupted connector through captions and nested spacing; preserve unrelated rows and child associations, distinguish unverified recorded fronts, and validate geometry in Chrome with its required runtime dependencies. +- Restore the Activity Monitor's compact preparation train pill and side rail on actual tracker rows, retaining live pipeline comments without changing stages, sorting, linked trees, or ready/native queue membership. +- Fence preparation settlement against superseded head/base/review inputs and concurrent owner or attempt changes, preserving unresolved refresh ownership and fresh-review requirements without treating required-green as release authority. +- Give an active base-preparation owner's current CI-green head bounded reviewer-slot priority, yielding to aged review waits between confirmed handoffs without changing review, merge, or resource gates. +- Recognize an active preparation owner's own base refresh when the destination advances beyond its recorded base snapshot, including after restart, using the existing App-authored unchanged-content proof while preserving CI, review, ownership, and fairness gates. +- Show durable base preparation owners and FIFO tickets in the Activity Monitor without presenting pending CI or review work as a ready merge train. +- fleet report: the knowledge primer's byte-cap warning is an operator configuration signal, not a repeated runtime defect, and no longer files an `unclassified_error_repeated` self-report (#14173). +- Copilot live usage capture now records Claude completions that the Copilot CLI sends to the Anthropic `/v1/messages` endpoint (JSON and streamed, including prompt-cache tokens), and helper calls on another model no longer relabel the agent's model ([#13487](https://github.com/hivecommons/hive/issues/13487)). +- Repeated blocked proxy requests (e.g. Copilot-internal endpoints) are now logged once at WARN instead of on every attempt, ending false-positive self-reports (#14204) +- The bundled proxy no longer rejects device-flow sign-in on direct-route spokes: `POST /api/gh-user-auth/start` and `/poll` (exact paths) are forwarded without the shared token, and mutating requests carrying a `hive_session` cookie reach the Go API, which authenticates the session itself. Neither gets `X-Hive-Internal`; all other unauthenticated mutations still return 401 ([#15872](https://github.com/hivecommons/hive/issues/15872)). +- The crux proxy now treats hostnames case-insensitively and ignores a trailing dot when classifying hosts for inspection. +- The agent proxy now applies its plain-HTTP destination policy to uninspected CONNECT and transparent-TLS tunnels as well, so all three egress legs dial only globally routable addresses; `HIVE_PROXY_ALLOW_PRIVATE_FORWARD=true` lifts it for every leg at once +- The push broker's trailing-blank-line normalisation now amends HEAD with `git commit --amend --only -- <files>`, so only the files it rewrote enter the amended commit; paths the agent had staged but not committed stay in the index instead of being folded into the push. The outgoing file list and protected-path check are re-evaluated against the amended commit, and the protected-path guard moved to `pushbroker/protected.go`. +- crux/pushbroker: trailing-blank-line normalisation no longer silently re-tracks a touched path the agent had staged for deletion (`git rm --cached`); the staged deletion is put back after the amend ([#16198](https://github.com/hivecommons/hive/issues/16198)). +- Allow independently proven, CI-ready pull requests to prepare past a completed refresh awaiting CI, without displacing unresolved mutations or bypassing dependency, review, fresh-base, or serialized-merge gates. +- When hive closed its own copy of an adopted PR, re-adopting it now opens a fresh copy instead of being mistaken for the earlier adoption and undone, and a recorded copy that is still open is reused ([#15204](https://github.com/hivecommons/hive/issues/15204)). +- Activity Monitor: a PR at *Ready for human merge* now offers **Approve & merge as maintainer** and **Approve — let hive merge** at the top of its ⋯ menu and needs-human popover (new `merge-now` / `queue-merge` decisions, merger/owner only, confirm + toast + decision badge), every needs-human state carries at least one matching action with a consequence line plus *Let hive decide* (on a 090 PR the hive answers at once in plain words why it won't merge, with the merge buttons), and the *untrusted author* pill explains why in plain words and how to trust the author (#15078). +- Stop filing fleet runtime self-reports for the expected handoff after rebase attempts are exhausted, while retaining the local warning and diagnostics ([#16510](https://github.com/hivecommons/hive/issues/16510)). +- The Activity Monitor's "Approve & merge as maintainer" on a PR that needs a rebase (behind or conflicting with its base) becomes **Rebase, then merge as maintainer** instead of failing with a GitHub 405: the click records your approval first, has the hive rebase the PR, waits for CI, then merges it with your approval on record — the row reads *Rebasing → merge queued (approved by @you)*, the ledger's `followed[]` carries each step, and a conflict settles as *failed* with the conflicting files and the options *Adopt into fresh branch* / *Close as superseded*. The approval stays bound to the head you read: only a head the hive itself committed counts as the rebase, and a head anyone else pushes after your click settles the follow-through as *failed* (`foreign-head`) with nothing merged and *Approve the new head & merge* as the way out. The option is also offered at 085 *Needs human decision* when the row wears needs-rebase. The fixer router now classifies a conflicting PR before skipping rows parked at needs-decision and routes a PR with an armed follow-through as pushable, so a parked PR that falls behind is no longer owned by no lane; and the unpark sweep dismisses any recorded changes-requested whose source is the hive's own `/hive decision` comment ([#15103](https://github.com/hivecommons/hive/issues/15103), [#14822](https://github.com/hivecommons/hive/issues/14822)). +- No merge lane ever rebased a conflicting PR — the self and trusted-author lanes stopped at prow's `needs-rebase` label before their update-branch call, and the fixer router only listed hive-authored or adopted PRs as rebase work, so PRs the operator opened under their own identity through session agents sat `dirty` with nobody kicked. Now a `behind` PR gets update-branch from its lane despite the stale label, and a `dirty` PR by the hive or a trusted author is dispatched to the fixer as a rebase-resolve task (rebase onto the base, resolve, force-with-lease to the PR's own branch) with a loop guard of two attempts per conflict episode: the Activity Monitor pill reads **Rebasing · attempt n/2**, then **Rebase failed · 2/2 — needs a person**, and *Rebase, then merge as maintainer* rides the same task; the conflict-aware merge train's rebase hook ([#15117](https://github.com/hivecommons/hive/issues/15117)) now opens that same episode (`requested_by: merge-train`), and its rebase-exhausted row offers *Rebase, then merge as maintainer* live instead of disabled ([#15103](https://github.com/hivecommons/hive/issues/15103)). +- **Approve** on a PR that is behind or conflicting no longer says "the merge gate takes it from here" (the gate skips a conflicting PR for good): the approval is recorded, the fixer's rebase episode opens in the operator's name, the toast reads *Approved — #N conflicts with base; hive will rebase it next pass (attempt 1/2)* with a **Rebase, then merge as maintainer** button, and the row's *Approving…* cue clears as soon as the decision records instead of lingering beside the ✓ ([#15103](https://github.com/hivecommons/hive/issues/15103)). +- The stage tracker's `regressed` chip now fires only on a genuine fall: a lapsed claim (020 → 010/015), the claim's PR-evidence flicker (030 → 020), the agent returning to its covering PR (040 → 030) and a 040 → 010 after the covering PR merged partially are no longer booked as regressions; the marker clears on the first forward hop instead of waiting for the item to climb back to the stage it fell from; and on a hive-driven row with nothing waiting on a person it draws as a muted `stage ↓` pill (tooltip: the hive is handling it) outside **Needs attention**, keeping red for human-gated rows ([#14570](https://github.com/hivecommons/hive/issues/14570)). +- The contributor relay's one-shot hub-registry relocation (after a certificate hostname mismatch) now follows only an `https://` entry under the hub's own spoke domain; registry entries naming any other host, a plain-http URL, or a spoke-domain lookalike are skipped and the hub stays parked with the existing remediation line. +- Claim release markers, including routine relay task completions, now share the per-issue automated comment budget with claim markers instead of posting without a cap; the local claim ledger remains authoritative when a release comment is suppressed ([#13766](https://github.com/hivecommons/hive/issues/13766)). +- Tagged releases resume: a `release: none` HTML-comment marker that rode in a `changelog.d/` fragment (#12928, merged 2026-10-19) was compiled into `## Unreleased` on every merge and made the release workflow's decide job skip every commit since v5.186.4 as an "explicit human override" — the fragment could only be consumed by the very release it vetoed. The fragment is removed; `check-changelog-fragment.sh` and `compile-changelog.sh` now reject a `none` marker in a fragment (bump markers stay allowed); and a hand-placed `none` freeze in CHANGELOG.md is surfaced as a workflow warning annotation and fails the decide job once it has outlived `RELEASE_FREEZE_MAX_DAYS` (default 7) instead of silently skipping forever. Also fixed on the way out: with the resulting 1,369-fragment backlog the bump inference's `grep -q` died of SIGPIPE under `pipefail` and would have labelled the catch-up release a patch instead of the minor its `### Added` section calls for. +- New agent claims clear stale `hive/claimed-by-human` labels when trusted claim and release comments confirm the prior human claim was released ([#14231](https://github.com/hivecommons/hive/issues/14231)). +- Activity Monitor: the PR in progress chevron on a red PR now reads the evidence-based remediation state — `Changes requested · unassigned · next: scanner` while nobody has picked it up, `Remediating · <actor> · 4m` only on a running fix kick, a clanker claim or a working agent on the PR, and a done-style `Fix pushed abc1234 · re-review pending` once a head lands after the red signal; a push that predates the changes-requested review no longer reads as a fix. The item carries `remediation: {actor, kind, since, source}` and the tooltip names the evidence (hivecommons/hive#16525). +- Auto-merge no longer merges the base branch into dependency-bot PRs (a `renovate/*` head branch or a `renovate[bot]`, `dependabot[bot]` or `mergeraptor[bot]` author) once they are out of hold: the lanes' update-branch, the current-base refresh, merge-forward, the merge train's sibling update and rebase requests, the trusted-author fixer rebase, adopted-PR recovery and `hive-merge --update-branch` all leave the rebase to the bot, and a behind bot branch holds as `behind` instead. A hive commit made Renovate stop rebasing the branch for good. +- Contributor and resident agents no longer park issues at `stage/045-needs-decision` for a target repository's own "offer a spec / confirm before implementing" instruction gate or a registered sibling checkout that is simply not cloned yet: prompts and policies state the hive dispatch satisfies such gates, the hub reclassifies a gate-citing verdict as idle and lifts the label once per issue, and a new `project.repo_policies[].companion_repos` key clones sibling repositories alongside the target. +- The reporter-trust merge hold (#9665) no longer holds hive-authored PRs, judges only linked issues (closing-keyword and declared links; a link that resolves to a PR is skipped, hive self-reports count as trusted), and the stage-label pass releases a hive-set reporter-trust hold left on a hive-authored PR; the stage tracker pill now reads "Held by hive · reporter trust (issue #N by @X, contributor)" / "Held by @login" with a release/keep decision popover, and the needs-decision comment names who set the hold and why. +- Activity Monitor: a pushed head with nothing against it now waits on `🐝 hive reviewer · re-review of <sha>` instead of the PR author (`rework.owed_by`), the Review chevron is the lit one once CI is green, and the GraphQL PR batch no longer caches a truncated `statusCheckRollup` page as the head's full check list — which had read `CI 7/11 · required check "test" hasn't reported` on an all-green head with 70+ contexts (#16635). +- Activity Monitor: "Returned to" rows now name the clanker's owner (`@login's clanker`) even when an issue is drawn through its covering PR, instead of the issue author (the hive App bot); rows the supersession sweep found superseded say "Superseded by #N · decide" and the "Close as superseded by…" prompt is prefilled with that PR. +- review: one backlog issue per finding per PR across perspectives and heads — carried-over "previous/prior … still present" notes and `<!-- hive-refers-to: #N -->` citations are references that never refile (at most one "still present at <head>" comment per head); on merge the blocked sweep checks the base itself and closes items whose file or symbol is gone; the activity monitor folds blocked review notes under their source PR as one muted line and counts the group once; dedupe ignores a leading `[reviewer]` title prefix +- The review backlog no longer folds a finding into an open issue just because both cite the same file: it folds only when the category (review perspective) matches and the finding cites the same symbol or a nearby line; otherwise it files a new issue cross-linked with "Same file as #N" ([#13906](https://github.com/hivecommons/hive/issues/13906)). The same check now applies to an open issue matched only by its "Review backlog (<perspective>)" title prefix, and scanner-filed issues without a "Review backlog (…)" title or "Perspective:" line no longer receive folded review findings (retiring the [#11578](https://github.com/hivecommons/hive/issues/11578) behaviour). +- Review backlog: a finding filed `blocked` (evidence file absent on the base branch) that folded into an already-open twin issue with the same title no longer carries `blocked` onto the twin. The fold discards the filing's body and with it the `<!-- hive:blocked-on pr=… -->` marker, so the twin was parked with nothing to lift it, lost `help wanted` and refused every claim; now the twin's own state governs. The blocked sweep additionally lifts a hive-applied `blocked` that has no blocked-on marker, no `hive:recheck-after` deadline and no `hive:ops-tracking` marker (a human-applied one is left alone) ([#13364](https://github.com/hivecommons/hive/issues/13364)). +- Activity Monitor: the Review and CI chevrons wear the amber in-progress fill only while perspectives or checks are actually running; a finished verdict is done-style (approved, changes requested, or a muted "awaiting human decision"). Back in PR in progress with the hive on the repair, a human-decision verdict reads "changes requested" instead of "awaiting human decision" (#16531). +- Reviewed row now counts reviews submitted after a PR's first read and reviews by deleted accounts (as unknown) (#16119, #16123) +- The contributor relay's PR review cycle no longer stalls waiting for a human to approve extra commands: its prompt no longer restricts the agent to the PR-listing commands, names the `gh` reads it needs to check review comments, reviews, checks and an UNKNOWN merge state, and tells the agent never to ask for permission. If a command is unavailable, the agent skips that check and names it in the `HIVE_VERDICT` ([#13787](https://github.com/hivecommons/hive/issues/13787)). +- review evidence: upserts to a PR's evidence bundle now take a cross-process file lock so hub and agent writers no longer lose verdicts (#13911). +- The "review fix dispatch excluded" line for PRs the hive did not author (`not-hive-authored`) is now logged at INFO instead of WARN, so the expected policy skip is no longer filed as an `unclassified_error_repeated` fleet issue ([#14870](https://github.com/hivecommons/hive/issues/14870)). +- review-fix: a `changes_requested` verdict whose report carries no `body_digest` is now treated as "digest unknown → body unchanged" instead of "PR body edited → re-review", so PRs at `stage/070-fixing` get a fix kick instead of being re-asked for review every cycle (#14665). Reports are now stamped with the PR body digest at collect time and when the relay records advisory verdicts; a starvation guard forces the fix path after 3 consecutive revisit-suppressed cycles, each suppressed cycle logs a WARN with its reason, and the planner summary line reports `fix_excluded` / `fix_excluded_reasons`. +- The review swarm no longer parks a Hive-authored PR at `stage/085-needs-decision` when its only workflow change is a strict `permissions:` reduction (hivecommons/hive#13068). hivecommons/pluk#305 narrowed a workflow-level `contents: write` to `contents: read` with green CI and still needed a human `/hive decision` because the `permissions-credentials` / `sensitive-paths` risk classes from #13043 keyed on the topic, not the direction. The relay now proves the direction structurally from the PR diff (`review.WorkflowPermissionsTighteningOnly`: only removed or lowered scopes, a block replaced by `permissions: {}`, no new job/step/trigger/`uses:`/`secrets.*`/`id-token: write`, no other sensitive path touched) and, only then, suppresses those two classes and the `permission`/`privilege` escalation terms; the suppression is recorded as a `permissions-tightening-only` reason on the aggregate. Any widening, any mixed diff, or anything the parser cannot prove still gates exactly as before, and the reviewer prompt now says the same thing. This is verdict classification only — no stage, transition or merge-gate change. +- Fix reviews stalled by removing a configured review perspective while heads are running. +- The Activity Monitor's Review and CI chevrons never say "activity unknown": with no verdict and no reviewer in flight the tooltip states what the head waits on (closed, draft, waiting for CI, not started and who is next, or no data for the head yet · refreshing), a settled verdict names who decided, how long ago and each perspective's verdict with its first finding, and settled verdicts stay known as observations age. +- Review dispatch now remembers heads it passed over for want of a free reviewer, promotes them ahead of webhook-prioritized PRs after three consecutive cycles, and the review queue plus Activity Monitor say how far the review got and how long the head has waited instead of a bare `stalled` pill (#15229). +- The self-report classifier no longer files `unclassified_error_repeated` issues for the review-request watcher warning that an abbreviated verdict head is not the PR's current head and was recorded as written (#14997). +- The activity monitor no longer tells an author who just force-pushed that they have given "no response" ([#16021](https://github.com/hivecommons/hive/issues/16021)): a human PR whose new head was red again re-entered 071 within one sweep, which restarted the waiting-on-push state and re-nudged for the new head, so the rework chip read `requested · no response` and the row kept "Needs @author". The stage record now remembers the original ask and the head pushed after it (`rework_asked_at`, `rework_pushed_head`, `rework_pushed_at`) across that re-ask, the chip reads `pushed · re-review pending` dated from the push with `requested_at` on the original ask (a review verdict on the pushed head is a fresh ask), and a row whose `push` field says pushed drops the "Needs @author" decision and the needs-human count until CI / the re-review settle. +- The rootless Podman qualification probe now keeps its temporary image store under `/var/tmp` to avoid quota-limited `/tmp` storage and preserves image-pull diagnostics when a prerequisite fails. +- Activity Monitor: the row menu's consequence hints ("merges #15118 into v5 now via hive's identity, attributed to you", "records your approval; the hive's merge sweep merges #15118 on its next pass…") no longer run past the menu border over the rows behind it — a menu with hints grows wider (capped to the viewport) and each hint wraps on its own line under its label, the rescan hint included (#15175). +- Stop the LKE cache-prune DaemonSet from deleting live toolchain binaries by archive timestamp; operators must apply the updated manifest to protect runner tool caches (#13425). +- Show the Activity Monitor's running fleet cost and its rotating period on a separate, wrapping line below the running count so narrow tiles and zoom no longer truncate the amount or period. +- Merge queue holds every open PR claiming an issue that another open PR in a different automerge lane also claims (the hive's own PR vs a trusted human's PR for one issue) until a decision is recorded — lane reason `merge-train:claim-conflict#<other>:<issue>`, log `same-issue claim conflict undecided: #A vs #B`, tracker chevron "held · duplicate of #B · needs decision", and a delegate plan that names the concrete PRs to keep and close instead of "all 2 PRs" (hivecommons/hive#15810). +- Sandboxed agents (`sandbox.enabled: true`, Podman or `runtime: job`) no longer 404 on the card's `📄 full log` / `📋 log text` buttons: hive archives the container's captured stdout/stderr as the kick log (`<kick_log_dir>/<agent>/<kick-start>-sandbox.log`, `source: sandbox-job`/`sandbox-podman`) when the run ends, serves the newest archive from `GET /api/agents/{name}/log`, lists every run in the 🕘 kick history, and names the archive in the last-run record (`logId`); before its first run the button explains that no archived run exists yet. The output used to live only in the Job pod (deleted on completion) and the sandbox workspace (swept after two hours). Reported-by: @joerunde (a1-vllm-spyre spoke). +- Sandboxed kicks no longer push a branch and open a PR just because commits exist: `.hive/agent-report.json` gained an optional `status` (`success`, `failed`, `blocked`), and when the report says `failed`/`blocked` or the sandbox exited non-zero hive keeps the commits local, records the run as failed with the reason (`prWithheld`, shown on the card as "no PR opened: …"), and writes a `sandbox_pr_withheld` audit line instead of a PR that can only fail CI. Reports without a `status` publish as before. Reported-by: @joerunde (a1-vllm-spyre spoke). +- Sandbox PRs now take their title/body from `.hive/pr-title.txt` / `.hive/pr-body.md` in the workspace (or the HEAD commit) instead of a fixed placeholder that referenced hive's own tracker +- Sandboxed agent run records are now written without holding the agent manager lock, so a slow data volume no longer stalls status and kick calls, and `sandbox-runs/runs.jsonl` is compacted to its newest 1000 records so the token collector's scan cost stays bounded. +- The review-request watcher no longer polls at its short cadence indefinitely when the sandbox review manifest directory is untrusted (#14993). +- Sandbox publish preflight (`publish.verify`) reads its commands from config only; a `<!-- hive:publish.verify … -->` block found in a kick message is logged and ignored instead of run. +- The scanner's governor (backlog) kick is no longer deferred indefinitely behind review-fix kicks: after an agent's governor kick has been displaced by a delivered fix kick on two consecutive cycles, the governor kick goes first for that cycle and the fix kick is re-planned, so actionable issues are offered to the agent again instead of sitting unclaimed for hours (#15166). +- Per-agent scoped-token mint with no GitHub App installation ID now logs one actionable warning per agent instead of every tick, and is reported as the `github_app_not_installed` fleet-report class rather than `unclassified_error_repeated` (#14186) +- The dashboard metrics collector now caches its GitHub Search-API count queries (hive-attributed merged PRs / closed issues per repo, outreach PR counts) for `HIVE_FORGE_COUNT_CACHE_TTL` (default `20m`) instead of re-asking on every collect, serves the last-good counts (marked stale) with a 10-minute retry backoff and a rate-limited warning when a refresh fails, and stands down while the GitHub slow-start caution window is engaged. Re-asking every cycle tripped GitHub's secondary rate limit on the hosted hive (2026-10-21) and darkened the automerge sweeps and advisory lookups behind it. Follow-up to the faster eval cycles from #13319. +- `EnumerateActionable` no longer publishes a repo as empty when GitHub refuses its fetch transiently (secondary/primary rate limit, 429, 5xx, pre-emptive refusal): the repo's last successful enumeration is substituted for up to two hours and listed in `ActionableResult.stale_repos`; the repo card carries `countsStale` and the Overview KPI snapshot is marked incomplete so history skips it. The dashboard previously showed TOTAL OPEN ISSUES 0 and a one-row activity monitor during such a refusal while the repo had 19 open issues. Webhook per-row tracker refreshes also skip their GET while the caution window is engaged. +- Webhook, review and continuous-agent wakes no longer re-list every tracked repository: the cadence tick (`eval_interval_webhook_s`, 900s while webhooks are healthy) is the authoritative reconcile pass, each webhook delivery's targeted re-read now upserts/moves/removes that one item in the governor's cached actionable snapshot (not just the activity-monitor row, so newly opened items no longer wait for a cycle), and wake cycles plan from that cached snapshot (`source=cached`, `/api/status.cachedCycles` / `webhookPatches`). A reconcile pass that fails outright keeps the previous snapshot published and marked stale instead of dropping to zero. +- The webhook patch path treats the delivery as a hint and re-reads the item before upserting, applies upserts monotonically by `updated_at` (recording the `X-GitHub-Delivery` id, fetch time and head SHA in `item_patches` for audit), removes closed/merged items and re-adds reopened ones after the confirming GET, and bounds irreversible actions: `CloseIssue`/`MergePR` planned from a snapshot refuse while the repo is stale and re-read an item older than 60s first. A reconcile that fails outright (or a cold start whose GitHub share failed) publishes the last-good figures with `staleSince` / `countsStaleSince` and an Overview "stale · as of" badge instead of zeros. +- The slow-start pacer now prioritises by caller: the governor's enumeration runs high priority, periodic housekeeping (automerge sweeps, review-request watcher, advisory lookups, metrics/fleet-stats collectors) is shed instead of queued when the caution-window queue is deeper than it could wait, the self-authored automerge sweep backs off to a 60s floor while cautious, and GitHub App installation-token mints bypass the pacer entirely — so a secondary-limit 403 no longer starves the eval cycle and token refresh behind housekeeping (`slot would miss request deadline`). +- The contributor security hold now reads scope-effective reports, the same ones the review gate decides from, so a security report whose raw `requires_human` verdict only rests on out-of-scope findings can no longer keep a contributor PR parked for a person when a sibling perspective supplies the effective `requires_human` ([#16865](https://github.com/hivecommons/hive/issues/16865)). +- On a PR the hive did not author, the security review's `requires_human` now stays a hold for a person (`stage/085-needs-decision`, with the finding named) when another perspective also asks for changes. Before, the sibling `changes_requested` folded the security hold into the fix cycle and the PR went back to its author at `stage/072-returned-to-contributor`, although a security finding is the contributor rule's one early exit to a person ([#15640](https://github.com/hivecommons/hive/issues/15640)). projectbluefin/utah-packages#890 was sent to its author for a PR-body edit while the security review's question about a new App credential waited on a maintainer. +- Activity Monitor bulk “Let hive decide” now works when a multi-PR parent issue is selected, confirming and deciding each open PR once even when its sub-rows are also selected ([#15061](https://github.com/hivecommons/hive/issues/15061)). +- A spoke whose self-upgrade `PATCH` on its own Deployment is rejected or timed out by a cluster admission webhook (a failing Kyverno webhook on vllm-d blocked every patch) no longer reports the upgrade as **failed** when a plain restart will land it anyway. The patch deadline is raised from 10s to 45s (above the 10s webhook default, so the apiserver can return the real webhook error) and retried once; when the patch still fails and the Deployment tracks a floating tag that the kubelet re-pulls (`imagePullPolicy: Always` or unknown), the spoke exits immediately with a distinct exit code and reports **pending-restart**, so the hub keeps the in-flight latch instead of counting a failed attempt. The hub's stuck-upgrade alert and the orphan-sweep give-up message now carry the spoke's classified cause ("cluster admission webhook (e.g. Kyverno) is rejecting or timing out Deployment patches — a cluster admin must fix or exempt the webhook") instead of the misleading "Deployment tracks a floating tag" guess ([#14385](https://github.com/hivecommons/hive/issues/14385)). +- The hub no longer re-requests a channel commit date from GitHub on every render after a failed lookup (e.g. HTTP 403 rate limit); it backs off for 10 minutes per commit, so rate-limited hubs stop repeating the "channel commit date: fetch failed" warning. +- The `ci_poll_nudge` self-report now lists the repeated CI-status commands (with counts) in its diagnostics, so the fleet issue is triageable instead of showing only an idle pane summary (#14289). +- Classify the login-required, ioscan classifier fail-closed and startup-kick-dropped WARNs as named fleet-report classes instead of `unclassified_error_repeated` (#14262, #14263, #14266) +- Classify transient GitHub-fetch, label-provisioning and agent-CLI restart-loop WARNs as named fleet-report classes (`github_fetch_transient`, `label_provisioning_failed`, `agent_cli_restart_loop`), report `ioscan_classifier_unavailable` on first observation, and tighten the `agent_pane_timeout` keywords (#14258, #14259, #14260, #14277, #14278, #14286) +- Recurring agent-runtime log lines no longer land in the self-report feed as "unclassified". Self-healing noise (cached GitHub 404s, rate-limited Copilot token validation, permissions repairs) is ignored, while tmux, proxy TLS handshake, per-agent directory setup and review-evidence write failures and feedback issue-refresh failures now report under their own named classes. +- The watchdog's `agent credential failure` log line is now reported under the existing `agent_login_required` selfreport class instead of `unclassified_error_repeated`, so owners are pointed at re-authenticating the agent backend rather than a generic defect report ([#16861](https://github.com/hivecommons/hive/issues/16861)). +- Repeated lane-gate and trusted-author sweep warnings caused by a transient GitHub 500 on the status read are no longer filed as selfreport issues (#15785, #15786); a hub heartbeat rejected with a restarting-hub 502/503/504 is likewise classified as transient (#15789) +- Fleet selfreports no longer file an unclassified-runtime-error issue when the request pacer refuses a request because its slot would miss the caller's deadline; the WARN stays in local logs (#15109). +- Fleet selfreports no longer file an unclassified-runtime-error issue per caller when GitHub rate limiting or the hive's own request pacing makes many callers log the same transient failure; the WARNs stay in local logs (#15106). +- Self-reports no longer loop between a spoke and whoever closes them: a runtime-error fingerprint names the defect (class + normalised message) instead of the build, a fingerprint closed upstream is not re-filed by the same hive while it keeps observing the condition (the 7-day cooldown now runs from the last observation, on the direct path and through the hub relay), "Cleared on" comments are paced to once per hive per 24h and withheld under a closed issue, and the catch-all `unclassified_error_repeated` class joins only issues whose title matches the message rather than any open issue of that class. +- The fleet self-report no longer files an unclassified-error issue when the review-request watcher suppresses a duplicate review comment under the per-head cap (#15906). +- Avoid filing repeated-error fleet reports for sentinel skips caused by GitHub pacing, while retaining the local warnings and reporting other failures. +- Sentinel: a dashboard Approve on a flagged PR is now remembered as the release of that head — the sweep reads the hive's own `hive:pr-approval head=<sha>` comment instead of treating the hive-account `unlabeled` event as nobody's clearance, so it no longer re-posts the alert and re-applies `sentinel-alert` to the head the owner just approved (dibs#510, hivecommons/hive#15214); a new push still re-arms. On a Prow repo where the bot is not an approver, a later Approve records the decision without re-posting `/lgtm` + `/approve` and reports `commands_skipped`. +- Surface shared-CI recovery permission refusals as an actionable operator handoff, retry after the permission cooldown even on unchanged PRs, and align bot-PR squash attribution with the existing required check. +- Sidebar count pills (Overview `40/18`, Governor `4/12`, Projects, Hive activity monitor, Knowledge, Contributors) now share one right edge. The hover-revealed hide toggle (⊘) is appended after the pill on every hideable row and held an invisible 20px slot there, so those pills sat ~26px left of Overview's (the one row that cannot be hidden). The pill is now always the last flex child; the toggle fades in between label and pill on hover, so nothing shifts. +- Dashboard sidebar: the Overview counter (`33/13`, open issues / open PRs) and the Hive activity monitor counter (`37`, rows) count the same open set two ways — every open issue is a row, a PR is its own row only when not drawn under a listed issue. Both tooltips and the activity-monitor header now say so (`37 rows (33 issues + 4 PRs on their own row) · 9 PRs shown on their issue's row`), so the numbers read as one population, not a disagreement. +- Spoke dashboard: clicking a left-sidebar item now keeps the chosen section pinned at the top of the viewport while late renders (status poll/SSE repaints, lazy panels, collapsing sections) shift the layout above it, instead of scrolling away and needing a second click. The hold re-anchors on layout drift for 2.5 s and releases on any wheel/touch/key input; render-time scroll anchoring pins the navigated section rather than the neighbour peeking under the sticky navbar. +- A signed-commit reconciler compare that hits a 404 (missing head branch or invisible repository) is now classified as a persistent GitHub refusal, so it is counted, bounded and noted once instead of being retried uncounted every pass ([#16202](https://github.com/hivecommons/hive/issues/16202)). +- Activity Monitor: a row parked on a policy sign-off ask (e.g. a fork's workflow change) now says "Review 5/5 · needs your sign-off" / "needs owner sign-off" instead of "awaiting human decision", leads with an inline "Approve ▸" when CI is green (then "Let hive decide ▸"), and no longer captions "Recommendation recorded" when hive kept the park without recording a recommendation. +- Hive no longer supersedes its own PRs for a missing sign-off: the automerge DCO stage treats commits on a PR by hive's `ai_author` or App login as self-squash (so an App-signed commit no longer counts as squash-unsafe), `signoff-rehome` keeps hive-authored and operator-approved heads in place instead of re-authoring them as a new PR, the App's signed re-author commit always carries a `Signed-off-by` trailer, and the push relay refuses a hive-identity commit that lacks one. +- Activity Monitor: a tracker row (issue row or PR sub-row) now renders at most one hive note line. The needs-human / decision ask outranks the blocker, next-move and stage-transition notes; a lower note's facts ride the winning line as a trailing clause only when they say something the row does not already (a "moved to Needs human decision" note under a strip already lit at Needs human decision is dropped). The single line keeps its ⬡ icon, View link and one relative age ([#16627](https://github.com/hivecommons/hive/issues/16627)). +- `skillreg.SpecServesRepo` no longer treats differently-owned org-qualified repo references as the same repo ([#16168](https://github.com/hivecommons/hive/issues/16168)): a spec scoped to `laredo/cuga-agent` now correctly refuses to serve `acme/cuga-agent`, while bare↔qualified matching remains (bare `cuga-agent` still matches qualified `laredo/cuga-agent`). +- The scanner, issue-request watcher and `/contribute` relay lane no longer dispatch an issue an open pull request already fixes: a live open-PR check (`scanner.skip_issues_with_open_pr`, default on) skips the claim, labels the issue `has-open-pr` and logs `claim skipped: open PR already linked`; and a duplicate-fix sweep resolves two open PRs fixing one issue without an owner decision — the earlier green/pending PR stays, the later hive PR is closed as `duplicate-of:<keeper>` with one comment, a person's later PR is commented on and left open, and only an earlier red/stale PR facing a later green one is escalated to `stage/085` ([#14799](https://github.com/hivecommons/hive/issues/14799)). +- List all 61 SOC 2 Trust Services Criteria in the compliance profile, with explicit not-covered rationales and mappings for monitoring, protected credential movement, and encrypted backups. The A1.2 backup mapping reports the effective key source (governor key_file, default Secret/PVC mounts, or the HIVE_BACKUP_KEY fallback) rather than the raw key_file path. +- `GET /api/hub/release/stable-promotion` no longer mixes a fresh stable SHA with the digest and commit date of the previous stable build, and reports the stable commit time as `built_at` (it was published as `promoted_at`, which misread a commit time as the tag's promotion time). +- `stage/030-pr-in-progress` now requires PR evidence. A hive-agent issue claim used to derive 030 on its own (claimswire `claimFactFor`, the `claim` issue request, and the live `hive:claim` marker on enumeration), so an issue the scanner claimed while triaging wore "PR in progress" with no PR or branch to show (hivecommons/hive#13069). Claims — agent, human, contributor, external — now derive `stage/020-claimed`; 030 is written only when the claim carries `PRStarted` (a `hive-open-pr --issues` request or a `<!-- hive:start branch=… -->` / `pr=…` marker), recorded on the ledger and the claim marker as `pr_started=true` so the sweep re-derives the same stage. Legacy `IssueStageFor` and the stage-engine adapter changed together (shadow mismatch gate stays 0); goldens regenerated with `pr_started` variants and three #13069 regression cases. +- The expected-transition table and pipeline diagram now draw `020-claimed → 010-actionable` and `030-pr-in-progress → 010-actionable` (claim released or expired) plus `020 → 040`, so claim expiry is no longer a `stage_transition_anomaly`. +- Stage engine (shadow): the PR deriver now reproduces the stage the automerge pass writes, not only `resolveStage`'s opinion — the pass hands it its post-step inputs (`PRPassFacts`: detected author kind, prior record, human-route evidence, DCO walk, adoption state) and `DerivePR` applies the same 07x split, normalized-fixing guard, `RouteHuman`, DCO override and 074 yield. Human hand-offs the route refined to 071/072 (red checks, conflicts) or 050 (no verdict for the head yet) were counted as `085` mismatches on every pass and kept the 48 h shadow gate from ever reading zero; a goldens parity test now derives all 8 231 fixtures through the engine. +- The stage pipeline diagram and the engine's expected-transition table now draw `071-needs-author ↔ 050-review-pending` (the human twin of the 072 edges), so a human author pushing a fresh head no longer counts as a `stage_transition_anomaly`. +- The stage-label reconciler now warns once per PR head and refusal reason when the write-back gate refuses reopening a hive-closed superseded PR, instead of on every tick. +- Make review-verdict normalization independent of the previous PR stage and suppress same-head stage reversals for 15 minutes at the reconciler write boundary, preventing idle PRs from repeatedly restarting label-triggered CI ([#16880](https://github.com/hivecommons/hive/issues/16880)). +- An issue with both a live agent claim and an open hive PR that fixes it now stays at stage/040-covered-by-pr: the eval sweep runs the duplicate-PR guard before the live-claim filter, so the claim no longer re-buckets the issue "claimed" (020) every cycle after its PR opens and the dashboard stage tracker no longer shows a spurious `regressed` chip on nearly every claimed issue. +- The stage tracker now surfaces an Actionable issue the scheduler withholds for an open GitHub "blocked by" dependency: the row wears the `blocked` modifier, the chip and tooltip name the blocker(s), the payload carries `blocked_on`, and the caption reads "waiting on #N" instead of plain "waiting for the scanner" — sequenced RFC sub-issues no longer look like intake starvation (hivecommons/hive#14765). +- Stage tracker *Let hive decide* now opens its preview at once as a skeleton (Cancel enabled, the action disabled until the plan lands, errors inline with Retry, no double-fire), prefetches the plan when a row's decision options are revealed and serves it from a 45 s bounded server cache with a `Server-Timing` header; covered issue rows read "Covered by PR #N — waiting for a decision on the PR" with a chip that scrolls to the PR's row, and every 👤 next move carries a short `human_reason` after its chevron word ([#15773](https://github.com/hivecommons/hive/issues/15773)). +- Stage tracker: Let hive decide now shows the hive is working at once, covered issues no longer repeat their PR's button, and a person's move says why (#15773) +- Activity tracker: the "updated … ago" chip now reports when its 30s poll is failing (`poll failing (HTTP 504)` / `(unreachable)`), goes amber at once and demotes `fresh` to `cache`, instead of counting up "updated 8m ago · fresh" from the last good payload while the server is unreachable (#14416). +- Dashboard: the Hive activity monitor's ▶ Play / ▶ Play both sound previews were silent in Safari and Chrome because the play checked `AudioContext.state` synchronously right after an un-awaited `resume()`; previews now create and resume the context inside the click, wait for it to come up (handling Safari's `interrupted` state), show "Playing…" on the button and toast when the browser blocks audio, while automatic merge/open plays resume briefly without bursting and re-arm gesture priming until a resume actually succeeds. +- Activity Monitor: the row event line no longer says "fell back to" for forward moves whose stage number happens to decrease — triage accepted (015 → 010), a decision made (085 → 080), the author resuming (072 → 070). The stage table now carries `falls_to` from the stage engine's regression rule, and only those hops read as a fall. +- Stage writer no longer removes Prow's `dco-signoff: yes|no` labels; it only reconciles its own `dco` / `no-dco` pair, ending the remove/re-add label war with Prow on every open PR (#13125). +- Issue stage sweep writes `stage/040-covered-by-pr` again for issues an open PR covers: the second in-cycle `annotateIssueWithClaim` pass no longer re-grades the hive's synthesised covered label as GitHub's, which had left issues with an open `Fixes #N` PR stuck at 010 (#14397). +- stagelabels: Owned and Plan now match existing stage labels case-insensitively, consistent with Current (#13909) +- Issue claims held by a hive agent are released the moment that agent's CLI is relaunched (hive boot, restart), with a `hive:release` marker comment that claim readers now honour, so an issue no longer sits at `stage/020-claimed` for the full agent TTL after a rollout. Rate-limit relaunches of Copilot agents are also spaced across the fleet (one per 30s) instead of all agents re-validating the same exhausted token budget together. +- Parked issues no longer show "Needs human decision" after a maintainer has acted: the un-park sweep honours a maintainer's `/fixed` (alias `/close`) on a parked issue — closing it as completed, clearing `needs-human` and the stage labels, and posting one acknowledgement ([dibs#459](https://github.com/hivecommons/dibs/issues/459)); `/hive approve` and `/hive decision` lift `needs-human` whoever applied it, with the reply naming who had, while `hold` stays untouched ([docs#419](https://github.com/hivecommons/docs/issues/419)); a new closed-issue sweep strips `stage/*` and a Hive-added `needs-human` from issues that closed wearing them ([homebrew-hive#127](https://github.com/hivecommons/homebrew-hive/issues/127)); and the dashboard tracker drops closed issues and reads the needs-decision state from the issue's current labels rather than a stale store record. +- Demote the stale status snapshot drop to Info; warn only after repeated consecutive drops (#14117) +- Classify repeated startup kicks dropped during an agent restart or stop as `startup_kick_interrupted` instead of an unclassified runtime error. +- Agent status, triage, verification and gate-check comments and every relay `label` request no longer count as a start signal, so they no longer record an agent claim or stage the issue `stage/030-pr-in-progress`; a comment starts work only with `<!-- hive:start -->`, a "starting now"-style phrase or an opening "Starting …"/"Implementing …". Claim admission (every producer) now also refuses issues parked on a person (`stage/045-needs-decision`, `needs-spec`, …) and umbrella issues labelled `epic` (new `governor.claims.never_claim_labels`, default `[epic]`), and the stage engine never derives `stage/020`/`stage/030` from a claim on an epic. The Settings dialog (Features → Issue claims) gains a “Never-claim labels” control for `governor.claims.never_claim_labels`. +- The dashboard status snapshot is now published before the governor's serial kick dispatch as well as after it, so `/api/status` (and the stage tracker, agent states and `governor.nextKickAt` derived from it) reflects an evaluation within seconds instead of after every due kick has been delivered — a phase that took 10–15 minutes on hosted hives and, when a rolling upgrade landed mid-dispatch, meant the evaluation never reached the dashboard at all. Snapshots the stale-build guard refuses are now logged at Warn and counted in a new `statusStaleDrops` field on `/api/status`. +- The Twitch matrix streamer no longer drops frames on every encoder hiccup: `VIDEO_QUEUE_FRAMES` defaults to 256, the audio queue is configurable (`AUDIO_QUEUE`), x11grab uses wallclock timestamps with `aresample=async=1` so audio/video PTS cannot drift, and a stall watchdog restarts ffmpeg when frames stop for 30 s or `speed` stays below 0.90x for 60 s, publishing its samples to `/run/stream/health.json`; the README gains a "Why does the player buffer?" diagnosis recipe. +- Twitch streamer (`src/deploy/stream`): no longer OOMKilled in a loop when the x264 encoder falls behind — the x11grab input queue is bounded (`VIDEO_QUEUE_FRAMES`, 16 raw frames instead of 1024, which could pin 8.5 GiB of MIT-SHM frames shared with Xvfb), x264 threads follow the cgroup CPU quota instead of `nproc`, Chromium runs with `--disable-dev-shm-usage --renderer-process-limit=1 --disable-extensions --js-flags=--max-old-space-size=1024`, the supervisor reloads the tab when Chromium's RSS passes `CHROMIUM_RSS_RELOAD_MIB`, and the Deployment requests 1 CPU / 3 Gi and limits 3 CPU / 6 Gi +- Twitch streamer self-heals: a watchdog asks Twitch whether the channel is live and restarts ffmpeg (then the pod) when ingest drops silently; probes now follow the watchdog heartbeat and tolerate Twitch's post-drop key lock. +- "Let hive decide" now tells the owner when a recorded decision never took effect and what to do about it: past `decisions.delegate.effect_timeout` (default 30m) a repeat click answers "Hive decided <plain action> at <time>, but it hasn't taken effect: <plain why>" with Merge as maintainer / Re-run decision / Close as superseded / Send back for a new commit as buttons, and the hive posts one plain-words follow-up on the item; every rule, verdict and reason is rendered from one glossary (Go + dashboard mirror) so slugs like `contributor-offline` or "supersede" are never shown bare; the delegate's `/hive decision` comment carries "Hive decided / Why / What happens next / If it doesn't happen"; and a decision comment the hive itself posted is never parsed as a reviewer's change request — the self-blocking seen on [#14822](https://github.com/hivecommons/hive/pull/14822). +- Delegated "supersede now" adoption decisions on trusted-bot PRs (`github-actions` and friends, observed on the self-authored lane) are executed instead of silently skipped every sweep with the `adoption/supersede` label left in place (hivecommons/docs#500 waited 15h); the supersede replays a conflicting head onto a fresh base first and, when that replay conflicts, posts one note naming the failure, consumes the request and keeps the PR on its fixing stage with reason `supersede-conflict`, and a request on the hive's own PR is refused once with a note rather than looping. +- Review aggregation no longer routes a hive-superseding PR to the fixer when every perspective's `requires_human` is a pure approver question with nothing above an informational finding. That route dispatched no-op fix kicks until the cycle was exhausted, then re-authored the same change (#16398 → #16456 → #16607) while the approver the reviewer asked never saw a decision. Such a head keeps its decision question, parks at `stage/085-needs-decision` with approve / request-changes actions, and the tracker's review chevron reads "waiting on a human approver · reviewer verified, needs sign-off". +- The dashboard's `/terminal` proxy now presents ttyd's basic-auth credential (`HIVE_TTYD_CREDENTIAL`, else `hive:<HIVE_DASHBOARD_TOKEN>` — the entrypoint's precedence) on every forwarded request, including the websocket upgrade, and drops any browser-supplied `Authorization` instead of relaying it. On token-protected spokes the already-authenticated browser was re-challenged by ttyd with a native user/password dialog after the dashboard had admitted it; the Node proxy's `/terminal` route is fixed the same way (#14693). +- Deflaked `test-issue-confirm-fixed.sh`: the DRY_RUN assertion piped `printf` into `grep -q`, which raced SIGPIPE under `pipefail` and intermittently failed `build-and-test`. (#16151) +- Fixed the tool-approval scan lane skipping its guardrail-path check for write tools it did not recognise by name ([#16976](https://github.com/hivecommons/hive/issues/16976)): `create`, `apply_patch`, `str_replace_editor`, `multi_edit`, `write_file` and any agent-specific editor tool writing `.github/workflows/**`, `OWNERS`, `CODEOWNERS`, `hive.yaml`, `policies/**`, `proxy/rules*` or `gh-wrapper*` auto-approved at L5/L6 where `write`/`edit` were denied. The check now holds every tool not classified read-only that names a file — an unrecognised tool name fails closed on those paths, so a read tool `IsReadOnly` does not spell is denied there until it is added (Copilot CLI's `view` is now spelled). `IsLocalWrite` spells the Copilot CLI and Codex editor tools too. +- Dashboard topbar: the ≡ drawer toggle is no longer clipped off the left edge on phones, and on ≤360px-wide screens the 🐛/⚙ chips collapse into the account menu (which gains a Settings entry) instead of overflowing the row. +- The dashboard topbar no longer shows an empty outlined pill between Settings and the health badge when every AI provider is usable: the hidden providers chip (`#oc-providers`) was still painted because the shared `.nav-chip` display rule outranked the `hidden` attribute. The chip now also carries a title/aria-label describing its state. +- The Hive activity monitor now lists every open issue and pull request from its `opened` webhook (with replay and poll fallback) instead of waiting for the governor's next publish, and renders a not-yet-staged item as a `000-new` row in the Open column that says who moves it next — a maintainer's triage label or the hive's stage-label pass — and when the next pass is due (#15094). +- Activity Monitor: while a row action is in flight the lit chevron shows one readable progress caption ("Queuing for merge…") on an opaque plate instead of a faint label over the stripes next to the old stage word (hivecommons/hive#15412). +- Hive Activity Monitor: every lit stage pill now draws its actor icon from a server-derived `stage_actor` (hive ⬡, contributor clanker, human, bot cog, or none with a "no one is working on this right now — why" tooltip) instead of guessing from the author; a bot-authored or unowned red PR reads "Conflicting · bot PR" / "Red · nobody on it" instead of an active "Fixing"; a PR closing several open issues is drawn once (`drawn_under`) with a "↳ #N · under #M" chip on the other issues; and the "Merged today" counter sits directly above the Merge gate / ✓ column header so the merge token's flight ends above the gate. +- Activity monitor row actions now show progress and never fail silently (hivecommons/hive#15436). **Close (read)** on an advisory row did nothing — an advisory is not a decision park, so the `decide:*` target mapping came up empty and the click returned without a request, a dialog or a toast. It now acts on the advisory row itself and really closes the issue (acknowledgement comment, closed as completed); an empty target list toasts a warning instead of returning silently. Every mutating row action (close-read, close-superseded, won't-fix, hold, approve, merge, decide) puts the chevron into the striped busy state with the verb as caption from the first byte sent, shows *Closed · leaving list* / *Merged · leaving list* once the server answers, and the server drops an operator-closed item from the tracker for `HIVE_OPERATOR_CLOSED_GRACE` (default 15m) so the row cannot come back before GitHub's list catches up. A close on an operator-paused repo is refused with the reason and writes nothing; refused, failed and network-errored actions restore the chevron, toast the reason and put it on the row's history badge (red, hover's first line), and the ledger records refused answers as `failed` with the one-line why. +- Describe failing author-owned PRs with unknown work activity instead of inferring that nobody is working from an absent Hive stage actor, including inline and nested PRs while preserving known Hive and bot routing. +- Activity Monitor: no status symbol rotates on a chevron or pill any more — the working glyph, the merge gate's ⟳ sweep glyph and the acting caption's spinner are static icons; their tooltips still say what the hive is doing (#15187). +- Every open issue in the Activity Monitor now offers a permission-checked Close issue action with an in-app confirmation; only the selected issue closes, leaving linked pull requests and other issues unchanged. +- Activity tracker: a follow-up or duplicate PR opened against an issue an earlier merge already delivered now reads `closed by #N` (the merged PR GitHub records as the closer, never an open PR with `Fixes #N`), or `closed · this PR unmerged` when no merged closer is known, instead of a bare `closed` chip that read as if the issue had been closed before its fix merged; docs state the rule that the hive closes an issue only after its PR merges +- A PR or issue closed on GitHub no longer reappears on the Hive activity monitor for minutes after the webhook re-read had already removed it. The eval cycle in flight at the time of the close published its status snapshot from the enumeration it started with (listing the item open), overwriting the webhook patch until the next full enumeration re-listed the repo (pluk#313 came back 4 s after closing and left again ~5 min later; up to `governor.eval_interval_webhook_s` plus a cycle in the worst case). Webhook re-reads are now remembered for `dashboard.stage_tracker.webhook_refresh_replay_window_s` (default `1800`) and re-applied to every status snapshot published meanwhile, monotonic on GitHub's `updated_at` so a later reopen still wins; repo issue / PR totals follow the patched lists, and a closed PR also takes its issues-feed copy with it. Closed items now leave within one dashboard poll. +- A closed issue or PR no longer stays on the Hive activity monitor when the confirming re-read a webhook delivery queues is refused (critical API budget, rate-limit caution window) or fails: the tracker now applies the payload's own `state` on every `issues`, `issue_comment` and `pull_request*` delivery, so a closed or merged item leaves on whichever action arrives (`labeled`, `unlabeled`, a comment — not only `closed`), its eviction is handed to the governor and remembered for replay like a re-read, and an open re-read older than the listed copy can neither rewrite the row nor un-remember a close (hivecommons/hive#14159 and #14064 sat at "Triage needed" / "Needs human decision" twenty minutes after closing, through the close, a bot comment and the stage-label sweep's unlabel). As a backstop for deliveries that never arrived, on each status publish it lists each repo's items closed since its last look every `dashboard.stage_tracker.closed_sweep_interval_s` (default `300`, one list call per repo, negative disables) and evicts any still shown. +- Activity Monitor: a PR the hive closed when it opened its replacement (close-first supersession) no longer renders under its issue as a bare sub-row with an empty ladder; the live replacement PR carries a small "supersedes #N" chip (hover: when it was closed, link) as the only trace, and the issue's ladder follows the live PR alone. +- Tracker Copy link now copies the selected issue or PR's canonical URL, including PRs linked or nested under issues, instead of copying the parent issue link. +- Show verified external merges at Activity Monitor's existing terminal step on root, inline and nested PR rows, using retained models and the actual recorded merger without inventing queue membership, Hive ownership or a second merge event. +- Hive activity monitor: the per-row select checkbox and ⋯ actions gutter is now present on every issue and PR row after every render path and always visible — dimmed at rest, full emphasis on hover/focus, on selected rows, and on all rows while a selection or the context menu is open — instead of a hover-only reveal that left an unpredictable, shifting subset of rows with a visible gutter as the live refresh swapped nodes under a still pointer (follow-up to [#13535](https://github.com/hivecommons/hive/pull/13535)). +- Activity Monitor: the right-most tracker column no longer shows a ✓ — the column header, the unmerged cap chevron and the "did I act on this?" badge now wear a history mark (clock with a counter-clockwise arrow); the badge is a neutral pill, carries the count of recorded actions and an aria-label, and keeps its hover history. The green ✓ remains only once a PR has merged. +- Explain exact-head human requirements separately from optional delegation and neutral ownership without inferring human presence, preserve covering-PR reasons and genuine current actions, reconcile old-head push requests and observed same-head CI retries, and keep pending head validation and requested review changes in CI/Review rather than implying approval or preparation admits a ready merge-queue seat. +- Keep informational trusted-author security notices separate from actual sentinel gates in Activity Monitor, quoting the real reviewer question without assigning exclusive decision authority to either the PR author or a person the reviewer mentions. +- Activity Monitor issue messages now follow covering PR progress instead of stale New/scanner captions, including links discovered from the PR side. +- Activity Monitor merge zap fires again: `recently_merged` entries recorded by the PR poller under a repo's short name (`repo=hive`) are now qualified to the `owner/name` the tracker rows carry, so human and observed merges match; a PR that drops off the open list a poll before its `pr_merged` audit entry lands is remembered as open until the entry arrives instead of being missed; a context the autoplay policy still holds suspended re-arms the gesture priming rather than queueing stale voices. New: a short bee-like buzz when an issue or PR first appears on the list (same opt-in chip, once per item, capped per refresh, silent on hidden tabs); turning the chip on plays one zap then one buzz. +- Keep Activity tracker chevrons compact on mobile while preserving their caption and icon alignment. +- Hive activity monitor: stage moves now animate on the live refresh. The hosted hive refreshes the tracker about once a second and the panel was rebuilt wholesale each time, cutting every move off after its opening flash; rows are now reconciled by item key so an in-flight move keeps its node, and rows leaving the list collapse out (`--ham-move-exit-ms`) while new rows fade in (`--ham-move-enter-ms`), both off under None or reduced motion. +- Hive Activity settings: the Movement animation preview no longer stacks a second, mis-sized chevron strip under the sample row; each Preview rebuilds the one sample row in place so it matches live tracker rows. +- Activity Monitor tracker: a human-authored PR waiting on its own author no longer leads with the red "Close as superseded" inline button (a close leads only when the server marks it `lead`, i.e. the reviewer named the superseding PR) and its pill reads "waiting on @author to push"; an issue and its asking nested PR render "Let hive decide" once, on the PR sub-row, instead of twice. +- Hive activity monitor: the `since` age now sits in line with the chevron strip and the status pill (`hold`, `stalled`, `unauthorized`, …) hugs the last title line directly over its own strip, with a hairline between entries and a whole-row hover tint, so a tall row (wrapped title, `↳ #PR` line) no longer floats its pill and age into the gap between two rows (#14640). +- Hive activity monitor: every row that involves a PR now draws the issue on the left and the PR on the right. A PR with no open linked issue shows a muted "no linked issue" (or "linked issue #N closed") placeholder in the issue slot and names itself in the PR column instead of standing in the issue slot with the PR column blank; `/api/stage-tracker` PR items carry `linked_issues` (GitHub's closing references for the PR body's Fixes/Closes/Resolves keywords) and a PR whose open issue is listed is paired with it from the PR side too ([#13421](https://github.com/hivecommons/hive/issues/13421)). +- Activity tracker ([#15589](https://github.com/hivecommons/hive/issues/15589)): a merge-queue chevron reads "Merge queued · 1st of 2" (the place with the queue length) and, when more than one train is on the page, names its train — "· train main.go" (the first overlapping file's basename, else the head `#N`) with a hover leading "Train of 2 PRs overlapping main.go; merges after #15567." — so two trains no longer show two unexplained "1st"s; the provisional suffix reads "queued 1st of 2 once ready" the same way, and each train's header and member rows share one left-rail accent colour so trains tell apart at a glance. +- Activity monitor: a PR whose body says `Refs #N` (or `Related to`, `Part of`, `Towards`, `See` …), whose title ends in `(#N, part 1)`, or whose first paragraph mentions an open issue, now sits on that issue's row under a muted `refs` chip instead of showing "no linked issue"; closing links still win and are drawn unchanged. +- Activity Monitor: a PR or issue by a registered contributor-hub clanker owner now reads as a clanker (author_kind_source `registry`) instead of an inferred person, so the row icon, its tooltip and the stage pill's holder ("@login's clanker") agree with the stage engine that adopts such PRs. +- An issue an open PR already covers (040) no longer falls to 020/010 — and books a spurious **regressed** badge on the activity monitor — when a contributor claims it, the claim is released, or a start mark lands between sweeps: the out-of-cycle stage-fact path now re-reads the remembered covering PR and keeps 040 while it is open. The `regressed` pill also explains itself: its tooltip, the row tooltip and the current-stage caption read "regressed: <from> → <to> at <time> because <reason>". +- Dashboard activity tracker: a pull request whose `Fixes #N` issue has already closed while the PR is still open is now anchored on the PR — the PR's number, title, stage and age lead the row and the closed issue becomes a muted `closes #N · closed` chip (plus `issue closed (not planned)` when GitHub says so) — instead of drawing the dead issue struck through as the headline (hivecommons/hive#14655). +- Activity Monitor: a PR whose linked issue is already closed keeps that issue as the row head (struck through, `closed` chip) instead of promoting the PR into the issue slot; when another merged PR closed the issue the chip reads `closed by #N` and links to it (#15232). +- Activity monitor hovers, the merge-gate chip popover, the ⋯ menu hints and the server captions say each thing once in plain words: the 090 "Ready for human merge" popover is now one sentence of state, one primary action ("Merge it") plus "More ⋯", who asked and when, and a collapsed Details holding how to trust the author and the rails; the untrusted-author reason, caption, next-move line and menu consequences lost their config keys, stage numbers and internal nouns and no longer repeat each other ([#15394](https://github.com/hivecommons/hive/issues/15394)). +- **Hive activity monitor: open-since age and one row count.** A plain *Open* chevron (no stage label yet, not on hold) now reads "Open · since 3d" ("since 14h" under two days), taken from the same instant the row's `since` column draws, with the ISO time in the chevron tooltip and a subtle red tint past two days (`STAGE_TRACKER_OPEN_STALE_DAYS`); *Open · hold* is unchanged, and an Open item carrying the `blocked` label gets its own "Open · blocked" word (⛔, hold's tint) that keeps the age — "Open · blocked · since 7h" — with the blocker (or the label) named in the chevron tooltip; hold wins when both are present. The sidebar badge and the list header no longer disagree: both are the **row count** of the default view from one shared function (the badge used to count open issues + PRs while the "of N" line counted rows, so a PR drawn on its issue's row made the badge read higher). That gap is now a footnote on the "showing" line's tooltip and the badge — "2 PRs shown on their issue's row" — and each such PR is led by a ↳ glyph whose link tooltip explains the shared row (and names the other issue when two list the same PR). A PR whose issue a filter hides still renders as its own row. +- Activity Monitor sounds work for every repo the hive governs: the client-side short-name resolution for `recently_merged` now learns `owner/name` from every item of every repo (issues included), so a repo whose last open PR just merged still zaps; the multi-repo path (server-side qualification over all configured repos, merge/new-item detection over the union of all repos' items) is now pinned by tests. +- Activity Monitor: a PR under repair — being fixed, waiting on its author or contributor, parked on a human decision, or with a red required check — is no longer a merge-train member. The planner skips it, the tracker drops it from the train with a muted hover note ("left the merge train while being fixed; rejoins when green"), the remaining members close ranks (count, ordinals, front), and a train left with one PR renders no header and no ordinal. Hive's own #15405 led a header as "1st: #15405" while its chevron read "Fixing" ([#15615](https://github.com/hivecommons/hive/issues/15615)). +- The shared tracker row asset now exports `trackerrow.RequiredGlobals`, the `STAGE_TRACKER_*` constants it reads from its host page pinned to the spoke's values, and tests fail if that list drifts from the asset or if the spoke declares a different value, so the hub cannot silently light different columns than the spoke. `dashboard-source-layout.md` also lists `tracker-human-attention` in manifest order (#16067, #16068). +- Activity Monitor: a PR queued in the base preparation train whose current head is already approved now reads "Approved N/M · queued for base refresh behind PR #<front>" instead of "waiting for a verdict on the current head" (hivecommons/hive#16756). +- Fix inference-gateway requests failing with `tool_use ids were found without tool_result blocks` when a Claude Code user turn carries text alongside a tool result: the translator now emits the `tool` messages directly after the assistant `tool_calls`, before the text. +- Activity Monitor: an issue the reporter-trust gate holds for a maintainer now reads **Triage needed** in the Open column (chevron, hover and row headline) from the moment the gate holds it, with the `needs-triage` modifier and the inline **Accept triage** lead — instead of **New** with the ask only in the caption, as hivecommons/hive#15437–#15440 did before the awaiting label landed; the caption of every held row (000-new or 015) is now exactly *Triage needed — accept or close* instead of repeating *triage* three times. +- Stage engine: `stage/015-triage-needed` is now derived only for issues the reporter-trust gate is holding (`needs-triage` label or the `reporter_triage` bucket); issues filed by hive agents or trusted humans are triaged by construction and stay `010-actionable` instead of being demoted to 015. +- Refresh persisted triage acceptance into the work queue and activity monitor on first acceptance and idempotent retries, reporting handoff failures instead of showing an unconfirmed success. +- Trust-promotion announcement records in the stage-label store are no longer exempt from `Prune` forever: they are now dropped once unseen for 180 days (or the prune age if longer), so the store stops accumulating one record per contributor while an author is still not re-announced within that window (#15463). +- Contributor-lane auto-promotion is announced once per author per hive instead of on every open PR by the author at once: the first PR that earns it gets one shorter, author-wide comment ("@login is now trusted for contributor-lane merging in this hive …"), the author's other open and later PRs post nothing, the announced fact survives restarts in the stage store, and a demotion followed by re-promotion announces once more ([#15443](https://github.com/hivecommons/hive/issues/15443)). +- Activity Monitor: a row never lights more than two chevrons, and a filled chevron now always means "this is where the item is / what is in motion". CI and Review are filled (amber) only while a check-run or a review perspective is actually running on the current head; passed / approved, findings, pending and decided verdicts are words in their colour on the muted field. Unreported checks and rows waiting on a person render as pending words, never amber. When both tracks run, the stage chevron is settled-current. A queued review swarm reads "Review 0/5 · swarm requested" instead of 5/5 (#16540). +- Refresh an issue's cached tracker snapshot after an accepted maintainer decision so its Actionable ribbon no longer retains stale needs-human badges and decision questions while waiting for a GitHub webhook. +- Show temporary upgrade holds as Delayed instead of missed windows, and clear resolved delay warnings after a successful upgrade on both dashboards, including older history entries. +- `hive validate` now lists base-config `launch_cmd` entries dropped for contradicting their backend and exits non-zero instead of printing "config OK" (#15769) +- Activity Monitor CI chevron counts (`CI 7/11`) are now driven by `check_run`/`workflow_job`/`status` webhook deliveries applied straight into a per-head check set — no PR re-read per check fan-out — with one coalesced check-run listing only when the head has none yet, so rows no longer sit at `CI ?/?` after a push or for sidelined PRs until the next eval cycle; `/api/status.webhooks` gains `last_ci_event_at`, `ci_events_1h`, `ci_events_applied_1h`, `ci_refetches_1h` and the hub relays `workflow_run`/`workflow_job` (hivecommons/hive#16521) +- review: a not-hive-authored head whose fix is withheld is now reported in `FixExclusions` only on the cycle that first withholds it, matching `auditWithheldReviewFixes`' doc instead of repeating every eval cycle (#14882, #14883). +- The contributor lane now binds an unmarked owner approval (a typed `/hive decision approve`, or a dashboard `/approve` posted without a head marker) to the time GitHub first showed the PR's current head, never to the head commit's committer date. That date is written by the pusher's git, so a later push carrying a backdated commit could inherit an approval given on the head before it and release the workflow-path fence for a diff the approver never saw. An approval older than the observed head now leaves the fence armed, exactly like an APPROVED review on a stale commit; the approver re-approves the new head to release it. This is deliberately fail-closed and slightly narrower than before: the observed time is pinned on the hive's first sweep of the head, and any comment or label that lands between the push and that sweep moves it later, so an approval typed in that gap is also treated as stale and has to be typed again. A head with no pinned time yet binds nothing. +- Preserve durable write counter totals and retry pending counts after transient file read errors ([#14531](https://github.com/hivecommons/hive/issues/14531)). +- Write-back containment: every unsolicited GitHub comment, label and review from platform sweeps (sentinel, hold-gate notices, stage labels, supersession, duplicate-fix, reporter-trust) now passes one central per-kind gate (`writeback.*`) that requires both an ACMM floor and the review opt-in label on foreign PRs, never back-fills onto PRs that predate hive's write access, and surfaces suppressed writes in the dashboard instead of on GitHub +- Restore the writeback direct-write ratchet on `v5`: the lapsed claimed-by label removal added in #16849 is annotated as gated, so `TestDirectWriteRatchet` passes again for every PR based on `v5` + +### Security + +- Stage-074 adoption now applies the contributor lane's diff fences before taking over a contributor PR: a PR that touches CI workflow/action definitions, deletes or guts tests, or whose file list cannot be read is no longer adopted in place or superseded by an App PR (including the `dco-rehome` takeover); it stays at stage 072 with a logged `contributor-lane:*` reason ([#12850](https://github.com/hivecommons/hive/issues/12850)). +- `hivectl hives web` now rejects requests whose `Host` is not a loopback host on the listening port (DNS-rebinding protection) and cross-origin browser requests (`Origin` / `Sec-Fetch-Site`), sends `Cache-Control: no-store`, `Referrer-Policy: no-referrer` and `X-Content-Type-Options: nosniff` on every response, and the page removes the launch token from the URL and browser history once loaded. Token auth is unchanged. ([#13178](https://github.com/hivecommons/hive/issues/13178), part of [#13153](https://github.com/hivecommons/hive/issues/13153)) +- The local `hivectl hives web` API now accepts its access token only through the `X-Hive-Commons-Token` header, preventing API credentials from leaking through query strings ([#13245](https://github.com/hivecommons/hive/issues/13245)). +- Image builds compile with Go 1.27.3: the `golang:1.27-alpine` builder digest in `src/Dockerfile`, `src/Dockerfile.hub`, `src/Dockerfile.contributor` and the base-registry probe now resolves to `1.27.3-alpine` instead of `1.27.2-alpine`, and the contributor image's standalone toolchain moves from Go 1.24.4 to 1.27.3, so the shipped `hive`, `hivectl`, `bd` and hub binaries carry the `crypto/x509` fix for GO-2026-6809 ([#13329](https://github.com/hivecommons/hive/issues/13329)). +- Dashboard review-evidence downloads, listings, aggregates, tracker annotations, heartbeats, and evidence-derived metrics now verify bundle signatures against the configured Ed25519 key before using on-disk data; unsigned mode still verifies content hashes, while an unavailable configured key or tampered bundle fails closed ([#13900](https://github.com/hivecommons/hive/issues/13900)). +- Keep the hive PR open and parked when a clean competing contributor PR references the same issue; delegated decisions now recommend a human adequacy comparison instead of automatically closing the hive's work ([#13998](https://github.com/hivecommons/hive/issues/13998)). +- Refuse to publish contributor workflow/action edits into upstream adoption branches, and revalidate head evidence before every supersession. The refusal is recorded once per head: the PR gets one note and moves to needs-decision instead of being re-checked every sweep. +- The proxy's plain-HTTP forward path now identifies its caller and refuses destinations that are not globally routable — loopback, link-local (cloud instance metadata), RFC 1918, CGNAT and multicast — checked at dial time so a hostname resolving inward is refused too; set `HIVE_PROXY_ALLOW_PRIVATE_FORWARD=true` to allow them (#14082) +- The proxy write-gate rule table mirrors GitHub posture for GitLab and Gitea/Forgejo: direct MR/PR creation and merge are hard-denied for every agent level (forcing the hive-open-pr and hive-merge request-file paths as the bot identity), reads and issues/comments/labels follow the ACMM ladder, and unknown routes fail closed ([#14114](https://github.com/hivecommons/hive/issues/14114), part of [#14096](https://github.com/hivecommons/hive/issues/14096)). +- "Let hive decide" (`POST …/items/{number}/decide-delegated`) no longer reads a pull request head as CI-green from `mergeable_state` alone. GitHub reports `blocked` both for a missing required review and for red required checks, and `unknown`/`behind` say nothing about the head, so the delegate could approve a PR whose required checks were failing or had never run and record it as a "green head" decision. The gatherer now settles those states from the head's combined status and check runs — no red, nothing pending, at least one green — the same way it already judged a competing PR, and such heads get the `fix-then-merge` direction instead of an approval ([#14167](https://github.com/hivecommons/hive/issues/14167)). +- Limit GitHub claim-effect processing to one worker per active issue so claim/release churn no longer accumulates waiting goroutines; queued effects still run in order without dropping release cleanup. +- The hive capability endpoint (`callback.Listen`, bound from `$CRUX_HIVE_LISTEN`) now refuses a TCP address off loopback, the same fail-closed rule `crux serve --listen` has applied since #13967. The listener is plain http gated by `$CRUX_HIVE_TOKEN`, and it serves `POST /v1/tokens`, which mints GitHub App installation tokens — a routable bind would have carried both the bearer token and every minted token across the network in cleartext. The k8s sidecar-container option is unaffected: the containers share the pod's network namespace, so `127.0.0.1` reaches the sidecar. Remote access goes through a TLS-terminating proxy. (#14348) +- The inference translator on `127.0.0.1:18444` now names its caller from the socket owner's UID, the way the GitHub proxy path and the decision endpoint already do, instead of from the `x-api-key` header the caller chose. That header is `sk-hive-<agent name>` and the name is public inside the pod, so any local process could previously borrow a different agent's inference route — backend, model, upstream credential and usage attribution. A mapped agent UID is authoritative (a header naming someone else is logged and overridden), the hive's own control plane keeps the header name, and an unidentifiable caller is refused with 401 unless `HIVE_PROXY_ADVISORY_OK=true`. The translator server also gained a `ReadHeaderTimeout` ([#14439](https://github.com/hivecommons/hive/issues/14439)). +- Refuse proxy-owned inference translator requests unless advisory identity is explicitly enabled, preventing forged agent identities through private plain-HTTP forwarding when `HIVE_PROXY_ALLOW_PRIVATE_FORWARD=true` (#14448). +- Keep raw IOScan classifier errors, including private endpoint URLs and DNS details, in local logs rather than public selfreport diagnostics. +- Prevent comment-only PR cross-references from moving issues to Reviewing or Closed in the dashboard; timeline PR links now require a closing keyword in the PR title or body ([#14985](https://github.com/hivecommons/hive/issues/14985)). +- A rebase-then-merge follow-through no longer treats an unsigned head as the hive's own just because its author email is the App bot's noreply address: an author GitHub resolves to the App bot now counts only on a commit GitHub reports as verified, as GitHub's update-branch commits are ([#15421](https://github.com/hivecommons/hive/issues/15421)). +- The hold guard no longer treats an approval carried from an adopted PR as proof that a trusted merger reviewed the copy's current head ([#15698](https://github.com/hivecommons/hive/issues/15698)). +- Agent NO_PROXY only appends the OMP_AUTH_BROKER_URL host when it is a concrete hostname or IP, so a wildcard or leading-dot host can no longer widen the proxy bypass (#15726) +- Fix tool approval's built-in destructive-command detection for root/home removal and fork bombs without relying on host text-scanner findings, and avoid matching removal of ordinary subpaths ([#15727](https://github.com/hivecommons/hive/issues/15727)). +- Redact credentials from logged errors, Stringer, TextAppender and TextMarshaler values (including marshal errors), and resolved LogValuer attributes, including nested groups and bound logger attributes ([#15729](https://github.com/hivecommons/hive/issues/15729)). Text-rendered attributes are now emitted as strings, including in JSON logs where a value implementing `json.Marshaler` may previously have emitted a number or object. +- The built-in destructive-command check now also matches equivalent root and home removal spellings such as `rm -rf //`, `rm -rf /.`, `rm -rf "/"`, `rm -r -f /` and `rm -rf ${HOME}`, instead of relying solely on the host text scanner ([#15740](https://github.com/hivecommons/hive/issues/15740)). +- The built-in destructive-`rm` check in `crux/toolapprove` now reads a command the way bash would hand it to `rm`, without running anything, and judges what each target means rather than how it is spelled ([#16094](https://github.com/hivecommons/hive/issues/16094)). Quoting and escapes, `$'…'` strings, brace expansion (`/{,}`, `{rm,-rf,/}`), `.`/`..` components (`/tmp/..`, `$PWD/../../..`), `$IFS` splitting, subshells, command substitutions and re-quoted commands (`bash -c '…'`, `eval`) now resolve to the same verdict as plain `rm -rf /`. A recursive `rm` of the root, the home directory, the working directory or any ancestor of one is flagged. That set now includes `rm -rf .`, `./*`, `..` and `"$PWD"`, matching the existing treatment of `rm -rf *`. A new spelling-equivalence test derives about 70,000 bash-equivalent commands from destructive and safe seeds and gates every detector change on them. The analysis has explicit limits: 1024 brace words per word, nesting 32 brace groups and 8 re-read levels deep, and a work budget proportional to the command. A command past them is reported as a separate `shell command exceeds destructive-command analysis bounds` violation instead of passing clean. The `rm` branch of the old regex is retired, so its false positives no longer fire: non-recursive `rm -f /`, literal `'$HOME'` and `"~"`, and `a=rm -rf /`. An `rm` that is the subcommand of a version-control tool (`git rm -r --cached .`, `hg rm`, `svn rm`) is not the binary and is not flagged. +- The contributor lane's workflow-path approval no longer accepts an edited comment as an approval: a `/hive decision approve` (or dashboard `/approve`) whose comment was modified after it was posted is ignored, the same rule the un-park sweep already applies, so rewriting a merger's earlier comment cannot be read as that merger's approval (#16127). +- The push broker's trailing-newline normaliser now resolves each changed file's parent directory and skips any path that escapes the workspace through a symlinked directory, as it already did for a committed symlink at the leaf. Since the normaliser began committing HEAD's blob rather than the working-tree bytes, an agent that committed `dir/file` and then swapped `dir/` for a symlink out of the sandbox workspace could have had that blob written briefly into a hive-owned file by the host-side broker before the restore put it back ([#16211](https://github.com/hivecommons/hive/issues/16211)). +- Require human policy sign-off for reviewer questions on workflow and action edits, including same-repository PRs. +- Harden Activity Monitor source-work verification with credential-free, bounded, read-only Git inspection that cannot execute workspace hooks, filters or helpers; unsupported normalization and unstable repository evidence stay unknown. +- Base-preparation state files and directory are no longer created group-writable (0o644/0o755, matching the stage store). (#15844) +- A recorded decision, and the base-preparation proof, now follow a PR onto a new head only when the merge commit is one GitHub created and verified (signed, committed by `web-flow` or the App) rather than any commit whose author email resolves to the App bot, and a base...head compare that reaches GitHub's 300-file listing cap fails closed instead of being compared on a truncated file list ([#16860](https://github.com/hivecommons/hive/issues/16860)). +- Contributor registration tokens expire after 90 days by default, support an optional inactivity cutoff, and can be inspected or revoked individually or in bulk from Management and `hivectl contribute tokens`; GitHub-authenticated `hivectl contribute login` rotates expired tokens, while legacy credentials receive persisted migration-time issuance dates (#13804). +- Bump golang.org/x/net to v0.62.0 in src/crux to clear GO-2026-6617/6612/6611/6603 (govulncheck red on hivecommons/crux main). +- Dashboard directions for contributor PRs now require the sweep's classification label, honoring `governor.labels.author` names, instead of falling back directly to PR-body markers; the sweep's body-marker classification remains unchanged ([#15268](https://github.com/hivecommons/hive/issues/15268)). +- Deleting a registry-only hive now requires being its owner or a hub admin; entries whose spoke never reported an owner are admin-only (#16134) +- Discord notifications and RFC notices no longer ping @everyone or roles from untrusted text such as issue titles +- Bumped the Go toolchain to 1.26.10 so the `govulncheck` gate stops flagging GO-2026-6809 (`crypto/x509` certificate verification), reachable from the dashboard's HTTP server. The gate was red on the default branch itself, blocking every open PR. +- Bump golang.org/x/net to v0.62.0 to clear GO-2026-6860 (govulncheck). +- The hold guard only advances a held PR's reviewed baseline after a merge-from-base when the new head is a two-parent merge of a base-branch commit into the head the hive asked to update, so a contributor push racing the update is no longer adopted as reviewed hygiene; the base parent is matched against the live base branch, so a base that moved before the update does not turn the hive's own merge into drift ([#14534](https://github.com/hivecommons/hive/issues/14534)). +- Scrub `[]byte`, `[]string`, map, struct and other composite log attributes (and `TextMarshaler` values) so credential-shaped tokens no longer bypass the log scrubber ([#15735](https://github.com/hivecommons/hive/issues/15735), [#15736](https://github.com/hivecommons/hive/issues/15736)). +- A hive authenticated with a personal access token and no configured identity now learns its own login from `GET /user`, so a once-only marker (unpark reply, label-approval, sentinel) pasted by another commenter is no longer trusted; hives that cannot reach `/user` keep the previous behavior ([#13520](https://github.com/hivecommons/hive/issues/13520)). +- Bumped transitive `body-parser` to 2.4.0 and `qs` to 6.17.1 in `src/proxy/package-lock.json` (GHSA-27r3-jxmh-p828, GHSA-6pq8-jhm2-2vcw), matching what `dashboard/` already pins, and `undici` to 6.29.1 in `discord/package-lock.json` (GHSA-2m5v-pch6-74hx TLS option drop and four DoS advisories). `/discord` now has its own Dependabot npm entry so the directory gets the same weekly coverage as `/src/proxy` and `/dashboard`. +- The `auto_merge.human_merge_pin_only` exception now verifies the commits behind the head, not only the PR author login: every commit must be authored by a `trusted_authors` login, committed by GitHub itself (`web-flow`) or a `trusted_authors` login, and carry a GitHub-verified signature (which binds to the committer, not the author), and the list must end at the current head. Before, anyone with write access could push a pin-shaped commit onto a trusted author's branch (a `dependabot/...` branch keeps `dependabot[bot]` as PR author) and have the sweep or `/approve` waive the human-merge-path hold on it. Unsigned or foreign commits, an unreadable or empty commit list, or a list that does not end at the head now hold the PR as before; the commit list is read only once the diff already qualifies, so refused PRs cost no extra API call. +- The opt-in `auto_merge.human_merge_pin_only` exception now admits an `action-sha` pin only when the new SHA is anchored in its upstream action repository: with a `# vX[.Y[.Z]]` comment the upstream `tags/vX…` ref (annotated tags dereferenced) must point at exactly that SHA, otherwise the SHA must be an ancestor of the upstream default branch ([#16399](https://github.com/hivecommons/hive/issues/16399)). GitHub resolves a `uses:` SHA across the whole fork network, so a pin-shaped line could otherwise point at a commit pushed to any fork. Any 404, mismatch, rate limit or API error keeps the human-merge-path hold; repos without the key are unaffected. The pin-only commit check now uses the shared PR commit lister ([#16401](https://github.com/hivecommons/hive/issues/16401)). +- Pushbroker now checks both source and destination paths of renamed files, preventing protected workflows, policies, and other guarded files from being moved out of protected paths to bypass the push gate ([#15728](https://github.com/hivecommons/hive/issues/15728)). +- RFC lifecycle notices no longer post RFCs from private repositories (titles and links) to `notifications.discord.rfc_channel_id` unless `notifications.discord.rfc_include_private: true` authorizes it. The gate applies in every mode, line mode included. Repo visibility is resolved once per repo and cached for an hour. A repo whose visibility cannot be resolved, or that is `internal`, counts as private (fail closed). Withheld RFCs still advance the detector state, so they never replay later (#15926, part of #15869). +- The sentinel no longer releases an alert on a dashboard-approval comment, nor writes its clearance record into an existing marker comment, unless one of the hive's own known accounts wrote it: a hive that cannot name its own accounts no longer falls back to trusting any author there, so a PR author cannot forge the release for their own head ([#15262](https://github.com/hivecommons/hive/issues/15262)). Skipping the dashboard `/lgtm` + `/approve` commands after a Prow rejection now believes only the Prow bot (`kubestellar-prow[bot]`), not any installed bot quoting the rejection phrase ([#15263](https://github.com/hivecommons/hive/issues/15263)). +- The Activity Monitor streamer's loopback `authproxy` (`src/deploy/stream`) now forwards only `GET`/`HEAD` to the dashboard and answers every other method `405` locally, before the bearer is attached. The token it injects is the spoke's shared dashboard token, which the dashboard treats as an unscoped owner; the kiosk only ever reads, so a compromised or misbehaving page in the `--no-sandbox` Chromium can no longer reach agent-control, config or settings mutations with that authority. +- Fixed the tool-approval guardrail-path check never seeing the target of a Copilot CLI `apply_patch` call ([#16979](https://github.com/hivecommons/hive/issues/16979)). The tool carries its paths in the patch text (`*** Update File:`, `*** Add File:`, `*** Delete File:`, `*** Move to:`) instead of a path argument, so `ToolRequest.GetFilePath` returned an empty string and a patch touching `.github/workflows/**`, `OWNERS`, `hive.yaml` or `policies/**` auto-approved at L5/L6. `GetFilePath` now falls back to the first path in the patch body, and the guardrail check now iterates the new `GetFilePaths` over every path the request names, so a patch that lists a harmless file first and a guardrail path later is still caught. + ## 2026-10-18 (v5.186.4) ### Fixed diff --git a/ROADMAP.md b/ROADMAP.md index 606e074fd0..f7133889e1 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -16,7 +16,7 @@ plan (Now / Next / Later, item by item), see the | --- | --- | --- | --- | | v4 | `v4` | Maintenance line (feature-frozen; security/critical fixes only) | none — builds publish `v4-latest` and short-SHA tags only ([#7721](https://github.com/hivecommons/hive/issues/7721) Phase 1) | | v5 | `v5` (default) | Supported stable line since the 2026-09-21 cut-over | `stable`, `candidate`, `latest` | -| v6 | `v6` | Active development, tracks v5 by forward-merge; the #7563 dashboard-optional tracks are merged on the branch (see [v6 section](#v6--dashboard-optional-operation-line-open)) | `edge` | +| v6 | `v6` | Release line since 2026-11-07 (cuts `v6.x.y` tags, GitHub Releases and SBOMs from the branch; first tag `v6.0.0`); tracks v5 by forward-merge, and the #7563 dashboard-optional tracks are merged on the branch (see [v6 section](#v6--dashboard-optional-operation-line-open)) | `edge` (plus `v6-latest`); `stable`/`candidate`/`latest` stay on v5 | Operators select a line by pointing a hive at a [release channel](src/docs/release-channels.md) rather than a branch tag. diff --git a/changelog.d/added-v6-release-line.md b/changelog.d/added-v6-release-line.md new file mode 100644 index 0000000000..4d2738f3d3 --- /dev/null +++ b/changelog.d/added-v6-release-line.md @@ -0,0 +1 @@ +- `v6` is now an official release line: `.github/release-lines.yml` lists `[v4, v5, v6]`, so `tagged-release.yml` mints `v6.x.y` tags (starting at `v6.0.0`), GitHub Releases, SBOMs and immutable image retags from the `v6` branch exactly as `v5` does; the default-branch copy of the workflow relays a completed `v6` build to `v6`'s own copy, since GitHub only delivers `workflow_run` to the default branch. Channel ownership is unchanged — `stable`/`candidate`/`:latest` follow `v5`, `edge`/`v6-latest` follow `v6`. diff --git a/changelog.d/changed-contributor-nudge-dedupe.md b/changelog.d/changed-contributor-nudge-dedupe.md new file mode 100644 index 0000000000..3d5e879937 --- /dev/null +++ b/changelog.d/changed-contributor-nudge-dedupe.md @@ -0,0 +1 @@ +- Contributor nudges are now one comment per PR and reason class, edited in place for a new head or changed reason, with a single re-nudge after `auto_merge.nudge_repeat_after` (default 72h); an agent's free-text relay comments fold into the `hive:status` card in quiet mode or one `hive:origin-notes` comment per item otherwise; a marker ratchet test caps unmarked bot comment emitters (hivecommons/hive#17067). diff --git a/changelog.d/security-crux-checkout-allowlist-boundary.md b/changelog.d/security-crux-checkout-allowlist-boundary.md new file mode 100644 index 0000000000..9f5743165e --- /dev/null +++ b/changelog.d/security-crux-checkout-allowlist-boundary.md @@ -0,0 +1 @@ +- The pinned-checkout service's repository allowlist now matches on URL segment boundaries and refuses non-canonical repository paths. Previously `CRUX_CHECKOUT_ALLOWLIST` was compared as a plain string prefix against the URL the caller sent, so `https://host/allowed/../other/repo` (which git resolves to `other/repo`), `file:///allowed/../../elsewhere`, and `https://host/allowed-evil/repo` all passed for an entry of `https://host/allowed`. Requests whose path contains `.`, `..`, empty or percent-encoded segments are now rejected as bad requests before any clone, and a prefix that does not end in `/` must be followed by `/`, `.git` or the end of the URL. diff --git a/docs/rfc-17054-llm-ranked-knowledge-advisor.md b/docs/rfc-17054-llm-ranked-knowledge-advisor.md new file mode 100644 index 0000000000..387825fc7e --- /dev/null +++ b/docs/rfc-17054-llm-ranked-knowledge-advisor.md @@ -0,0 +1,323 @@ +# RFC #17054: LLM-ranked knowledge advisor (phase 2) + +Status: proposal, for discussion on #17054 +Refs: #17054, #17052 (phase 1, implemented by PR #17068), #17045 / PR #17060 +(scoped entries), #17043, 2026-11-05 Hive Commons community meeting + +## Summary + +Phase 1 (#17052) is a pure matcher. The runtime parses each agent's pane for +scopes it has entered since the kick: a source directory, or a `gh` command +family. It asks the hive-side `crux.KnowledgeAdviser` for matching entries +(`Primer.PrimeScoped`, BM25 + Fisher-Rao), then types up to +`knowledge.advisor_max_per_kick` `📚 Knowledge:` lines into the live session. + +This RFC proposes an optional **advisor pass** that runs between the matcher +and delivery. A small model gets the kick's task summary, the tail of the +agent's pane, and the matcher's candidates. It returns either nothing or **one +candidate slug** plus a one-sentence reason. The runtime then delivers the +chosen entry with phase 1's primitive, line format, caps and gates. + +The recommendations, argued below: + +| Question | Recommendation | +| --- | --- | +| Ranker vs. generator | **Rank only.** The model returns a slug, which must be one of the candidates. The agent never sees model-written text: the reason goes to the decision record, not to the pane. | +| Budget | Per-agent hourly call cap plus a fleet-wide daily cap. Both are hive-side counters, charged to the hive's `governor.litellm` key and attributed per agent. The pass does not draw on the agent's own backend spend. | +| Where it runs | In the hive process, behind phase 1's `KnowledgeAdviser` seam. The model call must not run on the poll goroutine. Sidecar support comes with phase 1's planned `/v1/knowledge/advise` callback. | +| Signal | Kick summary plus the last 80 pane lines (scrubbed). No proxy GitHub calls and no JSONL transcript in the first cut. | +| Measurement | A shadow mode, then a per-kick holdout, with outcomes compared from the retro lane's existing counters. No "did this help" line. | + +## What exists today + +All of the following are on `v5` unless noted: + +- **Matcher.** `knowledge.Primer.PrimeScoped(ctx, scope, filePaths, keywords)` + in `src/pkg/knowledge/primer.go` runs BM25 search over the wiki layers and + the local `FileStore`. It then applies lifecycle and scope filters, + Fisher-Rao reranking (blended with BM25 weight 0.4) and priority, and cuts + to `MaxFacts`. The kick calls it from `Scheduler.primeKnowledge` + (`src/pkg/scheduler/kick_priming.go`). +- **Phase 1 seam (PR #17068, open).** `crux.KnowledgeAdviser` has two methods: + - `Policy(agent)` + - `Advise(agent, KnowledgeScope) []KnowledgeAdvice` + + The contract is that `Advise` "runs on the agent's poll goroutine and must + be bounded". The hive-side implementation (`cmd/hive/knowledge_adviser.go`) + gives `PrimeScoped` a 5 s timeout and returns at most 2 entries per scope. + Deliveries are recorded in prompt history with the trigger + `knowledge-advisor`. The seam is in-process only: in sidecar mode the + runtime has no adviser. +- **In-process model calls.** Hive has no shared completion helper. Each + feature carries its own small OpenAI-compatible client with a + `Complete(ctx, messages, maxTokens)` method: + - the retro analysis, `src/pkg/retro/analysis.go` (`retro.analysis_model`); + - the trajectory reviewer, `src/crux/trajectory` (`governor.trajectory`, + resolved by `GovernorConfig.ResolveReviewer`); + - the ioscan classifier, `src/pkg/ioscan`. It wraps its CLI client in a + per-UTC-day call cap (`NewDailyQuotaClassifier`, `cli_daily_quota`). + + All of these default to the `governor.litellm` endpoint and key. The retro + analysis makes no model call while `retro.analysis_model` is empty. Model + output is parsed with `jsonextract.Object`. +- **"Advisor" in the codebase today is not a model tier.** The `advisor` tier + in `hub.tier_limits` / `ContributorLaneGrantableTiers` is a contributor + trust tier. The `advisor` GitHub token tier (`AgentMode.TokenTier`) mints + read-only tokens. OMP's `--advisor` model is display-only metadata on + contributor PRs. The issue's "the `advisor` lane tier" therefore has nothing + to route to. The advisor pass needs its own model setting, like + `retro.analysis_model`. +- **Per-agent budget precedent.** `src/crux/proxy/agent_github_budget.go` + counts each agent's GitHub API calls through the proxy in a rolling one-hour + window (`agents.github_api_hourly_cap`, default 300). +- **Pane scrubbing.** `crux/logscrub.RedactPaneTokens` and `ScrubString` + already redact GitHub tokens, `sk-…` keys and the per-agent `sk-hive-<agent>` + LiteLLM keys from pane text before it leaves the runtime. +- **Retro lane.** The model call is in `pkg/retro` (`Lane.Run` → + `Analyzer.Analyze`). It works on a compact `RetroRecord` of counters (fix + attempts, kicks, drift pauses) plus PR and issue refs. `pkg/knowledge/retro_lesson.go` + only quality-gates, dedupes and stores the resulting lesson. Neither reads a + PR body or a diff, so "the retro pass looks for the slug in the PR" would be + new code, not an existing hook. + +## Design + +### Pipeline + +```mermaid +flowchart LR + P[poll tick: new scope] --> M[phase-1 matcher<br/>PrimeScoped, minus kick slugs<br/>minus delivered slugs] + M -->|0 candidates| X[drop] + M -->|1..N candidates| G{advisor_llm.mode} + G -->|off| D[deliver top-1<br/>phase 1 unchanged] + G -->|shadow| S[deliver top-1<br/>record model pick] + G -->|rank| R[model: slug or none] + R -->|none / invalid / error / over budget| X + R -->|slug in candidates| D2[deliver that entry<br/>same gates and caps] +``` + +1. **Candidates.** The phase-1 matcher runs unchanged. It asks for up to + `candidates` (default 5) entries instead of 2. Entries the kick block + rendered or that were already delivered this kick are removed first. With + zero candidates, no model call is made. +2. **Call.** One chat completion with `temperature: 0` and a small output cap + (about 120 tokens). The response must be one JSON object: + `{"slug": "<candidate slug>" | null, "reason": "<≤200 chars>"}`. +3. **Validation.** The runtime parses the object with `jsonextract.Object`. + A `slug` that is not exactly one of the candidates, or a malformed + response, is treated as `null`. The pass never invents an entry. There is + no corrective retry: a wrong answer costs at most one silent scope, while a + retry doubles the spend. +4. **Delivery.** The runtime types the chosen entry using phase 1's line + (`📚 Knowledge: <title> — <summary> (full: <ref>)`). Phase 1's + `advisor_max_per_kick`, cooldown, mid-tool-call, attached-human and + `kickDelivering` gates all apply. The model's `reason` is **not typed**. It + is recorded with the decision (see Measurement). + +### Ranker vs. generator: rank only + +Generation, which is what OMP's advisor does, lets the model write the hint. +This RFC rejects generation for the first LLM cut, for three reasons: + +- **Audit.** Every line an agent receives stays a stored, reviewable + knowledge entry with a slug and a source. "Why did the agent do X?" can be + answered from the entry, not from a model sample that no longer exists. +- **Prompt injection.** The pane holds untrusted text: issue bodies, PR + comments and tool output from strangers. The rank-only output space is the + set {candidates} ∪ {nothing}. A hostile pane can at most make the advisor + pick a weaker candidate or stay silent. It cannot make the runtime type + attacker-chosen text into another agent's session. This is also why the + `reason` is not typed: it is model-generated free text derived from that + same pane. +- **Phase-1 bound preserved.** #17052's invariant is "the advisor can never + show an agent something its kick could not". Rank-only keeps it. + +Generation can be reconsidered once there is measured evidence that ranked +entries are acted on, and that their wording, not their selection, is the +bottleneck. + +### Timing + +Phase 1 fires on the first sighting of a scope. The advisor pass handles +timing in two ways: + +- **`null` is a first-class answer.** The prompt tells the model to return + `null` unless the pane shows the agent about to act in this scope, for + example opening a file for edit or composing a `gh` command. A passing + `grep` should get `null`. +- **One re-evaluation per scope.** A `null` decision leaves the scope + eligible for exactly one more call. That call happens when the runtime next + sees an **edit** in the scope (for `gh` scopes, the next command in the + family). This requires phase 1's scope parser to tag each observation as + read, edit or run. The pane lines it parses (`⏺ Read(…)`, `● Edit …`, + `$ gh …`) already distinguish them. A scope is therefore evaluated at most + twice per kick. + +### Where it runs: hive process, off the poll goroutine + +The pass runs **in the hive process**, as a decorator over phase 1's hive-side +`KnowledgeAdviser`. The hive process holds the knowledge store, the Primer and +the `governor.litellm` credentials. A Crux-side hook would need all three +shipped to the runtime, and would also put an inference key in the sidecar. + +The phase-1 `Advise` contract has to change first. Phase 1 calls `Advise` +synchronously on the agent's 3 s poll goroutine. That is acceptable for a +bounded local search, but a model call takes seconds and would stall +everything else that tick serves, such as the CI-poll guard. Proposed change, +which also benefits phase 1's 5 s Primer timeout: + +- The runtime calls `Advise` on a separate goroutine, with **at most one call + in flight per agent**. New scopes seen while a call is running are queued, + newest first, and capped at the remaining per-kick allowance. +- The result is held until a later poll tick passes the existing delivery + gates. It is dropped if the kick has changed in the meantime. The check + compares the kick identity captured when the call was made with the + current one. +- `KnowledgeScope` gains an `Action` field (`read` / `edit` / `run`) and a + `PaneTail string`. The runtime fills `PaneTail` only when the policy says + the adviser wants it. Phase 1's policy never asks, so phase 1 never ships + pane text across the seam. + +**Sidecar.** Phase 1 already names a `/v1/knowledge/advise` callback route as +the follow-up for sidecar hives. The advisor pass would use the same route, +because the hive side does the work. No Crux-side model call is proposed. + +### Signal: pane tail plus kick summary only + +The model's input: + +- **Kick summary**, at most 600 chars: the primed issue/PR refs, titles and + labels that `primeKnowledge` already extracts keywords from. The hive-side + adviser keeps this per agent, set when the scheduler primes a kick. +- **Pane tail**: the last `pane_lines` (default 80) lines of the scrollback + the poller already captured, passed through `logscrub.RedactPaneTokens` + before it crosses the seam. +- **Candidates**: slug, title, and the same at most 300-char summary phase 1 + would type. No full entry bodies. + +Excluded from the first cut: + +- **Proxy GitHub calls.** The proxy sees API paths. For "which `gh` family is + the agent in", that adds nothing beyond phase 1's `gh` scope, and wiring it + in would couple the advisor to `crux/proxy`. +- **JSONL transcript (`kick_log_source: transcript`).** Readers exist only for + `claude` and `copilot`. Transcripts carry full tool outputs (more tokens and + more secret surface), and they would make the advisor's behaviour depend on + the backend. If shadow-mode data shows the pane tail is too thin, this is + the first signal to add, behind the same scrubber. + +### Budget + +The pass uses the hive's model, not the agent's, so it is hive spend: + +- **Per agent:** `max_calls_per_agent_hour`, default 6. This is a rolling + one-hour window counted the same way `agent_github_budget.go` counts GitHub + calls. +- **Fleet:** `max_calls_per_day`, default 300. This is a per-UTC-day counter, + following ioscan's `NewDailyQuotaClassifier`. +- **Attribution:** each request sets the OpenAI `user` field to + `hive-knowledge-advisor:<agent>`, so LiteLLM spend logs show per-agent cost + without hive running its own spend ledger. The decision record carries + prompt and completion token counts from the response's `usage`. +- **Over budget, timeout (`timeout_s`, default 15) or endpoint error:** the + scope is treated as `null` and a decision record with the outcome is + written. The pass falls back to silence, not to phase 1's top-1. The pass + exists to cut noise, and silently reverting to the noisier behaviour under + load would hide that it had stopped working. Operators who want the matcher + back can set `mode: off`. + +Charging the agent's own spend was rejected. Many agents run on subscription +CLIs with no per-call meter. Where an agent does have a LiteLLM virtual key, +spending it on advice would let the advisor exhaust the agent's own budget. + +### Configuration + +```yaml +knowledge: + advisor: true # phase 1 switch (#17052); required + advisor_llm: + mode: off # off | shadow | rank + model: "" # required for shadow/rank; empty = off + endpoint: "" # default governor.litellm endpoint + api_key_env: "" # / api_key_file; default governor.litellm key + candidates: 5 + pane_lines: 80 + timeout_s: 15 + max_calls_per_agent_hour: 6 + max_calls_per_day: 300 + holdout_percent: 0 # rank mode: % of kicks that decide but never deliver +``` + +`advisor_exclude_agents` and `advisor_max_per_kick` from phase 1 apply +unchanged. The endpoint, key and model resolve the same way as +`GovernorConfig.ResolveReviewer`. + +### Measurement + +Each model decision writes one `knowledge advisor: decision` log line and, +when something is delivered, one prompt-history entry with trigger +`knowledge-advisor`, exactly as phase 1 does. The log line carries: + +- agent, kick identity and scope (kind, key, action); +- the candidate slugs; +- the pick (or `null`), the reason, and the outcome (`delivered`, + `held-out`, `gated`, `invalid`, `timeout`, `over-budget`, `error`); +- latency and token counts. + +Rollout: + +1. **Shadow.** `mode: shadow` delivers phase 1's top-1 and logs what the model + would have picked. A week on hive's own hive answers the cheap questions + with no behaviour change: how often the model says `null`, how often it + picks something other than the matcher's top-1, the cost per kick, and the + latency. +2. **Rank with holdout.** `mode: rank`, `holdout_percent: 50`. The kick + identity is hashed into the delivery arm or the holdout arm. Holdout kicks + make the call and log the pick but type nothing. This gives a control group + with the same selection, which "did the agent mention the slug" never + gives. +3. **Outcome comparison.** The retro lane already reconstructs per-bead fix + attempts, kicks and drift pauses (`RetroRecord`). A small addition gives + each record the advisor arm of its kicks. Comparing the two arms on those + counters answers "did delivered advice help" with existing data. It needs + no new model call and no agent cooperation. + +An explicit "did this help" line from the agent is rejected. It spends an +agent turn on every delivery, agents tend to answer yes, compliance varies by +backend, and it adds lines to transcripts that the retro and log consumers +would then have to filter out. Searching the PR for the slug is also rejected +as the primary signal. Agents act on a rule without citing it, so the search +undercounts, and it measures citation, not effect. + +## Non-goals + +- Changing the entry format or the kick-time primer (#17045, #17043). +- Pull-based mid-task lookups by agents (the `/mcp/knowledge` endpoint). +- Generated hints (see "Ranker vs. generator"). +- Any delivery path other than phase 1's. + +## Implementation slices + +Each slice is independent once phase 1 (PR #17068) lands: + +1. **Runtime.** Make `Advise` asynchronous: one call in flight per agent, a + kick-identity check at delivery, and the `KnowledgeScope.Action` / + `PaneTail` fields. No behaviour change with phase 1's adviser. +2. **Hive.** Add the `knowledge.advisor_llm` config and the ranking decorator + with validation, budgets, the decision log line, and modes + `off`/`shadow`/`rank` plus holdout. +3. **Retro.** Record each bead's advisor arm in `RetroRecord` for the outcome + comparison. +4. **Sidecar.** The `/v1/knowledge/advise` callback, shared with phase 1's + sidecar follow-up. + +## Open for discussion + +- Is a per-agent-hour default of 6 calls with a fleet default of 300 per day + the right order of magnitude for hive's own fleet, or should shadow data + set the defaults? +- Should the second evaluation of a scope also be allowed on a long gap, for + example 10 minutes later, rather than only on the first edit? +- Once rank mode has data, should the reason be shown to agents as a + separately marked line? It is model text, so this reopens the injection + question above. diff --git a/src/cmd/hive/agent_runtime_sidecar.go b/src/cmd/hive/agent_runtime_sidecar.go index 3dc6a3efac..0ac63b0423 100644 --- a/src/cmd/hive/agent_runtime_sidecar.go +++ b/src/cmd/hive/agent_runtime_sidecar.go @@ -343,6 +343,14 @@ func (h *sidecarHost) SetSandboxMutationBoundary(boundary effects.Boundary) { // the runtime's own process); trajectory events do not depend on it. func (h *sidecarHost) SetSpanStarter(crux.SpanStarter) { h.inProcessOnly("SetSpanStarter") } +// SetKnowledgeAdviser is in-process-only in phase 1 of hivecommons/hive#17052: +// the adviser searches the knowledge store that lives in the hive process. +// A sidecar runtime runs without the mid-task advisor until a callback route +// carries the scope → advice exchange. +func (h *sidecarHost) SetKnowledgeAdviser(crux.KnowledgeAdviser) { + h.inProcessOnly("SetKnowledgeAdviser") +} + // SetInferenceRoute and ClearInferenceRoute are cruxhost.InferenceRouter: // the callback's end of SetInferenceCallbacks. A route that arrives before // boot has installed the closures is dropped and logged; the runtime's diff --git a/src/cmd/hive/knowledge_adviser.go b/src/cmd/hive/knowledge_adviser.go new file mode 100644 index 0000000000..c7c2f97d8b --- /dev/null +++ b/src/cmd/hive/knowledge_adviser.go @@ -0,0 +1,137 @@ +package main + +import ( + "context" + "log/slog" + "strings" + "time" + + "github.com/hivecommons/hive/crux" + "github.com/hivecommons/hive/pkg/config" + "github.com/hivecommons/hive/pkg/knowledge" +) + +// Mid-task knowledge adviser (hivecommons/hive#17052): the hive side of the +// runtime's knowledge advisor. The runtime says which scope an agent just +// entered; this asks the same Primer the kick used, under the same +// knowledge.agent_scopes restriction, and hands back entries the kick did +// not already carry. + +const ( + // knowledgeAdviseTimeout bounds one adviser query. It runs on the agent's + // poll goroutine, so a slow wiki layer must not stall the poller. + knowledgeAdviseTimeout = 5 * time.Second + // knowledgeAdviseMaxPerScope caps how many entries one scope may queue; + // the runtime's per-kick cap is the real bound, this keeps the queue short. + knowledgeAdviseMaxPerScope = 2 + // knowledgeAdviseSummaryRunes caps the body text handed to the runtime. + knowledgeAdviseSummaryRunes = 300 +) + +type knowledgeAdviser struct { + cfg func() *config.Config + primer func() *knowledge.Primer + primed func(agent string) []string + logger *slog.Logger +} + +func newKnowledgeAdviser(b *boot) *knowledgeAdviser { + return &knowledgeAdviser{ + cfg: func() *config.Config { return b.cfg }, + primer: func() *knowledge.Primer { + if b.sched == nil { + return nil + } + return b.sched.GetPrimer() + }, + primed: func(agent string) []string { + if b.sched == nil { + return nil + } + return b.sched.KickPrimedSlugs(agent) + }, + logger: b.logger, + } +} + +// Policy reads the live config every call so a dashboard change applies to +// the next poll tick without a restart, like the other host resolvers. +func (a *knowledgeAdviser) Policy(agent string) crux.KnowledgeAdvisorPolicy { + cfg := a.cfg() + if cfg == nil || !cfg.KnowledgeAdvisorEnabledFor(agent) { + return crux.KnowledgeAdvisorPolicy{} + } + return crux.KnowledgeAdvisorPolicy{Enabled: true, MaxPerKick: cfg.Knowledge.AdvisorMaxPerKick} +} + +// Advise searches the knowledge store for scope. Until #17045 lands the +// Primer has no kick context for paths, so the observed file goes in as the +// primer's file path and the scope's segments as keywords. +func (a *knowledgeAdviser) Advise(agent string, scope crux.KnowledgeScope) []crux.KnowledgeAdvice { + primer := a.primer() + cfg := a.cfg() + if primer == nil || cfg == nil { + return nil + } + var paths []string + if scope.Path != "" { + paths = []string{scope.Path} + } + var agentScope *knowledge.TOCScope + if sc, ok := cfg.KnowledgeAgentScope(agent); ok { + s := knowledge.AgentScope(sc.Layers, sc.Repos, sc.Types, sc.Tags, sc.IncludeStates) + agentScope = &s + } + ctx, cancel := context.WithTimeout(context.Background(), knowledgeAdviseTimeout) + defer cancel() + primed := primer.PrimeScoped(ctx, agentScope, paths, scope.Keywords) + advice := selectKnowledgeAdvice(primed.Facts, a.primed(agent), knowledgeAdviseMaxPerScope) + a.logger.Debug("knowledge advisor: scope entered", + "agent", agent, "scope", scope.Key, "candidates", len(primed.Facts), "advice", len(advice)) + return advice +} + +// selectKnowledgeAdvice keeps the best-ranked facts not in exclude, up to +// limit, rendered for the runtime's one-line delivery. +func selectKnowledgeAdvice(facts []knowledge.Fact, exclude []string, limit int) []crux.KnowledgeAdvice { + skip := make(map[string]bool, len(exclude)) + for _, slug := range exclude { + skip[slug] = true + } + var out []crux.KnowledgeAdvice + for _, f := range facts { + if f.Slug == "" || skip[f.Slug] || strings.TrimSpace(f.Title) == "" { + continue + } + skip[f.Slug] = true + out = append(out, crux.KnowledgeAdvice{ + Slug: f.Slug, + Title: f.Title, + Summary: truncateRunes(strings.Join(strings.Fields(f.Body), " "), knowledgeAdviseSummaryRunes), + Ref: knowledgeAdviceRef(f), + }) + if len(out) >= limit { + break + } + } + return out +} + +// knowledgeAdviceRef is where the agent can read the whole entry: the first +// source document URL, else the knowledge entry id the dashboard serves. +func knowledgeAdviceRef(f knowledge.Fact) string { + for _, s := range f.Sources { + if s.DocURL != "" { + return s.DocURL + } + } + return "knowledge entry " + f.Slug +} + +func truncateRunes(s string, n int) string { + r := []rune(s) + if len(r) <= n { + return s + } + return strings.TrimSpace(string(r[:n-1])) + "…" +} diff --git a/src/cmd/hive/knowledge_adviser_test.go b/src/cmd/hive/knowledge_adviser_test.go new file mode 100644 index 0000000000..09c5db0bc9 --- /dev/null +++ b/src/cmd/hive/knowledge_adviser_test.go @@ -0,0 +1,83 @@ +package main + +import ( + "log/slog" + "reflect" + "strings" + "testing" + + "github.com/hivecommons/hive/crux" + "github.com/hivecommons/hive/pkg/config" + "github.com/hivecommons/hive/pkg/knowledge" +) + +func TestSelectKnowledgeAdvice(t *testing.T) { + facts := []knowledge.Fact{ + {Slug: "primed", Title: "Already in the kick", Body: "x"}, + {Slug: "", Title: "No slug", Body: "x"}, + {Slug: "untitled", Title: " ", Body: "x"}, + {Slug: "tree", Title: "Re-pin the tree", Body: "line one\n\n line two " + strings.Repeat("w", 400), + Sources: []knowledge.Source{{PR: "1"}, {DocURL: "https://wiki/tree"}}}, + {Slug: "tree", Title: "Duplicate slug", Body: "x"}, + {Slug: "third", Title: "Third", Body: "short"}, + {Slug: "fourth", Title: "Fourth", Body: "never reached"}, + } + got := selectKnowledgeAdvice(facts, []string{"primed"}, 2) + if len(got) != 2 { + t.Fatalf("got %d advice: %+v", len(got), got) + } + if got[0].Slug != "tree" || got[0].Title != "Re-pin the tree" || got[0].Ref != "https://wiki/tree" { + t.Errorf("first = %+v", got[0]) + } + if !strings.HasPrefix(got[0].Summary, "line one line two w") || !strings.HasSuffix(got[0].Summary, "…") { + t.Errorf("summary = %q", got[0].Summary) + } + if n := len([]rune(got[0].Summary)); n > knowledgeAdviseSummaryRunes { + t.Errorf("summary is %d runes, cap %d", n, knowledgeAdviseSummaryRunes) + } + if got[1].Slug != "third" || got[1].Ref != "knowledge entry third" || got[1].Summary != "short" { + t.Errorf("second = %+v", got[1]) + } + if selectKnowledgeAdvice(nil, nil, 2) != nil { + t.Error("no facts should yield nil") + } +} + +func TestTruncateRunes(t *testing.T) { + if got := truncateRunes("héllo", 5); got != "héllo" { + t.Errorf("under cap = %q", got) + } + if got := truncateRunes("héllo wörld", 6); got != "héllo…" { + t.Errorf("over cap = %q", got) + } +} + +func TestKnowledgeAdviserPolicy(t *testing.T) { + cfg := &config.Config{Knowledge: config.KnowledgeConfig{Enabled: true, Advisor: true, AdvisorMaxPerKick: 4}} + a := &knowledgeAdviser{cfg: func() *config.Config { return cfg }, logger: slog.Default()} + want := crux.KnowledgeAdvisorPolicy{Enabled: true, MaxPerKick: 4} + if got := a.Policy("developer"); !reflect.DeepEqual(got, want) { + t.Errorf("policy = %+v, want %+v", got, want) + } + cfg.Knowledge.Advisor = false + if got := a.Policy("developer"); got.Enabled { + t.Errorf("disabled policy = %+v", got) + } + a.cfg = func() *config.Config { return nil } + if got := a.Policy("developer"); got.Enabled { + t.Errorf("nil config policy = %+v", got) + } +} + +func TestKnowledgeAdviserAdvise_NoPrimerIsSilent(t *testing.T) { + cfg := &config.Config{Knowledge: config.KnowledgeConfig{Enabled: true, Advisor: true}} + a := &knowledgeAdviser{ + cfg: func() *config.Config { return cfg }, + primer: func() *knowledge.Primer { return nil }, + primed: func(string) []string { return nil }, + logger: slog.Default(), + } + if got := a.Advise("developer", crux.KnowledgeScope{Key: "src/a", Path: "src/a/x.go"}); got != nil { + t.Errorf("advice without a primer = %+v", got) + } +} diff --git a/src/cmd/hive/main.go b/src/cmd/hive/main.go index 8949c14ecb..358a9cd042 100644 --- a/src/cmd/hive/main.go +++ b/src/cmd/hive/main.go @@ -1520,6 +1520,15 @@ func (b *boot) bootGovernor() { b.logger, )) + // Hosted spokes keep no checkout of their primary repo, so the two local + // roots agentsRepoRoot knows are empty there and AGENTS.md was never + // injected (hivecommons/hive#17090). Let the scheduler fetch it through the + // same App client when no local root exists. Guarded so a typed-nil + // *github.Client is never stored as a non-nil interface. + if b.ghClient != nil { + b.sched.SetAgentsMdFetcher(b.ghClient) + } + // Wire the whole-agent definition_source resolver so agents imported with // "keep linked" re-fetch their portable AgentDefinition from the repo on // reload/kick and re-apply its operator-safe fields (never security/seed-only @@ -4156,6 +4165,11 @@ func (b *boot) bootWatchersWith(deps bootWatchersDeps) { // per-agent "Prompts" tab. Redaction and truncation happen inside the // store, before anything is written to the PVC. b.agentMgr.SetRecordPromptCallback(b.dashSrv.RecordPrompt) + // Mid-task knowledge advisor (#17052): the runtime asks this when an + // agent's pane first shows a scope its kick did not cover. Policy is read + // off the live config per call, so knowledge.advisor flips without a + // restart; the adviser itself is a no-op until SetPrimer has run. + b.agentMgr.SetKnowledgeAdviser(newKnowledgeAdviser(b)) // Feed agent lifecycle events (start, stop, launch FAILURE, backend/model // change) into the durable audit store behind the dashboard's Audit Log. diff --git a/src/cmd/hive/merge_eligibility.go b/src/cmd/hive/merge_eligibility.go index b183b58a12..33e32bccf0 100644 --- a/src/cmd/hive/merge_eligibility.go +++ b/src/cmd/hive/merge_eligibility.go @@ -130,7 +130,7 @@ func stageLabelPolicyFunc(cfg *config.Config) func() automerge.StageLabelPolicy Dwell: stage.DwellOverrides(), StalledRequireQuiet: stage.Stalled.IsRequireQuiet(), ContributorNudge: stage.ContributorNudge.IsEnabled(), - RenudgeInterval: stage.ContributorNudge.EffectiveRenudgeInterval(), + RenudgeInterval: nudgeRepeatAfter(cfg), Adoption: stage.Adoption.IsEnabled(), GraceOnline: stage.EffectiveContributorGraceOnline(), GraceOffline: stage.EffectiveContributorGraceOffline(), @@ -1624,3 +1624,14 @@ func normalizedAutoMergeLabel(label string) string { } return github.AutoMergeQueuedLabel } + +// nudgeRepeatAfter is the delay before the one contributor re-nudge: +// governor.labels.stage.contributor_nudge.renudge_interval when set, +// otherwise auto_merge.nudge_repeat_after (default 72h, +// hivecommons/hive#17067). +func nudgeRepeatAfter(cfg *config.Config) time.Duration { + if d := cfg.Governor.Labels.Stage.ContributorNudge.EffectiveRenudgeInterval(); d > 0 { + return d + } + return cfg.AutoMerge.EffectiveNudgeRepeatAfter() +} diff --git a/src/crux/agent/claude_remote_control.go b/src/crux/agent/claude_remote_control.go index d383a8e836..9057361e49 100644 --- a/src/crux/agent/claude_remote_control.go +++ b/src/crux/agent/claude_remote_control.go @@ -38,11 +38,11 @@ func claudeBypassConsentSeed() map[string]any { } // sharedClaudeSettingsFile is the userSettings file every interactive -// claude-backend agent reads: the per-agent homes symlink ~/.claude to -// sharedAgentHome/.claude (interactiveHomeBridgeDirs), so one file governs -// the whole fleet. +// claude-backend agent reads: each per-agent ~/.claude is a REAL directory +// (perAgentCLIHomes) whose settings.json symlinks to +// sharedAgentHome/.claude/settings.json, so one file governs the whole fleet. func sharedClaudeSettingsFile() string { - return filepath.Join(sharedAgentHome, ".claude", "settings.json") + return filepath.Join(sharedAgentHome, claudeHomeDirName, claudeSettingsFileName) } // ensureClaudeRemoteControlDefault re-asserts, before a claude-backend launch, diff --git a/src/crux/agent/cli_memory.go b/src/crux/agent/cli_memory.go new file mode 100644 index 0000000000..f4a772a4da --- /dev/null +++ b/src/crux/agent/cli_memory.go @@ -0,0 +1,244 @@ +package agent + +import ( + "encoding/json" + "errors" + "io/fs" + "os" + "os/exec" + "path/filepath" + "strings" +) + +// Persistent CLI memory policy (hivecommons/hive#17032). See +// config.CLIMemoryConfig for the operator-facing knobs. Each CLI's switch is +// the one its vendor documents: +// +// - Claude Code: auto-memory lives in ~/.claude/projects/<cwd>/memory/ and +// is disabled with the CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 environment +// variable (equivalently "autoMemoryEnabled": false in settings.json). +// https://code.claude.com/docs/en/memory — the env var is used because it +// is per process, so a per-agent override needs no second settings file. +// - Codex: memories are a feature flag, [features] memories = true|false in +// $CODEX_HOME/config.toml, stored under $CODEX_HOME/memories/ (and the +// memories_v2/ layout). https://developers.openai.com/codex/memories and +// https://developers.openai.com/codex/config-reference +// - Copilot CLI: the "memory" key in ~/.copilot/settings.json ("whether to +// enable agentic memory", `copilot help config`; /memory on|off writes +// it). The memory itself is server-side (Copilot Memory), so there is no +// local store to wipe. +// - Gemini CLI: no automatic memory; save_memory / `/memory add` write +// ~/.gemini/GEMINI.md, which the wipe removes. +const ( + claudeDisableAutoMemoryEnv = "CLAUDE_CODE_DISABLE_AUTO_MEMORY" + codexMemoriesFeatureKey = "memories" + codexFeaturesTableHeader = "[features]" + copilotSettingsFileName = "settings.json" + copilotMemorySettingKey = "memory" +) + +// claudeCLIBackend reports whether backend launches the Claude Code CLI +// (subscription or inference-routed), i.e. whether Claude's auto-memory +// switch applies. +func claudeCLIBackend(backend string) bool { + return backend == "claude" || IsInferenceBackend(backend) +} + +// cliMemoryEnvPairs returns the launch environment that pins the CLI's +// auto-memory off for this agent when the policy says so. +func cliMemoryEnvPairs(agent *AgentProcess, backend string) []agentEnvPair { + if agent.Config.CLIMemory.AutoMemoryEnabled() || !claudeCLIBackend(backend) { + return nil + } + return []agentEnvPair{{claudeDisableAutoMemoryEnv, "1", false}} +} + +// codexConfigSeed applies every hive-owned pin to a $CODEX_HOME/config.toml: +// the startup update check off, and the memories feature pinned to the +// agents.cli_memory.auto_memory policy (hivecommons/hive#17032). +func codexConfigSeed(existing []byte, autoMemory bool) []byte { + return codexConfigWithMemoriesPinned(codexConfigWithUpdateCheckDisabled(existing), autoMemory) +} + +// codexConfigWithMemoriesPinned returns existing with `memories = <enabled>` +// set inside the [features] table, adding the table at the end when absent +// and replacing an existing memories line in place. Content outside that one +// key is preserved byte for byte, like codexConfigWithUpdateCheckDisabled. +func codexConfigWithMemoriesPinned(existing []byte, enabled bool) []byte { + line := codexMemoriesFeatureKey + " = " + boolTOML(enabled) + lines := strings.SplitAfter(string(existing), "\n") + if len(lines) > 0 && lines[len(lines)-1] == "" { + lines = lines[:len(lines)-1] + } + tableStart := -1 + for i, l := range lines { + if strings.TrimSpace(l) == codexFeaturesTableHeader { + tableStart = i + break + } + } + if tableStart < 0 { + text := strings.Join(lines, "") + if text != "" && !strings.HasSuffix(text, "\n") { + text += "\n" + } + if text != "" { + text += "\n" + } + return []byte(text + codexFeaturesTableHeader + "\n" + line + "\n") + } + end := len(lines) + for i := tableStart + 1; i < len(lines); i++ { + if strings.HasPrefix(strings.TrimSpace(lines[i]), "[") { + end = i + break + } + } + for i := tableStart + 1; i < end; i++ { + trimmed := strings.TrimSpace(lines[i]) + if strings.HasPrefix(trimmed, "#") { + continue + } + if key, _, ok := strings.Cut(trimmed, "="); ok && strings.TrimSpace(key) == codexMemoriesFeatureKey { + lines[i] = line + lineEnding(lines[i]) + return []byte(strings.Join(lines, "")) + } + } + // Insert as the last entry of the table, before any trailing blank lines + // that separate it from the next table. + insert := end + for insert > tableStart+1 && strings.TrimSpace(lines[insert-1]) == "" { + insert-- + } + if !strings.HasSuffix(lines[insert-1], "\n") { + lines[insert-1] += "\n" + } + merged := make([]string, 0, len(lines)+1) + merged = append(merged, lines[:insert]...) + merged = append(merged, line+"\n") + merged = append(merged, lines[insert:]...) + return []byte(strings.Join(merged, "")) +} + +func boolTOML(b bool) string { + if b { + return "true" + } + return "false" +} + +// seedCopilotMemorySetting pins the Copilot CLI "memory" setting in the +// agent's per-agent ~/.copilot/settings.json to the policy value. Unlike +// seedJSONFile this OVERWRITES the key: the policy owns it, so flipping +// agents.cli_memory.auto_memory takes effect on the next launch instead of +// being shadowed by the value an earlier launch wrote. Other keys are kept. +func (m *Manager) seedCopilotMemorySetting(agent *AgentProcess, home string) { + dir := filepath.Join(home, copilotHomeDirName) + if info, err := os.Lstat(dir); err != nil || !info.IsDir() || info.Mode()&os.ModeSymlink != 0 { + return + } + path := filepath.Join(dir, copilotSettingsFileName) + want := agent.Config.CLIMemory.AutoMemoryEnabled() + existing := map[string]any{} + if data, err := readInferenceConfigFile(path); err == nil { + if jsonErr := json.Unmarshal(data, &existing); jsonErr != nil { + m.logger.Warn("copilot settings unparseable, rewriting", + "agent", agent.Name, "path", path, "error", jsonErr) + existing = map[string]any{} + } + } + if cur, ok := existing[copilotMemorySettingKey].(bool); ok && cur == want { + return + } + existing[copilotMemorySettingKey] = want + data, err := json.Marshal(existing) + if err != nil { + m.logger.Warn("failed to marshal copilot settings", "agent", agent.Name, "path", path, "error", err) + return + } + if err := writeInferenceConfigFile(path, data); err != nil { + m.logger.Warn("failed to write copilot settings", "agent", agent.Name, "path", path, "error", err) + return + } + if agent.UID > 0 { + // Best-effort: unprivileged deployments cannot chown, and the file + // mode already keeps it usable there. + _ = os.Chown(path, agent.UID, -1) + } +} + +// cliMemoryStorePaths lists the persistent memory stores of every CLI this +// agent might have run, under its own HOME and CODEX_HOME only. Shared-home +// paths are never returned: under HIVE_SHARED_AGENT_HOME=1 (or a UID-0 +// agent) the stores are fleet-shared and wiping them for one agent's kick +// would erase every other agent's memory too. +func cliMemoryStorePaths(agent *AgentProcess, backend string) []string { + if agent.UID <= 0 || sharedAgentHomeForced() { + return nil + } + home := AgentHome(agent.Name, agent.UID, backend) + var paths []string + for _, spec := range perAgentCLIHomes { + for _, rel := range spec.memoryRel { + matches, err := filepath.Glob(filepath.Join(home, spec.dir, filepath.FromSlash(rel))) + if err != nil { + continue + } + paths = append(paths, matches...) + } + } + for _, rel := range codexMemoryDirs { + p := filepath.Join(codexHomePath(agent.Name), rel) + if _, err := os.Lstat(p); err == nil { + paths = append(paths, p) + } + } + return paths +} + +// codexMemoryDirs are the Codex memory layouts under $CODEX_HOME +// (https://developers.openai.com/codex/memories). +var codexMemoryDirs = []string{"memories", "memories_v2"} + +// clearCLIMemoryForKick removes the agent's persistent CLI memory stores +// before a kick when agents.cli_memory.clear_on_kick is set, so the new turn +// starts from the kick template and the shared knowledge system alone. It is +// best-effort: a store that cannot be removed is logged and the kick still +// proceeds, since a stale memory is a quality defect, not a safety one. +func (m *Manager) clearCLIMemoryForKick(agent *AgentProcess, backend string) { + if !agent.Config.CLIMemory.ClearMemoryOnKick() { + return + } + paths := cliMemoryStorePaths(agent, backend) + if len(paths) == 0 { + return + } + userSpec := m.agentExecUserSpec(agent) + var removed []string + for _, p := range paths { + if err := m.removeAgentPath(p, userSpec); err != nil { + m.logger.Warn("failed to clear CLI memory before kick", + "agent", agent.Name, "path", p, "error", err) + continue + } + removed = append(removed, p) + } + if len(removed) > 0 { + m.logger.Info("cleared CLI persistent memory before kick", + "agent", agent.Name, "paths", removed) + } +} + +// removeAgentPath removes path (recursively) from the manager's own identity, +// falling back to `su-exec <agent> rm -rf` when the tree is owned by the +// agent UID and the manager is not privileged to delete it. +func (m *Manager) removeAgentPath(path, userSpec string) error { + err := os.RemoveAll(path) + if err == nil || !errors.Is(err, fs.ErrPermission) || userSpec == "" { + return err + } + if out, rerr := exec.Command("su-exec", userSpec, "rm", "-rf", "--", path).CombinedOutput(); rerr != nil { + return outputErr("removing "+path+" as "+userSpec, rerr, out) + } + return nil +} diff --git a/src/crux/agent/cli_memory_test.go b/src/crux/agent/cli_memory_test.go new file mode 100644 index 0000000000..d2967488d0 --- /dev/null +++ b/src/crux/agent/cli_memory_test.go @@ -0,0 +1,215 @@ +package agent + +import ( + "encoding/json" + "os" + "path/filepath" + "testing" + + "github.com/hivecommons/hive/crux/config" +) + +func envValue(pairs []agentEnvPair, key string) (string, bool) { + for _, p := range pairs { + if p.Key == key { + return p.Value, true + } + } + return "", false +} + +// Default policy: Claude Code's auto-memory is pinned off for every Claude +// CLI launch (subscription and inference-routed), not for other CLIs. +func TestAgentEnvPairs_CLIMemoryPinsClaudeAutoMemoryOffByDefault(t *testing.T) { + m := NewManager(map[string]config.AgentConfig{"scanner": {Backend: "claude"}}, discardLogger(), ProjectContext{}) + for _, backend := range []string{"claude", "vllm"} { + ap := &AgentProcess{Name: "scanner", Config: config.AgentConfig{Backend: backend, Model: "sonnet"}} + if v, ok := envValue(m.agentEnvPairs(ap), claudeDisableAutoMemoryEnv); !ok || v != "1" { + t.Errorf("backend %s: %s=%q ok=%v, want 1", backend, claudeDisableAutoMemoryEnv, v, ok) + } + } + ap := &AgentProcess{Name: "scanner", Config: config.AgentConfig{Backend: "codex"}} + if _, ok := envValue(m.agentEnvPairs(ap), claudeDisableAutoMemoryEnv); ok { + t.Errorf("%s exported to a non-Claude CLI", claudeDisableAutoMemoryEnv) + } +} + +func TestAgentEnvPairs_CLIMemoryOptInLeavesClaudeDefault(t *testing.T) { + m := NewManager(map[string]config.AgentConfig{"scanner": {Backend: "claude"}}, discardLogger(), ProjectContext{}) + ap := &AgentProcess{Name: "scanner", Config: config.AgentConfig{ + Backend: "claude", + CLIMemory: &config.CLIMemoryConfig{AutoMemory: boolPtr(true)}, + }} + if v, ok := envValue(m.agentEnvPairs(ap), claudeDisableAutoMemoryEnv); ok { + t.Errorf("auto_memory: true still exported %s=%q", claudeDisableAutoMemoryEnv, v) + } +} + +func TestCodexConfigWithMemoriesPinned(t *testing.T) { + cases := []struct { + name string + in string + enabled bool + want string + }{ + { + name: "empty adds table", + want: "[features]\nmemories = false\n", + }, + { + name: "top-level keys kept, table appended", + in: "check_for_update_on_startup = false\nmodel = \"gpt-5-codex\"\n", + want: "check_for_update_on_startup = false\nmodel = \"gpt-5-codex\"\n\n[features]\nmemories = false\n", + }, + { + name: "existing table gets the key", + in: "model = \"x\"\n\n[features]\nweb_search = true\n\n[projects.\"/data/agents/ci\"]\ntrust_level = \"trusted\"\n", + want: "model = \"x\"\n\n[features]\nweb_search = true\nmemories = false\n\n[projects.\"/data/agents/ci\"]\ntrust_level = \"trusted\"\n", + }, + { + name: "existing key replaced in place", + in: "[features]\nmemories = true\nweb_search = true\n", + want: "[features]\nmemories = false\nweb_search = true\n", + }, + { + name: "opt-in writes true", + in: "[features]\nmemories = false\n", + enabled: true, + want: "[features]\nmemories = true\n", + }, + { + name: "memories key in another table is not ours", + in: "[projects.\"/x\"]\nmemories = true\n", + want: "[projects.\"/x\"]\nmemories = true\n\n[features]\nmemories = false\n", + }, + } + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + if got := string(codexConfigWithMemoriesPinned([]byte(c.in), c.enabled)); got != c.want { + t.Errorf("merged config = %q, want %q", got, c.want) + } + }) + } + // The combined seed carries both hive pins. + if got := string(codexConfigSeed(nil, false)); got != "check_for_update_on_startup = false\n\n[features]\nmemories = false\n" { + t.Errorf("codexConfigSeed(nil) = %q", got) + } +} + +func TestSeedCopilotMemorySetting_OwnsTheKey(t *testing.T) { + withSharedAgentHome(t) + m := interactiveHomeTestManager(t) + ap := &AgentProcess{Name: "scanner", UID: 1001, Config: config.AgentConfig{Backend: "copilot"}} + + m.setupInteractiveHome(ap, "copilot") + + path := filepath.Join(interactiveHomePath("scanner"), ".copilot", copilotSettingsFileName) + read := func() map[string]any { + t.Helper() + data, err := os.ReadFile(path) + if err != nil { + t.Fatalf("read settings: %v", err) + } + var got map[string]any + if err := json.Unmarshal(data, &got); err != nil { + t.Fatalf("parse settings: %v", err) + } + return got + } + if got := read(); got[copilotMemorySettingKey] != false { + t.Fatalf("default launch: %s = %v, want false", copilotMemorySettingKey, got[copilotMemorySettingKey]) + } + + // An operator key the CLI wrote itself is preserved; the policy flips + // only its own key when the operator opts in. + if err := os.WriteFile(path, []byte(`{"memory":false,"theme":"dark"}`), 0o600); err != nil { + t.Fatal(err) + } + ap.Config.CLIMemory = &config.CLIMemoryConfig{AutoMemory: boolPtr(true)} + m.setupInteractiveHome(ap, "copilot") + got := read() + if got[copilotMemorySettingKey] != true || got["theme"] != "dark" { + t.Fatalf("opt-in: %v", got) + } +} + +func TestClearCLIMemoryForKick_WipesOnlyThisAgentsStores(t *testing.T) { + shared := withSharedAgentHome(t) + prev := codexHomePrefix + codexHomePrefix = filepath.Join(t.TempDir(), ".codex-") + t.Cleanup(func() { codexHomePrefix = prev }) + + m := interactiveHomeTestManager(t) + ap := &AgentProcess{Name: "scanner", UID: 1001, Config: config.AgentConfig{ + Backend: "claude", + CLIMemory: &config.CLIMemoryConfig{ClearOnKick: true}, + }} + home := interactiveHomePath("scanner") + mustWrite := func(p string) { + t.Helper() + if err := os.MkdirAll(filepath.Dir(p), 0o755); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(p, []byte("x"), 0o644); err != nil { + t.Fatal(err) + } + } + claudeMem := filepath.Join(home, ".claude", "projects", "-data-agents-scanner", "memory", "MEMORY.md") + claudeTranscript := filepath.Join(home, ".claude", "projects", "-data-agents-scanner", "abc.jsonl") + geminiMem := filepath.Join(home, ".gemini", geminiMemoryFileName) + geminiSettings := filepath.Join(home, ".gemini", "settings.json") + codexMem := filepath.Join(codexHomePath("scanner"), "memories", "notes.md") + codexMemV2 := filepath.Join(codexHomePath("scanner"), "memories_v2", "index.json") + codexConfig := filepath.Join(codexHomePath("scanner"), "config.toml") + otherAgentMem := filepath.Join(interactiveHomePath("reviewer"), ".claude", "projects", "-data-agents-reviewer", "memory", "MEMORY.md") + sharedMem := filepath.Join(shared, ".claude", "projects", "-data-agents-coder", "memory", "MEMORY.md") + for _, p := range []string{claudeMem, claudeTranscript, geminiMem, geminiSettings, codexMem, codexMemV2, codexConfig, otherAgentMem, sharedMem} { + mustWrite(p) + } + + m.clearCLIMemoryForKick(ap, "claude") + + for _, p := range []string{claudeMem, geminiMem, codexMem, codexMemV2} { + if _, err := os.Lstat(p); !os.IsNotExist(err) { + t.Errorf("%s should have been wiped (err=%v)", p, err) + } + } + for _, p := range []string{claudeTranscript, geminiSettings, codexConfig, otherAgentMem, sharedMem} { + if _, err := os.Lstat(p); err != nil { + t.Errorf("%s must survive the wipe: %v", p, err) + } + } + + // Idempotent on an already-clean home. + m.clearCLIMemoryForKick(ap, "claude") +} + +func TestClearCLIMemoryForKick_OffByDefaultAndNeverSharedHome(t *testing.T) { + withSharedAgentHome(t) + m := interactiveHomeTestManager(t) + home := interactiveHomePath("scanner") + mem := filepath.Join(home, ".claude", "projects", "-data-agents-scanner", "memory", "MEMORY.md") + if err := os.MkdirAll(filepath.Dir(mem), 0o755); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(mem, []byte("x"), 0o644); err != nil { + t.Fatal(err) + } + + // No policy: nothing is touched. + m.clearCLIMemoryForKick(&AgentProcess{Name: "scanner", UID: 1001, Config: config.AgentConfig{Backend: "claude"}}, "claude") + if _, err := os.Stat(mem); err != nil { + t.Fatalf("default policy wiped memory: %v", err) + } + + // Shared-home escape hatch: the store is fleet-shared, so no wipe even + // when the policy asks for one. + t.Setenv("HIVE_SHARED_AGENT_HOME", "1") + on := &config.CLIMemoryConfig{ClearOnKick: true} + if got := cliMemoryStorePaths(&AgentProcess{Name: "scanner", UID: 1001, Config: config.AgentConfig{CLIMemory: on}}, "claude"); got != nil { + t.Errorf("shared home returned stores to wipe: %v", got) + } + if got := cliMemoryStorePaths(&AgentProcess{Name: "scanner", UID: 0, Config: config.AgentConfig{CLIMemory: on}}, "claude"); got != nil { + t.Errorf("uid 0 returned stores to wipe: %v", got) + } +} diff --git a/src/crux/agent/interactive_home.go b/src/crux/agent/interactive_home.go index a471c37648..99ce2c6a48 100644 --- a/src/crux/agent/interactive_home.go +++ b/src/crux/agent/interactive_home.go @@ -43,14 +43,13 @@ func sharedAgentHomeForced() bool { // the dirs the entrypoint pre-creates group-writable and the permissions // watcher reconciles — sharing them is deliberate: // -// - .claude — holds .credentials.json (the shared OAuth token) and -// settings.json. One login authenticates the fleet. -// - .config / .codex / .bob / .gemini — per-tool auth+config the fleet -// shared safely before this change (none are rewritten wholesale by -// rename the way .claude.json is). .config is also $XDG_CONFIG_HOME: gh's -// hosts.yml and goose's config.yaml (provider keys) live there, so it -// stays shared on purpose — it is credential/config state, not session -// state. +// - .config / .codex — per-tool auth+config the fleet shared safely before +// the per-agent layout (neither is rewritten wholesale by rename the way +// .claude.json is, and neither holds per-session or memory state: codex +// runs under a per-agent CODEX_HOME, see setupCodexHome). .config is also +// $XDG_CONFIG_HOME: gh's hosts.yml and goose's config.yaml (provider keys) +// live there, so it stays shared on purpose — it is credential/config +// state, not session state. // - .cache — tool caches; per-agent copies would cold-start every cache on // every new agent for no isolation benefit. // @@ -59,14 +58,20 @@ func sharedAgentHomeForced() bool { // .npm (per-agent npm caches avoid the cross-UID EACCES collisions the shared // cache suffered — see installCavemanForAgent), .local (#6238 — the // $XDG_DATA_HOME / $XDG_STATE_HOME root; see setupAgentXDGDirs for why it is -// a REAL per-agent directory with one narrow bridge inside it), and .copilot -// (hivecommons/hive#9444 — bridging the whole directory shared -// .copilot/session-state, the CLI's per-run chat transcripts, across every -// per-UID agent: any agent's session directory became visible, and mtime- -// newest, through every OTHER agent's symlinked home. See setupCopilotHome -// for why it is a REAL per-agent directory with one narrow bridge inside it). +// a REAL per-agent directory with one narrow bridge inside it), and the CLI +// state directories .copilot (hivecommons/hive#9444), .claude, .gemini and +// .bob (hivecommons/hive#17031): each holds BOTH the fleet-shared login and +// the CLI's per-session transcripts and persistent cross-session memory. +// Bridging the whole directory put every agent's state in ONE tree that any +// agent could read and rewrite: Claude Code's user-level ~/.claude/CLAUDE.md, +// history.jsonl and todos/ were a single shared copy, and each agent's +// auto-memory (~/.claude/projects/-data-agents-<name>/memory/MEMORY.md — +// keyed by cwd, so per-agent by path) sat beside every other agent's, +// writable by all of them (and by anything running as the shared uid). See +// perAgentCLIHomes for the REAL per-agent directories with narrow, +// credential-only bridges inside them. var interactiveHomeBridgeDirs = []string{ - ".claude", ".config", ".codex", ".bob", ".gemini", + ".config", ".codex", ".cache", } @@ -77,6 +82,80 @@ var interactiveHomeBridgeDirs = []string{ // .copilot/session-state (hivecommons/hive#9444). const copilotConfigFileName = "config.json" +// perAgentCLIHome describes one CLI state directory under $HOME that is a +// REAL per-agent directory, with only the named entries bridged back to the +// same path under sharedAgentHome. The bridge list is the allowlist: it names +// exactly the login/settings files one operator sign-in must propagate to the +// fleet, and nothing else — transcripts, todos, history and auto-memory stay +// per agent (hivecommons/hive#17031). This is the contributor-container +// posture (CLAUDE_STAGE_ALLOWLIST in the Justfile, hivecommons/hive#7836) +// applied to the hive's own agents. +type perAgentCLIHome struct { + // dir is the directory name under $HOME (".claude"). + dir string + // bridges are the entries inside dir that symlink to the shared copy. + // Files are linked even when the shared target does not exist yet (the + // link goes live on first login, like interactiveHomeBridgeFiles); + // directories are linked only when the shared target exists, because a + // CLI's `mkdir -p` through a dangling directory symlink fails with EEXIST. + bridges []string + // memoryRel are the per-agent paths, relative to dir, that hold the + // CLI's persistent cross-session memory. Glob patterns are allowed. + // Used by the launch-time shared-memory warning and by the memory wipe. + memoryRel []string +} + +// perAgentCLIHomes are the CLI state directories provisioned by +// setupPerAgentCLIHomes. Order is irrelevant; each is independent. +// +// - .claude — .credentials.json is the shared OAuth token and settings.json +// the fleet-wide user settings hive itself seeds (claude_remote_control.go, +// and the auto-memory pin). projects/ (transcripts AND +// projects/<cwd>/memory/), todos/, history.jsonl, session-env/, +// shell-snapshots/ and statsig/ are per agent. +// - .gemini — antigravity-cli/ holds agy's OAuth token and onboarding cache +// (the entrypoint pre-creates and guards it); settings.json, +// oauth_creds.json, google_accounts.json and installation_id are the +// Gemini CLI login/settings. GEMINI.md (the CLI's saved global memory) and +// tmp/ (checkpoints, session logs) are per agent. +// - .bob — settings.json (bobshell 1.x) and settings/ (bobshell 2.x) carry +// the auth-method/provider pins ensureBobAuthSettings asserts; they must +// stay one file so the pin reaches every bob agent. tmp/ (chat +// recordings), installation_id and trustedFolders.json are per agent. +// - .copilot — config.json only (hivecommons/hive#9444). +var perAgentCLIHomes = []perAgentCLIHome{ + { + dir: claudeHomeDirName, + bridges: []string{claudeCredentialsFileName, claudeSettingsFileName}, + memoryRel: []string{filepath.Join("projects", "*", "memory")}, + }, + { + dir: geminiHomeDirName, + bridges: []string{"antigravity-cli", "settings.json", "oauth_creds.json", "google_accounts.json", "installation_id"}, + memoryRel: []string{geminiMemoryFileName}, + }, + { + dir: bobHomeDirName, + bridges: []string{"settings.json", "settings"}, + }, + { + dir: copilotHomeDirName, + bridges: []string{copilotConfigFileName}, + }, +} + +const ( + claudeHomeDirName = ".claude" + claudeCredentialsFileName = ".credentials.json" + claudeSettingsFileName = "settings.json" + geminiHomeDirName = ".gemini" + // geminiMemoryFileName is the Gemini CLI's global memory file, written by + // its save_memory tool / `/memory add` under ~/.gemini. + geminiMemoryFileName = "GEMINI.md" + bobHomeDirName = ".bob" + copilotHomeDirName = ".copilot" +) + // xdgDataHomeRel / xdgStateHomeRel are the XDG Base Directory defaults // relative to $HOME. They are exported EXPLICITLY (not left to the spec // default) so a CLI that resolves XDG_* before HOME, or a wrapper that @@ -199,7 +278,8 @@ func (m *Manager) setupInteractiveHome(agent *AgentProcess, backend string) { m.bridgeInteractiveHome(agent.Name, home) m.retireSharedGitConfigBridge(agent.Name, home) m.setupAgentXDGDirs(agent.Name, home, agent.UID) - m.setupCopilotHome(agent.Name, home, agent.UID) + m.setupPerAgentCLIHomes(agent.Name, home, agent.UID) + m.seedCopilotMemorySetting(agent, home) m.seedClaudeSessionForAgent(agent, home) m.tightenInteractiveHome(agent.Name, home, agent.UID) m.sweepOrphanedClaudeTmp(agent.Name) @@ -298,46 +378,98 @@ func (m *Manager) setupAgentXDGDirs(agentName, home string, uid int) { } } -// setupCopilotHome makes $HOME/.copilot a REAL per-agent directory, retiring -// the legacy whole-directory symlink bridge to the shared /data/home/.copilot -// when one is found, then re-bridging only config.json back into the shared -// tree (hivecommons/hive#9444). +// setupPerAgentCLIHomes provisions every perAgentCLIHomes entry: makes +// $HOME/<dir> a REAL per-agent directory, retiring the legacy whole-directory +// symlink bridge to the shared /data/home/<dir> when one is found, then +// re-bridges only the named login/settings entries back into the shared tree. +// +// The pattern was introduced for .copilot (hivecommons/hive#9444): before it, +// .copilot rode interactiveHomeBridgeDirs as a bare symlink — correct for a +// directory that holds ONLY credential/config state, but Copilot CLI also +// keeps its per-run chat transcripts under .copilot/session-state, so every +// agent's session-state tree was the SAME physical directory. .claude, .gemini +// and .bob had the identical defect with higher stakes (hivecommons/hive#17031): +// Claude Code's user-level CLAUDE.md, history.jsonl and todos/ were one +// shared copy, and every agent's cwd-keyed auto-memory +// (projects/-data-agents-<name>/memory/MEMORY.md) lived in a tree any other +// agent could read or rewrite, forever (it lives on the PVC). // -// Before this, .copilot rode interactiveHomeBridgeDirs as a bare symlink — -// same as .claude / .config — which is correct for a directory that holds -// ONLY credential/config state, but Copilot CLI also keeps its per-run chat -// transcripts under .copilot/session-state. Bridging the whole directory -// therefore made every agent's session-state tree the SAME physical -// directory: any agent's session, and its mtime, showed up while listing -// ANY other agent's .copilot/session-state — exactly the cross-contamination -// the issue reports (sec-check/quality sessions found under the scanner's -// home). Only config.json (the fleet-shared token map read by -// copilotConfigHasTokens / the auth probe) still needs to be shared; nothing -// else under .copilot does. -func (m *Manager) setupCopilotHome(agentName, home string, uid int) { - dir := filepath.Join(home, ".copilot") +// Every step is best-effort and idempotent: a real directory that already +// exists is kept (it may hold live per-agent state), only a SYMLINK is +// replaced, and nothing under the shared tree is moved or deleted — a +// pre-existing shared memory store is left in place and reported once. +func (m *Manager) setupPerAgentCLIHomes(agentName, home string, uid int) { + for _, spec := range perAgentCLIHomes { + m.setupPerAgentCLIHome(agentName, home, uid, spec) + } +} + +func (m *Manager) setupPerAgentCLIHome(agentName, home string, uid int, spec perAgentCLIHome) { + dir := filepath.Join(home, spec.dir) + shared := filepath.Join(sharedAgentHome, spec.dir) if info, err := os.Lstat(dir); err == nil && info.Mode()&os.ModeSymlink != 0 { - // Legacy whole-directory bridge from before this fix. Removing the - // link touches nothing it pointed at (the shared session-state and - // config.json live on, reachable by every other agent's own link - // until they are re-provisioned too). + // Legacy whole-directory bridge. Removing the link touches nothing it + // pointed at (the shared state lives on, reachable by every other + // agent's own link until they are re-provisioned too). if rerr := os.Remove(dir); rerr != nil { - m.logger.Warn("failed to retire legacy shared .copilot bridge; session-state stays shared for this agent", + m.logger.Warn("failed to retire legacy shared CLI home bridge; session state and memory stay shared for this agent", "agent", agentName, "link", dir, "error", rerr) return } - m.logger.Info("retired legacy shared .copilot bridge in favour of a per-agent session-state dir", - "agent", agentName, "home", home) + m.logger.Info("retired legacy shared CLI home bridge in favour of a per-agent directory", + "agent", agentName, "dir", dir, "shared", shared) + m.warnSharedCLIMemoryOnce(spec, shared) } if err := mkdirAllNoFollow(sharedAgentHome, dir, interactiveHomeDirMode); err != nil { - m.logger.Warn("failed to create per-agent .copilot dir", + m.logger.Warn("failed to create per-agent CLI home dir", "agent", agentName, "dir", dir, "error", err) return } m.ownAgentDir(agentName, dir, uid) - m.bridgeHomeEntry(agentName, - filepath.Join(dir, copilotConfigFileName), - filepath.Join(sharedAgentHome, ".copilot", copilotConfigFileName)) + for _, name := range spec.bridges { + link := filepath.Join(dir, name) + target := filepath.Join(shared, name) + if _, err := os.Stat(target); err != nil && isPerAgentCLIBridgeDir(spec.dir, name) { + // Absent target: a dangling FILE link goes live on first login; a + // dangling DIRECTORY link would make the CLI's own mkdir -p fail, + // so a directory-shaped bridge waits for the entrypoint to create it. + m.logger.Debug("shared CLI dir absent; per-agent bridge deferred", + "agent", agentName, "link", link, "target", target) + continue + } + m.bridgeHomeEntry(agentName, link, target) + } +} + +// perAgentCLIBridgeDirs names the bridge entries that are directories (not +// files) in the shared tree, so an absent target is deferred rather than +// linked dangling. Keyed by "<dir>/<entry>". +var perAgentCLIBridgeDirs = map[string]bool{ + geminiHomeDirName + "/antigravity-cli": true, + bobHomeDirName + "/settings": true, +} + +func isPerAgentCLIBridgeDir(dir, entry string) bool { + return perAgentCLIBridgeDirs[dir+"/"+entry] +} + +// warnSharedCLIMemoryOnce logs, once per process, that the shared CLI home +// still holds a persistent memory store that every agent used to read and +// write. The data is the operator's and is deliberately NOT deleted or moved; +// the log names the path so the operator can review or drain it +// (hivecommons/hive#17033) and then remove it by hand. +func (m *Manager) warnSharedCLIMemoryOnce(spec perAgentCLIHome, shared string) { + for _, rel := range spec.memoryRel { + matches, err := filepath.Glob(filepath.Join(shared, filepath.FromSlash(rel))) + if err != nil || len(matches) == 0 { + continue + } + m.sharedCLIMemoryWarnOnce.Do(func() { + m.logger.Warn("shared CLI home still holds a persistent memory store that was shared by every agent; it is no longer read by per-agent homes and was left in place for review", + "dir", shared, "memory", matches, "see", "hivecommons/hive#17031") + }) + return + } } // retireSharedGitConfigBridge removes the legacy ~/.gitconfig symlink that diff --git a/src/crux/agent/interactive_home_test.go b/src/crux/agent/interactive_home_test.go index 79cfde95d6..dd9ef8e4d7 100644 --- a/src/crux/agent/interactive_home_test.go +++ b/src/crux/agent/interactive_home_test.go @@ -324,6 +324,147 @@ func TestSetupCopilotHome_RetiresLegacyBridgeAndIsolatesSessionState(t *testing. } } +// --- per-agent CLI homes: .claude / .gemini / .bob (hivecommons/hive#17031) -- + +// Regression for hivecommons/hive#17031: ~/.claude, ~/.gemini and ~/.bob were +// whole-directory bridges to the shared home, so Claude Code's auto-memory +// (projects/<cwd>/memory/MEMORY.md), its transcripts and todos — and Gemini's +// GEMINI.md and bob's chat recordings — were ONE physical tree for every +// agent. Each must now be a real per-agent directory with only the login / +// settings entries bridged. +func TestSetupInteractiveHome_CLIHomesArePerAgentWithCredentialBridges(t *testing.T) { + shared := withSharedAgentHome(t) + m := interactiveHomeTestManager(t) + ap := &AgentProcess{Name: "scanner", UID: 1001, Config: config.AgentConfig{Backend: "claude"}} + // Directory-shaped bridges only link when the shared target exists. + for _, d := range []string{ + filepath.Join(shared, ".gemini", "antigravity-cli"), + filepath.Join(shared, ".bob", "settings"), + } { + if err := os.MkdirAll(d, 0o755); err != nil { + t.Fatal(err) + } + } + + m.setupInteractiveHome(ap, "claude") + + home := interactiveHomePath("scanner") + for _, spec := range perAgentCLIHomes { + dir := filepath.Join(home, spec.dir) + if info, err := os.Lstat(dir); err != nil || info.Mode()&os.ModeSymlink != 0 || !info.IsDir() { + t.Errorf("%s should be a real per-agent dir: info=%v err=%v", spec.dir, info, err) + continue + } + for _, name := range spec.bridges { + link := filepath.Join(dir, name) + target, err := os.Readlink(link) + if err != nil { + t.Errorf("%s/%s bridge missing: %v", spec.dir, name, err) + continue + } + if want := filepath.Join(shared, spec.dir, name); target != want { + t.Errorf("%s/%s -> %q, want %q", spec.dir, name, target, want) + } + } + } + // A memory write through the per-agent home lands in the per-agent tree, + // not the shared one. + mem := filepath.Join(home, ".claude", "projects", "-data-agents-scanner", "memory") + if err := os.MkdirAll(mem, 0o755); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(filepath.Join(mem, "MEMORY.md"), []byte("# notes"), 0o644); err != nil { + t.Fatal(err) + } + if _, err := os.Stat(filepath.Join(shared, ".claude", "projects")); !os.IsNotExist(err) { + t.Errorf("per-agent claude projects leaked into shared home (err=%v)", err) + } + // Nothing else inside .claude is bridged — todos/history stay per agent. + for _, name := range []string{"projects", "todos", "history.jsonl"} { + if info, err := os.Lstat(filepath.Join(home, ".claude", name)); err == nil && info.Mode()&os.ModeSymlink != 0 { + t.Errorf(".claude/%s must not be a bridge", name) + } + } +} + +func TestSetupPerAgentCLIHomes_RetiresLegacyBridgeAndKeepsSharedMemory(t *testing.T) { + shared := withSharedAgentHome(t) + m := interactiveHomeTestManager(t) + ap := &AgentProcess{Name: "scanner", UID: 1001, Config: config.AgentConfig{Backend: "claude"}} + home := interactiveHomePath("scanner") + + // Pre-#17031 layout: ~/.claude is a whole-directory bridge and the shared + // tree already holds another agent's MEMORY.md plus the login. + sharedMem := filepath.Join(shared, ".claude", "projects", "-data-agents-coder", "memory") + if err := os.MkdirAll(sharedMem, 0o755); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(filepath.Join(sharedMem, "MEMORY.md"), []byte("# stale"), 0o644); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(filepath.Join(shared, ".claude", ".credentials.json"), []byte(`{}`), 0o600); err != nil { + t.Fatal(err) + } + if err := os.MkdirAll(home, 0o755); err != nil { + t.Fatal(err) + } + for _, d := range []string{".claude", ".gemini", ".bob"} { + if err := os.Symlink(filepath.Join(shared, d), filepath.Join(home, d)); err != nil { + t.Fatal(err) + } + } + + m.setupInteractiveHome(ap, "claude") + + for _, d := range []string{".claude", ".gemini", ".bob"} { + if info, err := os.Lstat(filepath.Join(home, d)); err != nil || info.Mode()&os.ModeSymlink != 0 || !info.IsDir() { + t.Errorf("legacy %s bridge not retired: info=%v err=%v", d, info, err) + } + } + // The other agent's memory is NOT visible through this agent's home... + if _, err := os.Stat(filepath.Join(home, ".claude", "projects", "-data-agents-coder")); !os.IsNotExist(err) { + t.Errorf("shared memory leaked into per-agent .claude (err=%v)", err) + } + // ...but the shared store is left in place (operator data, see #17033). + if _, err := os.Stat(filepath.Join(sharedMem, "MEMORY.md")); err != nil { + t.Errorf("shared MEMORY.md was disturbed: %v", err) + } + // Login still reaches the shared credential. + if target, err := os.Readlink(filepath.Join(home, ".claude", ".credentials.json")); err != nil || target != filepath.Join(shared, ".claude", ".credentials.json") { + t.Errorf(".credentials.json bridge: target=%q err=%v", target, err) + } + // Directory-shaped bridges whose shared target is absent are deferred, not + // left dangling (a dangling dir symlink breaks the CLI's mkdir -p). + if _, err := os.Lstat(filepath.Join(home, ".bob", "settings")); !os.IsNotExist(err) { + t.Errorf(".bob/settings should not be a dangling bridge (err=%v)", err) + } + // Idempotent. + m.setupInteractiveHome(ap, "claude") + if info, err := os.Lstat(filepath.Join(home, ".claude")); err != nil || info.Mode()&os.ModeSymlink != 0 { + t.Errorf(".claude regressed to a bridge on re-provision: info=%v err=%v", info, err) + } +} + +func TestSetupPerAgentCLIHomes_KeepsExistingRealDir(t *testing.T) { + withSharedAgentHome(t) + m := interactiveHomeTestManager(t) + ap := &AgentProcess{Name: "scanner", UID: 1001, Config: config.AgentConfig{Backend: "claude"}} + home := interactiveHomePath("scanner") + live := filepath.Join(home, ".claude", "projects", "-data-agents-scanner", "memory", "MEMORY.md") + if err := os.MkdirAll(filepath.Dir(live), 0o755); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(live, []byte("# mine"), 0o644); err != nil { + t.Fatal(err) + } + + m.setupInteractiveHome(ap, "claude") + + if got, err := os.ReadFile(live); err != nil || string(got) != "# mine" { + t.Errorf("live per-agent memory disturbed: %q err=%v", got, err) + } +} + func TestSetupAgentXDGDirs_KeepsExistingRealLocal(t *testing.T) { withSharedAgentHome(t) m := interactiveHomeTestManager(t) @@ -354,7 +495,7 @@ func TestSetupInteractiveHome_IdempotentAndRepairsStaleLink(t *testing.T) { home := interactiveHomePath("scanner") // Sabotage one bridge with a wrong target, then re-provision. - stale := filepath.Join(home, ".claude") + stale := filepath.Join(home, ".config") if err := os.Remove(stale); err != nil { t.Fatal(err) } @@ -363,7 +504,7 @@ func TestSetupInteractiveHome_IdempotentAndRepairsStaleLink(t *testing.T) { } m.setupInteractiveHome(ap, "claude") target, err := os.Readlink(stale) - if err != nil || target != filepath.Join(shared, ".claude") { + if err != nil || target != filepath.Join(shared, ".config") { t.Errorf("stale bridge not repaired: target=%q err=%v", target, err) } } @@ -374,7 +515,7 @@ func TestSetupInteractiveHome_NeverClobbersRealDir(t *testing.T) { ap := &AgentProcess{Name: "scanner", UID: 1001, Config: config.AgentConfig{Backend: "claude"}} home := interactiveHomePath("scanner") - realDir := filepath.Join(home, ".claude") + realDir := filepath.Join(home, ".config") if err := os.MkdirAll(realDir, 0o755); err != nil { t.Fatal(err) } @@ -387,7 +528,7 @@ func TestSetupInteractiveHome_NeverClobbersRealDir(t *testing.T) { info, err := os.Lstat(realDir) if err != nil || info.Mode()&os.ModeSymlink != 0 || !info.IsDir() { - t.Fatalf("real .claude dir was clobbered: %v %v", info, err) + t.Fatalf("real .config dir was clobbered: %v %v", info, err) } if _, err := os.Stat(marker); err != nil { t.Errorf("marker lost: %v", err) diff --git a/src/crux/agent/knowledge_advisor.go b/src/crux/agent/knowledge_advisor.go new file mode 100644 index 0000000000..6cd0896605 --- /dev/null +++ b/src/crux/agent/knowledge_advisor.go @@ -0,0 +1,339 @@ +package agent + +import ( + "regexp" + "strings" + "sync" + "time" + + "github.com/hivecommons/hive/crux" +) + +// Mid-task knowledge advisor (hivecommons/hive#17052). +// +// The kick primer injects `# Relevant Knowledge` once, at kick time, from the +// issue titles and labels. Whatever the agent later turns out to touch gets +// nothing. The advisor closes that gap with the two things the runtime already +// has: the scrollback the poller captures every tick, and the typed-line +// primitive every other nudge uses. When the pane first shows a scope (a source +// directory, a `gh` command family) that was not there at the first post-kick +// poll, the hive-side adviser is asked for matching entries and each is typed +// into the live session as one `📚 Knowledge:` line, subject to a per-kick cap, +// a cooldown and the same never-type-over-a-human / never-splice-a-kick gates +// the CI-poll nudge honours. Default off (knowledge.advisor: false). + +const ( + // knowledgeAdvisorDefaultMaxPerKick is the per-kick delivery cap when the + // policy leaves it unset. + knowledgeAdvisorDefaultMaxPerKick = 3 + // knowledgeAdvisorDefaultCooldown is the minimum gap between two + // deliveries to one agent when the policy leaves it unset. Each line + // becomes a queued user turn in the CLI; back-to-back lines would read + // as an operator talking over the agent. + knowledgeAdvisorDefaultCooldown = 2 * time.Minute + // knowledgeAdvisorMaxScopeDepth is how many directory segments identify a + // path scope: src/crux/agent/manager.go opens "src/crux/agent". + knowledgeAdvisorMaxScopeDepth = 3 + // knowledgeAdvisorMaxSummary caps the body text in a delivered line. + knowledgeAdvisorMaxSummary = 300 + // knowledgeAdvisorTrigger is the prompt-history trigger each delivery is + // recorded under, so the dashboard shows it beside kicks. + knowledgeAdvisorTrigger = "knowledge-advisor" + knowledgeAdvisorKindPath = "path" + knowledgeAdvisorKindGH = "gh" +) + +// knowledgePathRe matches a relative file path with at least one directory and +// a file extension, as the CLIs print paths they read, edit or run against: +// "⏺ Read(src/crux/agent/manager.go)", "● Edit src/pkg/config/config.go", +// "$ cat src/docs/x.md". The leading class excludes URLs (":" and "//" never +// precede a match) and absolute paths (the segment before the first "/" must +// be a name). +var knowledgePathRe = regexp.MustCompile(`(?:^|[\s("'` + "`" + `=,\[])((?:\./)?(?:[A-Za-z0-9_.-]+/)+[A-Za-z0-9_-][A-Za-z0-9_.-]*\.[A-Za-z0-9]{1,8})\b`) + +// knowledgeGHRe matches the GitHub CLI families worth a scope of their own. +var knowledgeGHRe = regexp.MustCompile(`\bgh (pr|issue|run|api|release|workflow)\b`) + +// knowledgeIgnoredDirs are path roots that are tooling, not the agent's work. +var knowledgeIgnoredDirs = map[string]bool{ + "node_modules": true, "vendor": true, ".git": true, "tmp": true, "proc": true, +} + +// knowledgeGenericSegments are directory names that carry no topic. +var knowledgeGenericSegments = map[string]bool{ + "src": true, "pkg": true, "cmd": true, "internal": true, "lib": true, "test": true, + "tests": true, "docs": true, "doc": true, "scripts": true, "static": true, "app": true, +} + +// knowledgeGHKeywords are the search terms a gh family contributes. +var knowledgeGHKeywords = map[string][]string{ + "pr": {"pull request", "pr"}, + "issue": {"issue", "triage"}, + "run": {"workflow run", "ci"}, + "api": {"github api", "rate limit"}, + "release": {"release", "tag"}, + "workflow": {"workflow", "ci"}, +} + +// knowledgeToolInFlightRe matches pane text the CLIs render only while a tool +// call is executing: Claude Code's collapsed "Running 1 shell command…", OMP's +// "⏺ Running… (esc to cancel)". Typing then would land inside the tool's +// output window, which is the one moment the advisor must not pick. +var knowledgeToolInFlightRe = regexp.MustCompile(`(?i)\brunning \d+ shell command|Running…|esc to cancel`) + +// knowledgeAdvisor holds the adviser and the per-agent, per-kick state. +type knowledgeAdvisor struct { + adviser crux.KnowledgeAdviser + now func() time.Time + mu sync.Mutex + agents map[string]*knowledgeKickState +} + +// knowledgeKickState is one agent's advisor state for one kick. It is +// replaced whenever LastKick moves, so a new kick starts clean without the +// kick path having to know the advisor exists. +type knowledgeKickState struct { + kickAt time.Time + baselined bool + seen map[string]bool // scope keys from the baseline or already handled + delivered map[string]bool // slugs typed this kick + count int + lastAt time.Time + pending []crux.KnowledgeAdvice +} + +// SetKnowledgeAdviser installs the hive-side matcher. A nil adviser turns the +// advisor off. It is an atomic store so the poller never takes m.mu for it. +func (m *Manager) SetKnowledgeAdviser(adviser crux.KnowledgeAdviser) { + if adviser == nil { + m.knowledgeAdvisor.Store(nil) + return + } + m.knowledgeAdvisor.Store(&knowledgeAdvisor{ + adviser: adviser, + now: time.Now, + agents: make(map[string]*knowledgeKickState), + }) +} + +// adviseKnowledge is the poll-tick entry point. scrollback is the capture the +// poller already holds; visible is the visible pane, captured once per tick +// and shared with the CI-poll guard. +func (m *Manager) adviseKnowledge(agent *AgentProcess, scrollback, visible string) { + ka := m.knowledgeAdvisor.Load() + if ka == nil || agent == nil || agent.kickDelivering.Load() || agent.LastKick == nil { + return + } + policy := ka.adviser.Policy(agent.Name) + if !policy.Enabled { + return + } + advice, ok := ka.collect(agent.Name, *agent.LastKick, scrollback, visible, policy) + if !ok { + return + } + if m.tmuxSessionHasAttachedClientForAgent(agent) { + return + } + line := renderKnowledgeAdvice(advice) + ka.markDelivered(agent.Name, advice.Slug) + m.logger.Info("knowledge advisor: delivered", + "agent", agent.Name, "slug", advice.Slug, "title", advice.Title) + m.recordPrompt(agent.Name, knowledgeAdvisorTrigger, line) + m.tmuxSendLiteralForAgent(agent, line) + time.Sleep(textToEnterDelay) + m.tmuxSendEntersForAgent(agent) +} + +// collect folds this tick's scrollback into the agent's kick state, asks the +// adviser for every scope that is new since the baseline, and returns the +// next deliverable advice when the cap, cooldown and pane gates all allow it. +func (ka *knowledgeAdvisor) collect(name string, kickAt time.Time, scrollback, visible string, policy crux.KnowledgeAdvisorPolicy) (crux.KnowledgeAdvice, bool) { + scopes := observedKnowledgeScopes(scrollback) + + ka.mu.Lock() + st := ka.agents[name] + if st == nil || !st.kickAt.Equal(kickAt) { + st = &knowledgeKickState{kickAt: kickAt, seen: map[string]bool{}, delivered: map[string]bool{}} + ka.agents[name] = st + } + if !st.baselined { + // Scrollback keeps work from before this kick; what is already on + // screen at the first post-kick poll was not entered during it. + st.baselined = true + for _, sc := range scopes { + st.seen[sc.Key] = true + } + ka.mu.Unlock() + return crux.KnowledgeAdvice{}, false + } + var fresh []crux.KnowledgeScope + for _, sc := range scopes { + if !st.seen[sc.Key] { + st.seen[sc.Key] = true + fresh = append(fresh, sc) + } + } + maxPerKick := policy.MaxPerKick + if maxPerKick <= 0 { + maxPerKick = knowledgeAdvisorDefaultMaxPerKick + } + capped := st.count >= maxPerKick + ka.mu.Unlock() + + if capped { + return crux.KnowledgeAdvice{}, false + } + // The adviser runs outside the lock: it searches the knowledge store. + var found []crux.KnowledgeAdvice + for _, sc := range fresh { + found = append(found, ka.adviser.Advise(name, sc)...) + } + + ka.mu.Lock() + defer ka.mu.Unlock() + for _, adv := range found { + if adv.Slug == "" || st.delivered[adv.Slug] || knowledgeAdvicePending(st.pending, adv.Slug) { + continue + } + st.pending = append(st.pending, adv) + } + if len(st.pending) == 0 { + return crux.KnowledgeAdvice{}, false + } + if knowledgeTurnIdle(visible) { + // The turn the advice was for is over; the next kick primes afresh. + st.pending = nil + return crux.KnowledgeAdvice{}, false + } + if knowledgeToolInFlight(visible) { + return crux.KnowledgeAdvice{}, false + } + cooldown := policy.Cooldown + if cooldown <= 0 { + cooldown = knowledgeAdvisorDefaultCooldown + } + if !st.lastAt.IsZero() && ka.now().Sub(st.lastAt) < cooldown { + return crux.KnowledgeAdvice{}, false + } + next := st.pending[0] + st.pending = st.pending[1:] + return next, true +} + +// markDelivered records a typed slug against the agent's current kick. +func (ka *knowledgeAdvisor) markDelivered(name, slug string) { + ka.mu.Lock() + defer ka.mu.Unlock() + st := ka.agents[name] + if st == nil { + return + } + st.delivered[slug] = true + st.count++ + st.lastAt = ka.now() +} + +func knowledgeAdvicePending(pending []crux.KnowledgeAdvice, slug string) bool { + for _, p := range pending { + if p.Slug == slug { + return true + } + } + return false +} + +// knowledgeTurnIdle reports whether the agent is parked at an empty prompt +// with no work in flight — the turn is over. +func knowledgeTurnIdle(visible string) bool { + return !paneShowsActiveWork(visible) && paneShowsEmptyInputPrompt(visible) +} + +// knowledgeToolInFlight reports whether a tool call is executing right now. +func knowledgeToolInFlight(visible string) bool { + return knowledgeToolInFlightRe.MatchString(visible) +} + +// observedKnowledgeScopes extracts the scopes a pane capture shows the agent +// working in, in first-seen order, one entry per key. +func observedKnowledgeScopes(pane string) []crux.KnowledgeScope { + pane = stripExplainLines(pane) + var out []crux.KnowledgeScope + seen := map[string]bool{} + add := func(sc crux.KnowledgeScope) { + if sc.Key == "" || seen[sc.Key] { + return + } + seen[sc.Key] = true + out = append(out, sc) + } + for _, match := range knowledgePathRe.FindAllStringSubmatch(pane, -1) { + add(knowledgePathScope(match[1])) + } + for _, match := range knowledgeGHRe.FindAllStringSubmatch(pane, -1) { + add(crux.KnowledgeScope{ + Kind: knowledgeAdvisorKindGH, + Key: "gh:" + match[1], + Keywords: knowledgeGHKeywords[match[1]], + }) + } + return out +} + +// knowledgePathScope turns one observed relative path into its scope, or a +// zero scope for root-level files and tooling directories. +func knowledgePathScope(path string) crux.KnowledgeScope { + path = strings.TrimPrefix(path, "./") + segments := strings.Split(path, "/") + dirs := segments[:len(segments)-1] + if len(dirs) == 0 || knowledgeIgnoredDirs[dirs[0]] { + return crux.KnowledgeScope{} + } + for _, d := range dirs { + if d == "" || d == "." || d == ".." { + return crux.KnowledgeScope{} + } + } + if len(dirs) > knowledgeAdvisorMaxScopeDepth { + dirs = dirs[:knowledgeAdvisorMaxScopeDepth] + } + var keywords []string + for _, d := range dirs { + if !knowledgeGenericSegments[strings.ToLower(d)] { + keywords = append(keywords, d) + } + } + return crux.KnowledgeScope{ + Kind: knowledgeAdvisorKindPath, + Key: strings.Join(dirs, "/"), + Path: path, + Keywords: keywords, + } +} + +// renderKnowledgeAdvice is the single line typed into the session. +func renderKnowledgeAdvice(adv crux.KnowledgeAdvice) string { + var b strings.Builder + b.WriteString("📚 Knowledge: ") + b.WriteString(oneLine(adv.Title)) + if summary := headRunes(oneLine(adv.Summary), knowledgeAdvisorMaxSummary); summary != "" { + b.WriteString(" — ") + b.WriteString(summary) + } + if ref := strings.TrimSpace(adv.Ref); ref != "" { + b.WriteString(" (full: ") + b.WriteString(ref) + b.WriteString(")") + } + return b.String() +} + +// headRunes keeps s within n runes, ellipsis included, so the typed line's +// body never exceeds the documented cap. +func headRunes(s string, n int) string { + r := []rune(s) + if len(r) <= n { + return s + } + return strings.TrimSpace(string(r[:n-1])) + "…" +} diff --git a/src/crux/agent/knowledge_advisor_test.go b/src/crux/agent/knowledge_advisor_test.go new file mode 100644 index 0000000000..110968f430 --- /dev/null +++ b/src/crux/agent/knowledge_advisor_test.go @@ -0,0 +1,322 @@ +package agent + +import ( + "reflect" + "strings" + "testing" + "time" + + "github.com/hivecommons/hive/crux" + "github.com/hivecommons/hive/crux/config" +) + +// knowledge_advisor_test.go covers the mid-task knowledge advisor (#17052): +// the pure pieces (scope extraction, the typed line, the pane gates) as tables, +// and the per-kick delivery loop against a fake adviser, a fake clock and the +// funcTerminal seams — no tmux, no time.Sleep beyond the package TestMain's +// shrunk textToEnterDelay. + +// fakeAdviser answers Advise from a fixed table and records every scope asked. +type fakeAdviser struct { + policy crux.KnowledgeAdvisorPolicy + byKey map[string][]crux.KnowledgeAdvice + asked []string +} + +func (f *fakeAdviser) Policy(string) crux.KnowledgeAdvisorPolicy { return f.policy } + +func (f *fakeAdviser) Advise(_ string, scope crux.KnowledgeScope) []crux.KnowledgeAdvice { + f.asked = append(f.asked, scope.Key) + return f.byKey[scope.Key] +} + +// workingPane is a Claude Code pane mid-turn: a tool just finished and the +// model is generating, so the busy footer is up and no tool is in flight. +const workingPane = "⏺ Read(src/crux/agent/manager.go)\n⎿ Read 120 lines\n\n✶ Thinking… (4s · ↓ 94 tokens)\n\n❯ \n esc to interrupt" + +// toolPane is the same pane while a shell command runs. +const toolPane = "⏺ Running 1 shell command…\n\n❯ \n esc to interrupt" + +// idlePane is a finished turn: empty prompt, no busy footer. +const idlePane = "✻ Worked for 26s\n\n❯ " + +func advisorManager(t *testing.T, adviser crux.KnowledgeAdviser) (*Manager, *AgentProcess, *[]string) { + t.Helper() + m := testManager(4) + kickAt := time.Date(2026, 11, 7, 12, 0, 0, 0, time.UTC) + a := &AgentProcess{ + Name: "developer", + Config: config.AgentConfig{Backend: "claude"}, + tmuxSession: "hive-developer-test-nonexistent", + LastKick: &kickAt, + } + m.agents[a.Name] = a + var typed []string + termSeams(m).sessionAttached = func(*AgentProcess) bool { return false } + termSeams(m).sendLiteral = func(_ *AgentProcess, text string) { typed = append(typed, text) } + termSeams(m).sendKeys = func(*AgentProcess, ...string) {} + m.SetKnowledgeAdviser(adviser) + return m, a, &typed +} + +// fakeClock replaces the advisor's clock; tests advance it by hand. +func fakeClock(m *Manager, start time.Time) *time.Time { + now := start + m.knowledgeAdvisor.Load().now = func() time.Time { return now } + return &now +} + +func enabledPolicy() crux.KnowledgeAdvisorPolicy { + return crux.KnowledgeAdvisorPolicy{Enabled: true, MaxPerKick: 2, Cooldown: time.Minute} +} + +func TestObservedKnowledgeScopes(t *testing.T) { + tests := []struct { + name string + pane string + want []string + }{ + { + name: "claude code expanded tool calls", + pane: "⏺ Read(src/crux/agent/manager.go)\n⏺ Update(src/pkg/config/config.go)", + want: []string{"src/crux/agent", "src/pkg/config"}, + }, + { + name: "copilot cli and shell shapes, deeper paths truncate to three segments", + pane: "● Edit src/pkg/dashboard/static/app.js\n$ cat ./src/docs/operator-reference.md", + want: []string{"src/pkg/dashboard", "src/docs"}, + }, + { + name: "one key per scope, first-seen order", + pane: "src/crux/agent/a.go src/crux/agent/b.go .github/workflows/ci.yml", + want: []string{"src/crux/agent", ".github/workflows"}, + }, + { + name: "gh families", + pane: "$ gh pr checks 17052\n$ gh run view 12 --log-failed\n$ gh pr view 1", + want: []string{"gh:pr", "gh:run"}, + }, + { + name: "root files, urls, absolute paths and tooling dirs are not scopes", + pane: "README.md https://github.com/hivecommons/hive/blob/v5/src/x.go /tmp/out.log node_modules/ws/index.js vendor/x/y.go", + want: nil, + }, + { + name: "explain narration is not work", + pane: config.ExplainLinePrefix + " reading src/crux/agent/manager.go next", + want: nil, + }, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + var got []string + for _, sc := range observedKnowledgeScopes(tt.pane) { + got = append(got, sc.Key) + } + if !reflect.DeepEqual(got, tt.want) { + t.Errorf("scopes = %v, want %v", got, tt.want) + } + }) + } +} + +func TestKnowledgePathScopeKeywordsDropGenericSegments(t *testing.T) { + sc := knowledgePathScope("./src/crux/agent/manager_kick.go") + if sc.Kind != knowledgeAdvisorKindPath || sc.Key != "src/crux/agent" || sc.Path != "src/crux/agent/manager_kick.go" { + t.Fatalf("scope = %+v", sc) + } + if want := []string{"crux", "agent"}; !reflect.DeepEqual(sc.Keywords, want) { + t.Errorf("keywords = %v, want %v", sc.Keywords, want) + } + if gh := observedKnowledgeScopes("gh pr list")[0]; !reflect.DeepEqual(gh.Keywords, []string{"pull request", "pr"}) { + t.Errorf("gh keywords = %v", gh.Keywords) + } +} + +func TestRenderKnowledgeAdvice(t *testing.T) { + long := strings.Repeat("word ", 100) + line := renderKnowledgeAdvice(crux.KnowledgeAdvice{ + Slug: "scripts-tree", Title: "Re-pin TRUSTED_SCRIPTS_TREE", Summary: "line one\nline two " + long, Ref: "knowledge entry scripts-tree", + }) + if !strings.HasPrefix(line, "📚 Knowledge: Re-pin TRUSTED_SCRIPTS_TREE — line one line two word") { + t.Errorf("line = %q", line) + } + if !strings.HasSuffix(line, " (full: knowledge entry scripts-tree)") { + t.Errorf("line = %q", line) + } + if strings.Contains(line, "\n") { + t.Error("line must be a single line") + } + body := strings.TrimSuffix(strings.TrimPrefix(line, "📚 Knowledge: Re-pin TRUSTED_SCRIPTS_TREE — "), " (full: knowledge entry scripts-tree)") + if n := len([]rune(body)); n > knowledgeAdvisorMaxSummary { + t.Errorf("summary is %d runes, cap %d", n, knowledgeAdvisorMaxSummary) + } + if got := renderKnowledgeAdvice(crux.KnowledgeAdvice{Title: "T"}); got != "📚 Knowledge: T" { + t.Errorf("bare title = %q", got) + } +} + +func TestKnowledgePaneGates(t *testing.T) { + tests := []struct { + name string + pane string + idle, inTool bool + }{ + {"generating", workingPane, false, false}, + {"shell command running", toolPane, false, true}, + {"omp tool call", "⏺ Running… (esc to cancel)", false, true}, + {"turn over", idlePane, true, false}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + if got := knowledgeTurnIdle(tt.pane); got != tt.idle { + t.Errorf("idle = %v, want %v", got, tt.idle) + } + if got := knowledgeToolInFlight(tt.pane); got != tt.inTool { + t.Errorf("toolInFlight = %v, want %v", got, tt.inTool) + } + }) + } +} + +func TestAdviseKnowledge_BaselineThenNewScopeDelivers(t *testing.T) { + adv := &fakeAdviser{policy: enabledPolicy(), byKey: map[string][]crux.KnowledgeAdvice{ + "src/scripts": {{Slug: "scripts-tree", Title: "Re-pin TRUSTED_SCRIPTS_TREE", Summary: "Any src/scripts edit must re-pin the tree."}}, + }} + m, a, typed := advisorManager(t, adv) + fakeClock(m, time.Date(2026, 11, 7, 12, 1, 0, 0, time.UTC)) + + // First tick after the kick: src/scripts is already in scrollback from + // before the kick, so it is baseline, not a new scope. + m.adviseKnowledge(a, "⏺ Read(src/scripts/old.sh)", workingPane) + if len(adv.asked) != 0 || len(*typed) != 0 { + t.Fatalf("baseline tick asked %v, typed %v", adv.asked, *typed) + } + m.adviseKnowledge(a, "⏺ Read(src/scripts/old.sh)", workingPane) + if len(adv.asked) != 0 { + t.Fatalf("baseline scope re-asked: %v", adv.asked) + } + + // A new kick resets the baseline, so the same scope is new again. + later := a.LastKick.Add(time.Hour) + a.LastKick = &later + m.adviseKnowledge(a, "⏺ Read(src/crux/agent/x.go)", workingPane) + m.adviseKnowledge(a, "⏺ Read(src/crux/agent/x.go)\n⏺ Edit(src/scripts/ci.sh)", workingPane) + if !reflect.DeepEqual(adv.asked, []string{"src/scripts"}) { + t.Fatalf("asked = %v", adv.asked) + } + if len(*typed) != 1 || !strings.HasPrefix((*typed)[0], "📚 Knowledge: Re-pin TRUSTED_SCRIPTS_TREE — Any src/scripts edit") { + t.Fatalf("typed = %v", *typed) + } + // Same slug never twice in a kick, even if another scope matches it. + adv.byKey["gh:pr"] = adv.byKey["src/scripts"] + m.adviseKnowledge(a, "⏺ Edit(src/scripts/ci.sh)\n$ gh pr checks 1", workingPane) + if len(*typed) != 1 { + t.Fatalf("duplicate slug typed: %v", *typed) + } +} + +func TestAdviseKnowledge_CapCooldownAndPaneGates(t *testing.T) { + adv := &fakeAdviser{policy: enabledPolicy(), byKey: map[string][]crux.KnowledgeAdvice{ + "src/a": {{Slug: "a1", Title: "A1"}, {Slug: "a2", Title: "A2"}, {Slug: "a3", Title: "A3"}}, + }} + m, a, typed := advisorManager(t, adv) + now := fakeClock(m, time.Date(2026, 11, 7, 12, 1, 0, 0, time.UTC)) + m.adviseKnowledge(a, "", workingPane) // baseline + + // Tool in flight: the advice queues, nothing is typed. + m.adviseKnowledge(a, "⏺ Edit(src/a/x.go)", toolPane) + if len(*typed) != 0 { + t.Fatalf("typed during a tool call: %v", *typed) + } + m.adviseKnowledge(a, "⏺ Edit(src/a/x.go)", workingPane) + if len(*typed) != 1 || (*typed)[0] != "📚 Knowledge: A1" { + t.Fatalf("typed = %v", *typed) + } + // Cooldown holds the second line back until the clock moves. + m.adviseKnowledge(a, "⏺ Edit(src/a/x.go)", workingPane) + if len(*typed) != 1 { + t.Fatalf("cooldown ignored: %v", *typed) + } + *now = now.Add(time.Minute) + m.adviseKnowledge(a, "⏺ Edit(src/a/x.go)", workingPane) + if len(*typed) != 2 || (*typed)[1] != "📚 Knowledge: A2" { + t.Fatalf("typed = %v", *typed) + } + // MaxPerKick is 2: the third candidate never goes out this kick. + *now = now.Add(time.Minute) + m.adviseKnowledge(a, "⏺ Edit(src/a/x.go)", workingPane) + if len(*typed) != 2 { + t.Fatalf("cap ignored: %v", *typed) + } + if len(adv.asked) != 1 { + t.Errorf("adviser asked %d times for one scope, want 1", len(adv.asked)) + } +} + +func TestAdviseKnowledge_IdleTurnDropsPending(t *testing.T) { + adv := &fakeAdviser{policy: enabledPolicy(), byKey: map[string][]crux.KnowledgeAdvice{ + "src/a": {{Slug: "a1", Title: "A1"}}, + }} + m, a, typed := advisorManager(t, adv) + fakeClock(m, time.Date(2026, 11, 7, 12, 1, 0, 0, time.UTC)) + m.adviseKnowledge(a, "", workingPane) + m.adviseKnowledge(a, "⏺ Edit(src/a/x.go)", toolPane) // queued + m.adviseKnowledge(a, "⏺ Edit(src/a/x.go)", idlePane) // turn over: dropped + m.adviseKnowledge(a, "⏺ Edit(src/a/x.go)", workingPane) + if len(*typed) != 0 { + t.Fatalf("advice for a finished turn was typed: %v", *typed) + } +} + +func TestAdviseKnowledge_Refusals(t *testing.T) { + newCase := func() (*fakeAdviser, *Manager, *AgentProcess, *[]string) { + adv := &fakeAdviser{policy: enabledPolicy(), byKey: map[string][]crux.KnowledgeAdvice{ + "src/a": {{Slug: "a1", Title: "A1"}}, + }} + m, a, typed := advisorManager(t, adv) + fakeClock(m, time.Date(2026, 11, 7, 12, 1, 0, 0, time.UTC)) + m.adviseKnowledge(a, "", workingPane) + return adv, m, a, typed + } + t.Run("disabled policy parses nothing", func(t *testing.T) { + adv, m, a, typed := newCase() + adv.policy = crux.KnowledgeAdvisorPolicy{} + m.adviseKnowledge(a, "⏺ Edit(src/a/x.go)", workingPane) + if len(adv.asked) != 0 || len(*typed) != 0 { + t.Fatalf("asked %v typed %v", adv.asked, *typed) + } + }) + t.Run("kick being typed", func(t *testing.T) { + _, m, a, typed := newCase() + a.kickDelivering.Store(true) + m.adviseKnowledge(a, "⏺ Edit(src/a/x.go)", workingPane) + if len(*typed) != 0 { + t.Fatal("typed into a kick in delivery") + } + }) + t.Run("no kick yet", func(t *testing.T) { + _, m, a, typed := newCase() + a.LastKick = nil + m.adviseKnowledge(a, "⏺ Edit(src/a/x.go)", workingPane) + if len(*typed) != 0 { + t.Fatal("typed before any kick") + } + }) + t.Run("human attached", func(t *testing.T) { + _, m, a, typed := newCase() + termSeams(m).sessionAttached = func(*AgentProcess) bool { return true } + m.adviseKnowledge(a, "⏺ Edit(src/a/x.go)", workingPane) + if len(*typed) != 0 { + t.Fatal("typed over an attached client") + } + }) + t.Run("no adviser installed", func(t *testing.T) { + _, m, a, typed := newCase() + m.SetKnowledgeAdviser(nil) + m.adviseKnowledge(a, "⏺ Edit(src/a/x.go)", workingPane) + if len(*typed) != 0 { + t.Fatal("typed with the advisor off") + } + }) +} diff --git a/src/crux/agent/manager.go b/src/crux/agent/manager.go index 3c48d910cf..976442eb70 100644 --- a/src/crux/agent/manager.go +++ b/src/crux/agent/manager.go @@ -559,8 +559,9 @@ type Manager struct { // rateLimitRelaunchMu guards lastRateLimitRelaunch, the fleet-wide clock // that spaces rate-limit relaunches (rateLimitRelaunchFleetSpacing). Its // own mutex: the pane pollers that consult it must not take m.mu. - rateLimitRelaunchMu sync.Mutex - lastRateLimitRelaunch time.Time + rateLimitRelaunchMu sync.Mutex + lastRateLimitRelaunch time.Time + sharedCLIMemoryWarnOnce sync.Once // see warnSharedCLIMemoryOnce (hivecommons/hive#17031) // thrashMu guards thrash — its own mutex, NEVER m.mu: the breaker runs on // the output-capture goroutines, and taking m.mu there risks startup @@ -754,13 +755,13 @@ type Manager struct { breakerPaused map[string]bool // recordPromptCallback, when set, persists the fully-expanded prompt text - // delivered to an agent so owners can review it later. - // - // Held as an atomic.Pointer rather than behind m.mu because the kick path + // delivered to an agent so owners can review it later. Held as an + // atomic.Pointer rather than behind m.mu because the kick path // (deliverKickLocked) already holds m.mu when it fires this. m.mu is a // non-reentrant RWMutex, so reading the callback under a second Lock there // would deadlock the kick path. recordPromptCallback atomic.Pointer[func(agent, trigger, prompt string)] + knowledgeAdvisor atomic.Pointer[knowledgeAdvisor] // mid-task knowledge advisor (#17052); nil = off // spanStarter, when set, opens the trace spans the runtime emits // (SendKick's agent.send_kick). Same atomic.Pointer discipline as // recordPromptCallback: read on paths that hold m.mu. Nil falls back to diff --git a/src/crux/agent/manager_env.go b/src/crux/agent/manager_env.go index 355f4b90b5..f198eab532 100644 --- a/src/crux/agent/manager_env.go +++ b/src/crux/agent/manager_env.go @@ -405,6 +405,7 @@ func (m *Manager) agentEnvPairs(agent *AgentProcess) []agentEnvPair { } vars = append(vars, agentEnvPair{claudeAutoModeServerEnv, claudeAutoModeServerOff, false}) } + vars = append(vars, cliMemoryEnvPairs(agent, backend)...) if m.copilotAuthToken != "" { vars = append(vars, agentEnvPair{copilotTokenEnvVar, m.copilotAuthToken, true}) } diff --git a/src/crux/agent/manager_homes.go b/src/crux/agent/manager_homes.go index a9068ca7ba..c7781b279d 100644 --- a/src/crux/agent/manager_homes.go +++ b/src/crux/agent/manager_homes.go @@ -100,13 +100,13 @@ func (m *Manager) setupCodexHome(agent *AgentProcess) { if readFailed { // Preserve unknown existing content rather than overwrite it blindly. } else if configBytes != nil || salvagedConfig != nil { - mergedConfig := codexConfigWithUpdateCheckDisabled(configBytes) + mergedConfig := codexConfigSeed(configBytes, agent.Config.CLIMemory.AutoMemoryEnabled()) if string(mergedConfig) != string(configBytes) || salvagedConfig != nil { if err := writeFileAsUser(agentUser, configPath, mergedConfig); err != nil { m.logger.Warn("failed to seed codex config", "agent", agent.Name, "dir", dir, "error", err) } } - } else if err := writeFileAsUser(agentUser, configPath, codexConfigWithUpdateCheckDisabled(nil)); err != nil { + } else if err := writeFileAsUser(agentUser, configPath, codexConfigSeed(nil, agent.Config.CLIMemory.AutoMemoryEnabled())); err != nil { m.logger.Warn("failed to seed codex config", "agent", agent.Name, "dir", dir, "error", err) } // Bridge auth: symlink the per-agent auth.json to the shared login file so a diff --git a/src/crux/agent/manager_kick.go b/src/crux/agent/manager_kick.go index 53364a2ea7..cbd3a272c6 100644 --- a/src/crux/agent/manager_kick.go +++ b/src/crux/agent/manager_kick.go @@ -317,6 +317,12 @@ func (m *Manager) deliverKickLocked(agent *AgentProcess, message, trigger string time.Sleep(staleCheckDelay) } + // Persistent CLI memory (hivecommons/hive#17032) is wiped before the + // conversation /clear below, and skipped on the same resume kicks: a + // resumed session is continuing prior work, not starting a fresh turn. + if !skipClear { + m.clearCLIMemoryForKick(agent, backend) + } if agent.Config.ClearOnKick && !skipClear { if err := m.tmuxSendLiteralForAgent(agent, "/clear"); err != nil { return m.kickDeliveryFailedLocked(agent, "send text", err) diff --git a/src/crux/agent/manager_poll.go b/src/crux/agent/manager_poll.go index 31bd3da5fb..112f75cad4 100644 --- a/src/crux/agent/manager_poll.go +++ b/src/crux/agent/manager_poll.go @@ -325,7 +325,9 @@ func (m *Manager) pollTmuxOutputForAgent(agent *AgentProcess, ctx context.Contex } if !IsInferenceBackend(effectiveBackend(agent)) { - m.nudgeIfPollingCI(agent, output, m.captureVisiblePaneForAgent(agent)) + visible := m.captureVisiblePaneForAgent(agent) + m.nudgeIfPollingCI(agent, output, visible) + m.adviseKnowledge(agent, output, visible) } // Detect copilot hung: if running long enough with no CLI prompt, diff --git a/src/crux/agent/manager_test.go b/src/crux/agent/manager_test.go index 6c046c6268..21add302e2 100644 --- a/src/crux/agent/manager_test.go +++ b/src/crux/agent/manager_test.go @@ -591,10 +591,11 @@ func TestAgentEnvPairs_BDDirFromBeadsDir(t *testing.T) { t.Error("BD_DIR should be present when BeadsDir is configured") } - // Count should be baseEnvVarCount + 1 for BD_DIR - const expectedWithBDDir = baseEnvVarCount + 1 + // Count should be baseEnvVarCount + 1 for BD_DIR + 1 for the Claude CLI's + // CLAUDE_CODE_DISABLE_AUTO_MEMORY pin (hivecommons/hive#17032). + const expectedWithBDDir = baseEnvVarCount + 2 if len(pairs) != expectedWithBDDir { - t.Errorf("testEnvPairs() returned %d vars, want %d (base + BD_DIR)", len(pairs), expectedWithBDDir) + t.Errorf("testEnvPairs() returned %d vars, want %d (base + BD_DIR + auto-memory pin)", len(pairs), expectedWithBDDir) } } diff --git a/src/crux/agent/sandbox_executor.go b/src/crux/agent/sandbox_executor.go index 75349f9410..ec0d5d2ca9 100644 --- a/src/crux/agent/sandbox_executor.go +++ b/src/crux/agent/sandbox_executor.go @@ -17,6 +17,7 @@ import ( "github.com/hivecommons/hive/crux/config" "github.com/hivecommons/hive/crux/effects" "github.com/hivecommons/hive/crux/internal/textutil" + "github.com/hivecommons/hive/crux/kubejob" "github.com/hivecommons/hive/crux/logscrub" "github.com/hivecommons/hive/crux/outputschema" "github.com/hivecommons/hive/crux/pushbroker" @@ -129,8 +130,16 @@ type SandboxVerifyResult struct { TimedOut bool } -// Passed reports whether the command ran to completion with exit 0. -func (v SandboxVerifyResult) Passed() bool { return v.Err == "" && v.ExitCode == 0 && !v.TimedOut } +// Passed reports whether the command ran to completion with exit 0. A +// launcher that returned no error but could not read the exit code back +// (a Complete Job whose pod is already gone) counts as passed too: the +// Job's own success condition is the fact, the missing code is not a failure. +func (v SandboxVerifyResult) Passed() bool { + if v.Err != "" || v.TimedOut { + return false + } + return v.ExitCode == 0 || v.ExitCode == kubejob.ExitCodeUnknown +} type SandboxExecutor struct { Launcher sandbox.Launcher @@ -622,7 +631,9 @@ func sandboxPublishWithheld(res SandboxKickResult) string { } return reason } - if res.Sandbox.ExitCode != 0 { + // A completed Job whose pod could not be read has no exit code; that is + // not a failure, and the guessed 0 it used to carry was not a fact either. + if code := res.Sandbox.ExitCode; code != 0 && code != kubejob.ExitCodeUnknown { return fmt.Sprintf("sandbox exited %d", res.Sandbox.ExitCode) } return "" diff --git a/src/crux/agent/sandbox_kick_log.go b/src/crux/agent/sandbox_kick_log.go index 56aeede587..39833f57f3 100644 --- a/src/crux/agent/sandbox_kick_log.go +++ b/src/crux/agent/sandbox_kick_log.go @@ -4,8 +4,11 @@ import ( "fmt" "os" "path/filepath" + "strconv" "strings" "time" + + "github.com/hivecommons/hive/crux/kubejob" ) const ( @@ -25,7 +28,11 @@ const ( // text from the agent. func sandboxKickLogBody(runtime string, res SandboxKickResult, runErr error) string { var b strings.Builder - fmt.Fprintf(&b, "runtime: %s\nexit_code: %d\ncommits: %d\n", runtime, res.Sandbox.ExitCode, res.CommitCount) + exitCode := strconv.Itoa(res.Sandbox.ExitCode) + if res.Sandbox.ExitCode == kubejob.ExitCodeUnknown { + exitCode = "unknown" + } + fmt.Fprintf(&b, "runtime: %s\nexit_code: %s\ncommits: %d\n", runtime, exitCode, res.CommitCount) if res.Branch != "" { fmt.Fprintf(&b, "branch: %s\n", res.Branch) } diff --git a/src/crux/agent/sandbox_kick_log_test.go b/src/crux/agent/sandbox_kick_log_test.go index da308ac8a7..1ac931e14c 100644 --- a/src/crux/agent/sandbox_kick_log_test.go +++ b/src/crux/agent/sandbox_kick_log_test.go @@ -10,6 +10,7 @@ import ( "github.com/hivecommons/hive/crux" "github.com/hivecommons/hive/crux/config" + "github.com/hivecommons/hive/crux/kubejob" "github.com/hivecommons/hive/crux/outputschema" "github.com/hivecommons/hive/crux/sandbox" ) @@ -146,3 +147,39 @@ func TestBuildSandboxRunCarriesPRWithheld(t *testing.T) { t.Errorf("PRWithheld = %q (len %d), want the bounded reason", run.PRWithheld, len([]rune(run.PRWithheld))) } } + +func TestSandboxKickLogBodyUnknownExitCode(t *testing.T) { + res := SandboxKickResult{Sandbox: sandbox.Result{ExitCode: kubejob.ExitCodeUnknown}} + body := sandboxKickLogBody("job", res, nil) + if !strings.Contains(body, "exit_code: unknown\n") { + t.Errorf("unreadable-pod run must not render a guessed exit code:\n%s", body) + } +} + +func TestSandboxPublishWithheldIgnoresUnknownExitCode(t *testing.T) { + unknown := SandboxKickResult{Sandbox: sandbox.Result{ExitCode: kubejob.ExitCodeUnknown}} + if got := sandboxPublishWithheld(unknown); got != "" { + t.Errorf("completed-without-code must not withhold the PR, got %q", got) + } + failed := SandboxKickResult{Sandbox: sandbox.Result{ExitCode: 3}} + if got := sandboxPublishWithheld(failed); got != "sandbox exited 3" { + t.Errorf("got %q, want sandbox exited 3", got) + } +} + +func TestSandboxVerifyResultPassedUnknownExitCode(t *testing.T) { + // A Complete verify Job whose pod could not be read back carries no exit + // code and no error; that must not withhold the PR. + if !(SandboxVerifyResult{ExitCode: kubejob.ExitCodeUnknown}).Passed() { + t.Error("nil-error verify with unknown exit code must pass") + } + if (SandboxVerifyResult{ExitCode: kubejob.ExitCodeUnknown, Err: "boom"}).Passed() { + t.Error("unknown exit code with an error must not pass") + } + if (SandboxVerifyResult{ExitCode: kubejob.ExitCodeUnknown, TimedOut: true}).Passed() { + t.Error("unknown exit code after a timeout must not pass") + } + if (SandboxVerifyResult{ExitCode: 1}).Passed() { + t.Error("exit 1 must not pass") + } +} diff --git a/src/crux/api/client/client_test.go b/src/crux/api/client/client_test.go index 915b864b37..373adbb5ef 100644 --- a/src/crux/api/client/client_test.go +++ b/src/crux/api/client/client_test.go @@ -140,8 +140,10 @@ func TestParityHostVersusSetterTable(t *testing.T) { t.Errorf("api.HostSetters[%q] has unknown kind %q", name, row.Kind) } } - if api.HostSetters["SetSpanStarter"].Kind != api.HostSetterInProcessOnly { - t.Error("SetSpanStarter is the one in-process-only setter") + for _, name := range []string{"SetSpanStarter", "SetKnowledgeAdviser"} { + if api.HostSetters[name].Kind != api.HostSetterInProcessOnly { + t.Errorf("%s is an in-process-only setter", name) + } } } diff --git a/src/crux/api/host_setters.go b/src/crux/api/host_setters.go index b83f00e043..bb10303485 100644 --- a/src/crux/api/host_setters.go +++ b/src/crux/api/host_setters.go @@ -85,7 +85,8 @@ var HostSetters = map[string]HostSetter{ "SetConditionReporter": {HostSetterEvent, EventCondition + ", " + hostViaConditions}, // In-process only. - "SetSpanStarter": {HostSetterInProcessOnly, "OpenTelemetry global tracer in the runtime process; trajectory events are independent of spans"}, + "SetSpanStarter": {HostSetterInProcessOnly, "OpenTelemetry global tracer in the runtime process; trajectory events are independent of spans"}, + "SetKnowledgeAdviser": {HostSetterInProcessOnly, "the knowledge store lives in the hive process; a sidecar runtime runs without the mid-task knowledge advisor (hivecommons/hive#17052 phase 1)"}, // Advisor lane (v6, #9722): the sidecar runtime does not run the advisor // lane yet; resolvers are installed only in-process until the lane's // policy rides the hive callback. diff --git a/src/crux/api/runs.go b/src/crux/api/runs.go new file mode 100644 index 0000000000..29360311d3 --- /dev/null +++ b/src/crux/api/runs.go @@ -0,0 +1,122 @@ +package api + +import "time" + +// Contained runs and saved run results (hivecommons/crux#114, S2 and S7): +// +// POST /v1/runs run an untrusted command in a sandbox +// GET /v1/runs/{id} the saved record, whatever the process state +// POST /v1/runs/{id}/cancel cancel; after completion returns the result +// unchanged with already_finished: true +// +// Routes beyond these (restart, listing) are deferred; see +// src/docs/design/crux-work-services.md. +const PathRuns = "/" + Version + "/runs" + +// RunPath is the route of one run's saved record. +func RunPath(id string) string { return PathRuns + "/" + id } + +// RunCancelPath is the route that cancels one run. +func RunCancelPath(id string) string { return RunPath(id) + "/cancel" } + +// The runs routes answer CodeUnsupported (501, shared with the checkout +// routes) when the request asks for something the configured backend cannot +// enforce (a network mode, a profile, a workspace form); the message names it +// and the run never starts with the limit dropped. It differs from +// CodeNotSupported, which is a whole route the server cannot serve (here: a +// server started without a contained-run backend answers POST /v1/runs with +// CodeNotSupported while still serving the saved records). + +// Run statuses, the closed set every record reports. +const ( + RunAccepted = "accepted" + RunRunning = "running" + RunWaiting = "waiting" + RunCompleted = "completed" + RunFailed = "failed" + RunCancelled = "cancelled" + RunUnfinished = "unfinished" + RunUnsupported = "unsupported" +) + +// Run profiles. +const ( + // RunProfileExperiment (the default) runs with network none, no + // credentials and time and output limits. + RunProfileExperiment = "experiment" + // RunProfileAgent is S6's execution half and is not yet accepted + // (CodeUnsupported). + RunProfileAgent = "agent" +) + +// Network modes a run may request. +const ( + RunNetworkNone = "none" + RunNetworkRestricted = "restricted" +) + +// ContainedRunWorktree is the ad-hoc workspace form: the service clones repo and +// pins commit (a full 40-hex SHA) under the run's directory. +type ContainedRunWorktree struct { + Repo string `json:"repo"` + Commit string `json:"commit"` +} + +// ContainedRunRequest is POST /v1/runs. Exactly one of Checkout, Worktree or +// WorkspacePath names the workspace. Checkout (an S1 id) is accepted by the +// wire shape but answers CodeUnsupported until the checkout service lands. +type ContainedRunRequest struct { + Checkout string `json:"checkout,omitempty"` + Worktree *ContainedRunWorktree `json:"worktree,omitempty"` + WorkspacePath string `json:"workspace_path,omitempty"` + Command []string `json:"command"` + EnvAllowlist []string `json:"env_allowlist,omitempty"` + // Network is RunNetworkNone (default) or RunNetworkRestricted. + Network string `json:"network,omitempty"` + // TimeoutMs bounds the command; zero uses the server default. + TimeoutMs int64 `json:"timeout_ms,omitempty"` + // MaxOutputBytes caps each of stdout and stderr in the response; zero + // uses the server default. The full output is kept as an artifact. + MaxOutputBytes int64 `json:"max_output_bytes,omitempty"` + // Profile is RunProfileExperiment (default) or RunProfileAgent. + Profile string `json:"profile,omitempty"` + // IdempotencyKey, when set, makes a repeated request return the + // existing run instead of starting a second one (S7). + IdempotencyKey string `json:"idempotency_key,omitempty"` + // Detach returns as soon as the run is accepted (202) instead of + // waiting for the result; poll GET /v1/runs/{id}. + Detach bool `json:"detach,omitempty"` +} + +// Run is the saved record of one contained run: the response of every runs +// route. Fields that are not yet known are absent; ExitCode in particular is +// present only when the command's exit is known, never guessed. +type ContainedRun struct { + ID string `json:"id"` + Status string `json:"status"` + Owner string `json:"owner,omitempty"` + // Reason explains a failed, unfinished or unsupported status. + Reason string `json:"reason,omitempty"` + CreatedAt time.Time `json:"created_at"` + StartedAt *time.Time `json:"started_at,omitempty"` + FinishedAt *time.Time `json:"finished_at,omitempty"` + + Profile string `json:"profile,omitempty"` + Network string `json:"network,omitempty"` + Backend string `json:"backend,omitempty"` + Command []string `json:"command,omitempty"` + Workdir string `json:"workspace,omitempty"` + ExitCode *int `json:"exit_code,omitempty"` + TimedOut bool `json:"timed_out,omitempty"` + Stdout string `json:"stdout,omitempty"` + Stderr string `json:"stderr,omitempty"` + // StdoutTruncatedAt and StderrTruncatedAt are the byte offsets at which + // the response output was cut; absent when nothing was truncated. The + // full, scrubbed output is the stdout.txt / stderr.txt artifact in the + // run's directory. + StdoutTruncatedAt *int64 `json:"stdout_truncated_at,omitempty"` + StderrTruncatedAt *int64 `json:"stderr_truncated_at,omitempty"` + // AlreadyFinished is set on a cancel response when the run had already + // reached a terminal status; the record is returned unchanged. + AlreadyFinished bool `json:"already_finished,omitempty"` +} diff --git a/src/crux/api/runs_client.go b/src/crux/api/runs_client.go new file mode 100644 index 0000000000..446f05420a --- /dev/null +++ b/src/crux/api/runs_client.go @@ -0,0 +1,27 @@ +package api + +import ( + "context" + "net/http" +) + +// CreateRun is POST /v1/runs: the saved record, final unless req.Detach. +func (c *Client) CreateRun(ctx context.Context, req ContainedRunRequest) (ContainedRun, error) { + var out ContainedRun + err := c.Do(ctx, http.MethodPost, PathRuns, req, &out) + return out, err +} + +// GetRun is GET /v1/runs/{id}. +func (c *Client) GetRun(ctx context.Context, id string) (ContainedRun, error) { + var out ContainedRun + err := c.Do(ctx, http.MethodGet, RunPath(id), nil, &out) + return out, err +} + +// CancelRun is POST /v1/runs/{id}/cancel. +func (c *Client) CancelRun(ctx context.Context, id string) (ContainedRun, error) { + var out ContainedRun + err := c.Do(ctx, http.MethodPost, RunCancelPath(id), nil, &out) + return out, err +} diff --git a/src/crux/api/runs_test.go b/src/crux/api/runs_test.go new file mode 100644 index 0000000000..efe0433393 --- /dev/null +++ b/src/crux/api/runs_test.go @@ -0,0 +1,12 @@ +package api + +import "testing" + +func TestRunPaths(t *testing.T) { + if PathRuns != "/v1/runs" || RunPath("run_a") != "/v1/runs/run_a" || RunCancelPath("run_a") != "/v1/runs/run_a/cancel" { + t.Fatalf("paths: %s %s %s", PathRuns, RunPath("run_a"), RunCancelPath("run_a")) + } + if CodeUnsupported == CodeNotSupported { + t.Fatal("unsupported-limit refusals must be distinguishable from a not-configured server") + } +} diff --git a/src/crux/checkout/checkout.go b/src/crux/checkout/checkout.go index 2ffaa3e8f0..c1d87f2b0e 100644 --- a/src/crux/checkout/checkout.go +++ b/src/crux/checkout/checkout.go @@ -189,13 +189,29 @@ func (s *Service) Allowed(repo string) (rule string, err error) { return "", fmt.Errorf("%w: repository %q: the checkout allowlist is empty", ErrForbidden, repo) } for _, p := range s.cfg.AllowedRepos { - if strings.HasPrefix(repo, p) { + if prefixMatches(repo, p) { return p, nil } } return "", fmt.Errorf("%w: repository %q matches none of the allowed prefixes %s", ErrForbidden, repo, strings.Join(s.cfg.AllowedRepos, ", ")) } +// prefixMatches reports whether repo falls under the allowlist prefix p. +// A prefix that ends in "/" is a directory and admits everything beneath +// it; any other prefix must be followed by a segment boundary ("/", the +// ".git" suffix, or the end of the URL), so "https://h/org" does not admit +// "https://h/org-evil/x" or "https://h.evil/x". +func prefixMatches(repo, p string) bool { + rest, ok := strings.CutPrefix(repo, p) + if !ok { + return false + } + if strings.HasSuffix(p, "/") { + return true + } + return rest == "" || rest == ".git" || strings.HasPrefix(rest, "/") +} + // Create provisions a checkout for req, recorded as owned by req.Owner. func (s *Service) Create(ctx context.Context, req Request) (Record, error) { rec, err := s.validate(req) @@ -316,7 +332,12 @@ func (s *Service) validate(req Request) (Record, error) { } // parseRepo accepts an https:// or file:// URL without credentials, query or -// fragment, so a token can never ride into a record. +// fragment, so a token can never ride into a record. The path must already +// be in canonical form — no ".", ".." or empty segments and no +// percent-encoding — because Allowed compares the string the caller sent +// while git (via libcurl, or literally for file://) resolves dot segments: +// "https://h/allowed/../other/repo" would pass a prefix check for +// "https://h/allowed/" and clone other/repo. func parseRepo(raw string) (*url.URL, error) { u, err := url.Parse(raw) if err != nil || (u.Scheme != "https" && u.Scheme != "file") || u.User != nil || u.RawQuery != "" || u.Fragment != "" { @@ -325,9 +346,27 @@ func parseRepo(raw string) (*url.URL, error) { if (u.Scheme == "https" && u.Host == "") || (u.Scheme == "file" && u.Path == "") { return nil, fmt.Errorf("%w: repo %q names no host or path", ErrBadRequest, raw) } + if u.RawPath != "" || !canonicalPath(u.Path) { + return nil, fmt.Errorf("%w: repo path must be canonical — no \".\", \"..\" or empty segments and no percent-encoding (got %q)", ErrBadRequest, raw) + } return u, nil } +// canonicalPath reports whether p has no ".", ".." or empty segments. A +// single trailing "/" is allowed. +func canonicalPath(p string) bool { + p = strings.TrimSuffix(p, "/") + if p == "" { + return true + } + for _, seg := range strings.Split(strings.TrimPrefix(p, "/"), "/") { + if seg == "" || seg == "." || seg == ".." { + return false + } + } + return true +} + // sourceDir is the shared clone for (repo, owner). func (s *Service) sourceDir(repo, owner string) string { sum := sha256.Sum256([]byte(repo)) diff --git a/src/crux/checkout/checkout_test.go b/src/crux/checkout/checkout_test.go index 95674d2fa5..6629b43020 100644 --- a/src/crux/checkout/checkout_test.go +++ b/src/crux/checkout/checkout_test.go @@ -158,6 +158,11 @@ func TestCreateRefusals(t *testing.T) { repo, shas := fixtureRepo(t) svc := newTestService(t, repo, nil) ctx := context.Background() + // The allowlist admits the fixture's parent directory; the bypass cases + // below spell the same bare repo through paths that would clone it (or + // a sibling) while escaping a plain string-prefix comparison. + fixtureDir := filepath.Dir(strings.TrimPrefix(repo, "file://")) + allowedDir := "file://" + fixtureDir ok := Request{Repo: repo, Commit: shas[0], Owner: "o"} cases := []struct { name string @@ -178,6 +183,11 @@ func TestCreateRefusals(t *testing.T) { {"credentials in url", func(r *Request) { r.Repo = "https://user:tok@github.com/org/name.git" }, ErrBadRequest, "credentials"}, {"query in url", func(r *Request) { r.Repo = "https://github.com/org/name.git?x=1" }, ErrBadRequest, "query"}, {"no host", func(r *Request) { r.Repo = "https:///name.git" }, ErrBadRequest, "no host"}, + {"dot-dot segment", func(r *Request) { r.Repo = allowedDir + "/../" + filepath.Base(fixtureDir) + "/" + filepath.Base(repo) }, ErrBadRequest, "canonical"}, + {"dot segment", func(r *Request) { r.Repo = allowedDir + "/./" + filepath.Base(repo) }, ErrBadRequest, "canonical"}, + {"empty segment", func(r *Request) { r.Repo = allowedDir + "//" + filepath.Base(repo) }, ErrBadRequest, "canonical"}, + {"percent-encoded segment", func(r *Request) { r.Repo = allowedDir + "/%2e%2e/" + filepath.Base(repo) }, ErrBadRequest, "canonical"}, + {"mid-segment prefix", func(r *Request) { r.Repo = allowedDir + "-evil/" + filepath.Base(repo) }, ErrForbidden, "matches none of the allowed prefixes"}, {"off allowlist", func(r *Request) { r.Repo = "https://github.com/org/name.git" }, ErrForbidden, "matches none of the allowed prefixes"}, {"unknown commit", func(r *Request) { r.Commit = strings.Repeat("0", 40) }, ErrBadRequest, "could not be fetched"}, } @@ -216,6 +226,9 @@ func TestNewValidatesConfig(t *testing.T) { if _, err := New(Config{Dir: t.TempDir(), AllowedRepos: []string{"github.com/org/"}}); !errors.Is(err, ErrBadRequest) || !strings.Contains(err.Error(), "allowlist entry") { t.Fatalf("New with bare prefix = %v", err) } + if _, err := New(Config{Dir: t.TempDir(), AllowedRepos: []string{"https://github.com/org/../"}}); !errors.Is(err, ErrBadRequest) || !strings.Contains(err.Error(), "canonical") { + t.Fatalf("New with dot-dot prefix = %v", err) + } svc, err := New(Config{Dir: t.TempDir(), AllowedRepos: []string{" https://github.com/org/ "}}) if err != nil || svc.cfg.AllowedRepos[0] != "https://github.com/org/" || svc.cfg.MaxCheckouts != DefaultMaxCheckouts { t.Fatalf("New = %+v %v", svc, err) @@ -471,3 +484,52 @@ func contains(list []string, want string) bool { } return false } + +func TestAllowedMatchesOnSegmentBoundary(t *testing.T) { + svc, err := New(Config{Dir: t.TempDir(), AllowedRepos: []string{"https://github.com/org", "https://host.example/dir/"}}) + if err != nil { + t.Fatal(err) + } + for repo, want := range map[string]bool{ + "https://github.com/org": true, + "https://github.com/org.git": true, + "https://github.com/org/repo": true, + "https://github.com/org/repo.git": true, + "https://github.com/org-evil/repo": false, + "https://github.com/organic/repo": false, + "https://github.com/org.evil": false, + "https://github.com.evil.example/org/x": false, + "https://host.example/dir/anything/x": true, + "https://host.example/dir": false, + "https://host.example/directory/x": false, + } { + _, err := svc.Allowed(repo) + if got := err == nil; got != want { + t.Errorf("Allowed(%q) = %v, want allowed=%v", repo, err, want) + } + } +} + +func TestParseRepoRequiresCanonicalPath(t *testing.T) { + for raw, want := range map[string]bool{ + "https://github.com/org/repo": true, + "https://github.com/org/repo/": true, + "https://github.com/org/": true, + "file:///srv/repos/x.git": true, + "https://github.com/org/../other/repo": false, + "https://github.com/org/./repo": false, + "https://github.com/org//repo": false, + "https://github.com/org/%2e%2e/repo": false, + "https://github.com/org/re%2Fpo": false, + "file:///srv/repos/../../etc/x.git": false, + "file:///srv/repos/..": false, + } { + _, err := parseRepo(raw) + if got := err == nil; got != want { + t.Errorf("parseRepo(%q) = %v, want ok=%v", raw, err, want) + } + if err != nil && !errors.Is(err, ErrBadRequest) { + t.Errorf("parseRepo(%q) = %v, want ErrBadRequest", raw, err) + } + } +} diff --git a/src/crux/cli/cli.go b/src/crux/cli/cli.go index b3879de2b5..2ef01ed3d7 100644 --- a/src/crux/cli/cli.go +++ b/src/crux/cli/cli.go @@ -209,6 +209,11 @@ func (e *Env) dispatch(ctx context.Context, opts globalOptions, name string, arg } } return e.local(ctx, opts, name, args) + case "runs": + // The contained-run family lives on a `crux serve`; there is no + // in-process form, so the verb is only reachable with --server. + fmt.Fprintln(e.Stderr, "crux: runs needs --server ADDR (or CRUX_SERVER); contained runs execute on a crux serve") + return ExitUsage case "help", "-h", "--help": fs := flag.NewFlagSet("crux", flag.ContinueOnError) e.usage(fs) @@ -339,6 +344,8 @@ Commands (each maps onto crux.Runtime): runtime that spawned it, not run by hand cline-turn one bounded Cline CLI turn (stdin prompt); --model provider/model, --check for preflight + runs start|status|cancel contained command runs on a crux serve + (--server only; 'crux runs help' for flags) Work services (no runtime; hivecommons/crux#114): checkout add|rm|list pinned checkouts under <workdir>/checkouts diff --git a/src/crux/cli/remote.go b/src/crux/cli/remote.go index 20882c6a90..accd3e92b1 100644 --- a/src/crux/cli/remote.go +++ b/src/crux/cli/remote.go @@ -53,6 +53,8 @@ func (e *Env) remote(ctx context.Context, opts globalOptions, name string, args return e.remoteStop(ctx, c, args) case "checkout": return e.remoteCheckout(ctx, c, args) + case "runs": + return e.remoteRuns(ctx, c, args) default: fmt.Fprintf(e.Stderr, "crux: %q is not available with --server; it runs where the runtime is\n", name) return ExitUsage diff --git a/src/crux/cli/runs.go b/src/crux/cli/runs.go new file mode 100644 index 0000000000..7b694ae606 --- /dev/null +++ b/src/crux/cli/runs.go @@ -0,0 +1,187 @@ +package cli + +import ( + "context" + "encoding/json" + "fmt" + "strings" + + "github.com/hivecommons/hive/crux/api" +) + +// runsUsage is the `crux runs` synopsis. The verb is `runs`, not `run`, +// because `crux run` already starts an agent from a definition. +const runsUsage = `usage: crux --server ADDR runs start [flags] -- <command> [args…] + crux --server ADDR runs status <id> + crux --server ADDR runs cancel <id> + +start flags: + --repo URL --commit SHA clone URL at SHA into a fresh workspace + --workspace PATH run in an existing directory on the server + --env NAME pass this environment variable through (repeatable) + --network none|restricted network for the command (default none) + --timeout DURATION wall-clock limit (server default when unset) + --max-output BYTES bytes of stdout/stderr returned (server default) + --profile experiment|agent + --idempotency-key KEY return the existing run for a repeated request + --detach return the accepted record instead of waiting + --json print the record as JSON` + +// remoteRuns is `crux --server … runs`: the contained-run family (RFC +// crux#114 S2 + S7). It only exists against a server; the runtime that +// launches sandboxes and keeps run records lives there. +func (e *Env) remoteRuns(ctx context.Context, c *api.Client, args []string) int { + if len(args) == 0 { + fmt.Fprintln(e.Stderr, runsUsage) + return ExitUsage + } + switch args[0] { + case "start": + return e.remoteRunsStart(ctx, c, args[1:]) + case "status": + return e.remoteRunsGet(ctx, c, args[1:]) + case "cancel": + return e.remoteRunsCancel(ctx, c, args[1:]) + case "help", "-h", "--help": + fmt.Fprintln(e.Stderr, runsUsage) + return ExitOK + default: + fmt.Fprintf(e.Stderr, "crux: runs: unknown subcommand %q\n%s\n", args[0], runsUsage) + return ExitUsage + } +} + +// stringList is a repeatable string flag. +type stringList []string + +func (l *stringList) String() string { return strings.Join(*l, ",") } +func (l *stringList) Set(v string) error { *l = append(*l, v); return nil } + +func (e *Env) remoteRunsStart(ctx context.Context, c *api.Client, args []string) int { + fs := e.subFlags("runs start") + var req api.ContainedRunRequest + var wt api.ContainedRunWorktree + var env stringList + fs.StringVar(&wt.Repo, "repo", "", "repository URL to clone") + fs.StringVar(&wt.Commit, "commit", "", "full commit SHA to check out") + fs.StringVar(&req.WorkspacePath, "workspace", "", "existing directory on the server") + fs.Var(&env, "env", "environment variable to pass through (repeatable)") + fs.StringVar(&req.Network, "network", "", "none or restricted") + timeout := fs.Duration("timeout", 0, "wall-clock limit") + fs.Int64Var(&req.MaxOutputBytes, "max-output", 0, "bytes of output returned") + fs.StringVar(&req.Profile, "profile", "", "experiment or agent") + fs.StringVar(&req.IdempotencyKey, "idempotency-key", "", "idempotency key") + fs.BoolVar(&req.Detach, "detach", false, "return the accepted record") + asJSON := fs.Bool("json", false, "print the record as JSON") + if code, ok := parseSub(fs, args); !ok { + return code + } + if fs.NArg() == 0 { + fmt.Fprintln(e.Stderr, runsUsage) + return ExitUsage + } + req.Command = fs.Args() + req.EnvAllowlist = env + req.TimeoutMs = timeout.Milliseconds() + if wt.Repo != "" || wt.Commit != "" { + req.Worktree = &wt + } + run, err := c.CreateRun(ctx, req) + if err != nil { + return e.remoteErr("runs start", "", err) + } + return e.printRun(run, *asJSON) +} + +func (e *Env) remoteRunsGet(ctx context.Context, c *api.Client, args []string) int { + fs := e.subFlags("runs status") + asJSON := fs.Bool("json", false, "print the record as JSON") + if code, ok := parseSub(fs, args); !ok { + return code + } + if fs.NArg() != 1 { + fmt.Fprintln(e.Stderr, "usage: crux --server ADDR runs status [--json] <id>") + return ExitUsage + } + run, err := c.GetRun(ctx, fs.Arg(0)) + if err != nil { + return e.remoteErr("runs status", fs.Arg(0), err) + } + return e.printRun(run, *asJSON) +} + +func (e *Env) remoteRunsCancel(ctx context.Context, c *api.Client, args []string) int { + fs := e.subFlags("runs cancel") + asJSON := fs.Bool("json", false, "print the record as JSON") + if code, ok := parseSub(fs, args); !ok { + return code + } + if fs.NArg() != 1 { + fmt.Fprintln(e.Stderr, "usage: crux --server ADDR runs cancel [--json] <id>") + return ExitUsage + } + run, err := c.CancelRun(ctx, fs.Arg(0)) + if err != nil { + return e.remoteErr("runs cancel", fs.Arg(0), err) + } + if run.AlreadyFinished { + fmt.Fprintf(e.Stderr, "crux: run %s had already finished\n", run.ID) + } + return e.printRun(run, *asJSON) +} + +// printRun writes the record: JSON when asked, otherwise a one-line +// summary on stdout with the command's own output following so a caller +// can pipe `crux runs start` like the command itself. The exit code is +// the command's when it is known; an unknown exit is ExitError, never a +// guess. +func (e *Env) printRun(run api.ContainedRun, asJSON bool) int { + if asJSON { + enc := json.NewEncoder(e.Stdout) + enc.SetIndent("", " ") + if err := enc.Encode(run); err != nil { + fmt.Fprintln(e.Stderr, "crux:", err) + return ExitError + } + return runExit(run) + } + line := fmt.Sprintf("%s %s", run.ID, run.Status) + if run.ExitCode != nil { + line += fmt.Sprintf(" exit=%d", *run.ExitCode) + } + if run.TimedOut { + line += " timed_out" + } + if run.Reason != "" { + line += " (" + run.Reason + ")" + } + fmt.Fprintln(e.Stderr, line) + if run.Stdout != "" { + fmt.Fprint(e.Stdout, run.Stdout) + if run.StdoutTruncatedAt != nil { + fmt.Fprintf(e.Stderr, "\n[stdout truncated at byte %d; the full output is kept with the run]\n", *run.StdoutTruncatedAt) + } + } + if run.Stderr != "" { + fmt.Fprint(e.Stderr, run.Stderr) + if run.StderrTruncatedAt != nil { + fmt.Fprintf(e.Stderr, "\n[stderr truncated at byte %d; the full output is kept with the run]\n", *run.StderrTruncatedAt) + } + } + return runExit(run) +} + +// runExit maps a record onto the process exit code. +func runExit(run api.ContainedRun) int { + switch run.Status { + case api.RunCompleted: + if run.ExitCode != nil && *run.ExitCode != 0 { + return ExitError + } + return ExitOK + case api.RunAccepted, api.RunRunning, api.RunWaiting: + return ExitOK + default: + return ExitError + } +} diff --git a/src/crux/cli/runs_test.go b/src/crux/cli/runs_test.go new file mode 100644 index 0000000000..726de5c7cf --- /dev/null +++ b/src/crux/cli/runs_test.go @@ -0,0 +1,252 @@ +package cli + +import ( + "encoding/json" + "net/http" + "net/http/httptest" + "path/filepath" + "strings" + "sync" + "testing" + + "github.com/hivecommons/hive/crux/api" + "github.com/hivecommons/hive/crux/config" + "github.com/hivecommons/hive/crux/runs" + "github.com/hivecommons/hive/crux/runstate" +) + +// fakeRunsAPI is the contained-run family of a `crux serve` stand-in. +type fakeRunsAPI struct { + mu sync.Mutex + created []api.ContainedRunRequest + cancelled []string +} + +func (f *fakeRunsAPI) handler() http.Handler { + exit := func(v int) *int { return &v } + cut := int64(5) + records := map[string]api.ContainedRun{ + "run_ok": {ID: "run_ok", Status: api.RunCompleted, ExitCode: exit(0), Stdout: "hello\n", Stderr: "warned\n"}, + "run_fail": {ID: "run_fail", Status: api.RunCompleted, ExitCode: exit(2), Reason: "exit status 2"}, + "run_cut": {ID: "run_cut", Status: api.RunCompleted, ExitCode: exit(0), Stdout: "12345", StdoutTruncatedAt: &cut, Stderr: "abcde", StderrTruncatedAt: &cut}, + "run_lost": {ID: "run_lost", Status: api.RunUnfinished, Reason: "pod vanished"}, + "run_late": {ID: "run_late", Status: api.RunFailed, TimedOut: true, Reason: "timed out", AlreadyFinished: true}, + "run_sleep": {ID: "run_sleep", Status: api.RunRunning}, + } + mux := http.NewServeMux() + mux.HandleFunc("POST "+api.PathRuns, func(w http.ResponseWriter, r *http.Request) { + var req api.ContainedRunRequest + if err := json.NewDecoder(r.Body).Decode(&req); err != nil { + w.WriteHeader(http.StatusBadRequest) + _ = json.NewEncoder(w).Encode(api.Error{Error: err.Error(), Code: api.CodeBadRequest}) + return + } + f.mu.Lock() + f.created = append(f.created, req) + f.mu.Unlock() + if req.Profile == api.RunProfileAgent { + w.WriteHeader(http.StatusNotImplemented) + _ = json.NewEncoder(w).Encode(api.Error{Error: "profile agent is not available yet", Code: api.CodeUnsupported}) + return + } + if req.Detach { + w.WriteHeader(http.StatusAccepted) + _ = json.NewEncoder(w).Encode(api.ContainedRun{ID: "run_new", Status: api.RunAccepted}) + return + } + _ = json.NewEncoder(w).Encode(records["run_ok"]) + }) + mux.HandleFunc("GET "+api.PathRuns+"/{id}", func(w http.ResponseWriter, r *http.Request) { + rec, ok := records[r.PathValue("id")] + if !ok { + w.WriteHeader(http.StatusNotFound) + _ = json.NewEncoder(w).Encode(api.Error{Error: "run not found", Code: api.CodeNotFound}) + return + } + _ = json.NewEncoder(w).Encode(rec) + }) + mux.HandleFunc("POST "+api.PathRuns+"/{id}/cancel", func(w http.ResponseWriter, r *http.Request) { + id := r.PathValue("id") + f.mu.Lock() + f.cancelled = append(f.cancelled, id) + f.mu.Unlock() + rec, ok := records[id] + if !ok { + w.WriteHeader(http.StatusNotFound) + _ = json.NewEncoder(w).Encode(api.Error{Error: "run not found", Code: api.CodeNotFound}) + return + } + if rec.Status == api.RunRunning { + rec.Status = api.RunCancelled + } + _ = json.NewEncoder(w).Encode(rec) + }) + return mux +} + +func TestRunsIsRemoteOnly(t *testing.T) { + t.Setenv(config.ServerEnvVar, "") + h := newHarness(t) + if code := h.run("runs", "status", "run_ok"); code != ExitUsage || !strings.Contains(h.stderr.String(), "needs --server") { + t.Fatalf("local runs: %d %s", code, h.stderr) + } + if len(h.rt.Calls()) != 0 { + t.Fatalf("runs touched the local runtime: %v", h.rt.Calls()) + } + h = newHarness(t) + h.run("help") + if !strings.Contains(h.stderr.String(), "runs start|status|cancel") { + t.Fatalf("usage does not list runs:\n%s", h.stderr) + } +} + +func TestRunsStartStatusCancel(t *testing.T) { + t.Setenv(config.ServerEnvVar, "") + t.Setenv(config.ServeTokenEnvVar, "") + f := &fakeRunsAPI{} + ts := httptest.NewServer(f.handler()) + t.Cleanup(ts.Close) + server := ts.URL + + h := newHarness(t) + code := h.run("--server", server, "runs", "start", "--repo", "https://github.com/hivecommons/hive", "--commit", strings.Repeat("a", 40), + "--env", "PATH", "--env", "LANG", "--network", "none", "--timeout", "2s", "--max-output", "64", "--idempotency-key", "k1", "--", "make", "-j2", "test") + if code != ExitOK { + t.Fatalf("start: %d %s", code, h.stderr) + } + if h.stdout.String() != "hello\n" || !strings.Contains(h.stderr.String(), "run_ok completed exit=0") || !strings.Contains(h.stderr.String(), "warned") { + t.Fatalf("start output:\nstdout=%q\nstderr=%q", h.stdout, h.stderr) + } + req := f.created[0] + if req.Worktree == nil || req.Worktree.Repo != "https://github.com/hivecommons/hive" || req.Worktree.Commit != strings.Repeat("a", 40) || + strings.Join(req.Command, " ") != "make -j2 test" || strings.Join(req.EnvAllowlist, ",") != "PATH,LANG" || + req.Network != "none" || req.TimeoutMs != 2000 || req.MaxOutputBytes != 64 || req.IdempotencyKey != "k1" || req.Detach { + t.Fatalf("request = %+v (worktree %+v)", req, req.Worktree) + } + + h = newHarness(t) + if code := h.run("--server", server, "runs", "start", "--workspace", "/srv/ws", "--detach", "--json", "--", "true"); code != ExitOK { + t.Fatalf("detach: %d %s", code, h.stderr) + } + var detached api.ContainedRun + if err := json.Unmarshal([]byte(h.stdout.String()), &detached); err != nil || detached.ID != "run_new" || detached.Status != api.RunAccepted { + t.Fatalf("detach json = %q (%v)", h.stdout, err) + } + if req := f.created[1]; req.WorkspacePath != "/srv/ws" || req.Worktree != nil || !req.Detach { + t.Fatalf("detach request = %+v", req) + } + + h = newHarness(t) + if code := h.run("--server", server, "runs", "start", "--workspace", "/srv/ws", "--profile", "agent", "--", "true"); code != ExitError || !strings.Contains(h.stderr.String(), "not available yet") { + t.Fatalf("unsupported: %d %s", code, h.stderr) + } + + for _, tc := range []struct { + id string + code int + stdout string + stderr string + }{ + {"run_ok", ExitOK, "hello\n", "run_ok completed exit=0"}, + {"run_fail", ExitError, "", "run_fail completed exit=2 (exit status 2)"}, + {"run_cut", ExitOK, "12345", "stdout truncated at byte 5"}, + {"run_lost", ExitError, "", "run_lost unfinished (pod vanished)"}, + {"run_sleep", ExitOK, "", "run_sleep running"}, + {"run_missing", ExitError, "", "run not found"}, + } { + h = newHarness(t) + if code := h.run("--server", server, "runs", "status", tc.id); code != tc.code || h.stdout.String() != tc.stdout || !strings.Contains(h.stderr.String(), tc.stderr) { + t.Fatalf("status %s: %d stdout=%q stderr=%q", tc.id, code, h.stdout, h.stderr) + } + } + h = newHarness(t) + if code := h.run("--server", server, "runs", "status", "--json", "run_cut"); code != ExitOK || !strings.Contains(h.stdout.String(), `"stderr_truncated_at": 5`) { + t.Fatalf("status json: %d %s", code, h.stdout) + } + + h = newHarness(t) + if code := h.run("--server", server, "runs", "cancel", "run_sleep"); code != ExitError || !strings.Contains(h.stderr.String(), "run_sleep cancelled") { + t.Fatalf("cancel: %d %s", code, h.stderr) + } + h = newHarness(t) + if code := h.run("--server", server, "runs", "cancel", "--json", "run_late"); code != ExitError || !strings.Contains(h.stderr.String(), "had already finished") || !strings.Contains(h.stdout.String(), `"timed_out": true`) { + t.Fatalf("late cancel: %d stdout=%s stderr=%s", code, h.stdout, h.stderr) + } + if strings.Join(f.cancelled, ",") != "run_sleep,run_late" { + t.Fatalf("cancelled = %v", f.cancelled) + } +} + +func TestRunsUsage(t *testing.T) { + t.Setenv(config.ServerEnvVar, "") + t.Setenv(config.ServeTokenEnvVar, "") + ts := httptest.NewServer((&fakeRunsAPI{}).handler()) + t.Cleanup(ts.Close) + for _, tc := range []struct { + args []string + code int + stderr string + }{ + {[]string{"runs"}, ExitUsage, "usage: crux --server ADDR runs start"}, + {[]string{"runs", "help"}, ExitOK, "usage: crux --server ADDR runs start"}, + {[]string{"runs", "bogus"}, ExitUsage, `unknown subcommand "bogus"`}, + {[]string{"runs", "start"}, ExitUsage, "usage: crux --server ADDR runs start"}, + {[]string{"runs", "start", "-h"}, ExitOK, "-repo"}, + {[]string{"runs", "start", "--bogus", "x"}, ExitUsage, "bogus"}, + {[]string{"runs", "status"}, ExitUsage, "usage: crux --server ADDR runs status"}, + {[]string{"runs", "status", "-bogus"}, ExitUsage, "bogus"}, + {[]string{"runs", "cancel", "a", "b"}, ExitUsage, "usage: crux --server ADDR runs cancel"}, + {[]string{"runs", "cancel", "-bogus"}, ExitUsage, "bogus"}, + } { + h := newHarness(t) + if code := h.run(append([]string{"--server", ts.URL}, tc.args...)...); code != tc.code || !strings.Contains(h.stderr.String(), tc.stderr) { + t.Fatalf("%v: %d %s", tc.args, code, h.stderr) + } + } +} + +func TestOpenRunsReconcilesAndLoadsTheBackend(t *testing.T) { + t.Setenv(runsConfigEnvVar, "") + h := newHarness(t) + workDir := t.TempDir() + store, err := runstate.Open(workDir) + if err != nil { + t.Fatal(err) + } + stale, _, err := store.Create(runstate.Record{}) + if err != nil { + t.Fatal(err) + } + svc, err := h.env.openRuns(workDir, "") + if err != nil { + t.Fatal(err) + } + if svc.Configured() { + t.Fatal("configured without a config file") + } + if run, err := svc.Get(stale.ID); err != nil || run.Status != api.RunUnfinished { + t.Fatalf("stale record = %+v, %v", run, err) + } + if !strings.Contains(h.stderr.String(), stale.ID+" was in flight") { + t.Fatalf("reconcile not reported: %s", h.stderr) + } + + cfgPath := writeFile(t, filepath.Join(t.TempDir(), "runs.json"), `{"image":"img","workspace_roots":["/srv"]}`) + svc, err = h.env.openRuns(workDir, cfgPath) + if err != nil || !svc.Configured() || svc.Backend.Name != runs.BackendPodman { + t.Fatalf("configured = %v, %v", svc, err) + } + t.Setenv(runsConfigEnvVar, cfgPath) + if svc, err = h.env.openRuns(workDir, ""); err != nil || !svc.Configured() { + t.Fatalf("env config = %v, %v", svc, err) + } + if _, err := h.env.openRuns(workDir, writeFile(t, filepath.Join(t.TempDir(), "bad.json"), `{"backend":"job","image":"img"}`)); err == nil { + t.Fatal("bad config accepted") + } + if _, err := h.env.openRuns(writeFile(t, filepath.Join(t.TempDir(), "file"), ""), cfgPath); err == nil { + t.Fatal("work dir under a file accepted") + } + if code := h.run("serve", "--runs-config", filepath.Join(t.TempDir(), "missing.json")); code != ExitUsage || !strings.Contains(h.stderr.String(), "crux: runs:") { + t.Fatalf("serve with a missing runs config: %d %s", code, h.stderr) + } +} diff --git a/src/crux/cli/serve.go b/src/crux/cli/serve.go index 104848eccf..f188cecc03 100644 --- a/src/crux/cli/serve.go +++ b/src/crux/cli/serve.go @@ -12,6 +12,8 @@ import ( "github.com/hivecommons/hive/crux/checkout" "github.com/hivecommons/hive/crux/config" "github.com/hivecommons/hive/crux/lanes" + "github.com/hivecommons/hive/crux/runs" + "github.com/hivecommons/hive/crux/runstate" "github.com/hivecommons/hive/crux/serve" "github.com/nats-io/nats.go" ) @@ -40,12 +42,14 @@ func (e *Env) cmdServe(ctx context.Context, opts globalOptions, args []string) i fs.StringVar(&checkoutDir, "checkout-dir", "", "where pinned checkouts live (default $"+config.CheckoutDirEnvVar+", then <workdir>/"+checkout.DirName+")") fs.StringVar(&operatorName, "operator-name", "", "name of the principal behind the control token on work-services routes (default $"+config.ServeOperatorNameEnvVar+", then "+serve.DefaultOperatorName+")") fs.StringVar(&laneConfig, "lanes-config", "", "opt-in durable lane configuration file (default $CRUX_LANES_CONFIG)") + var runsConfig string + fs.StringVar(&runsConfig, "runs-config", "", "opt-in contained-run backend configuration file (default $"+runsConfigEnvVar+")") fs.StringVar(&hiveAddr, "hive-callback", "", "hive capability endpoint to dial (default $"+callback.SocketEnvVar+"; none when unset)") if code, ok := parseSub(fs, args); !ok { return code } if fs.NArg() != 0 { - fmt.Fprintln(e.Stderr, "usage: crux serve [-socket PATH] [-listen HOST:PORT] [-token T] [-hive-callback ADDR] [-lanes-config PATH] [-operator-name NAME] [-checkout-allow PREFIXES] [-checkout-dir DIR]") + fmt.Fprintln(e.Stderr, "usage: crux serve [-socket PATH] [-listen HOST:PORT] [-token T] [-hive-callback ADDR] [-lanes-config PATH] [-operator-name NAME] [-checkout-allow PREFIXES] [-checkout-dir DIR] [-runs-config PATH]") return ExitUsage } if cfg.Token == "" { @@ -117,6 +121,12 @@ func (e *Env) cmdServe(ctx context.Context, opts globalOptions, args []string) i defer broker.Close() srv.Lanes, srv.LaneAuth = broker, auth } + runSvc, err := e.openRuns(opts.workDir, runsConfig) + if err != nil { + fmt.Fprintln(e.Stderr, "crux: runs:", err) + return ExitUsage + } + srv.Runs = runSvc if hive != nil { hive.install(ctx, rt, srv, e.Stdout) hive.watchPolicy(ctx, rt, e.Stdout, e.Stderr) @@ -148,3 +158,42 @@ func (e *Env) laneBrokerFailure(err error) int { fmt.Fprintf(e.Stderr, "crux: lanes: cannot initialize durable broker (%s)\n", category) return ExitError } + +// runsConfigEnvVar names the contained-run configuration file when +// --runs-config is not given. +const runsConfigEnvVar = "CRUX_RUNS_CONFIG" + +// openRuns builds the contained-run service. Saved records under +// <workdir>/runs are always served, so a server with no backend configured +// still answers `crux runs status`; the backend comes from the config file +// when one is named. Records left in flight by an earlier process are +// marked unfinished here, before the first request can observe them. +func (e *Env) openRuns(workDir, path string) (*runs.Service, error) { + if path == "" { + path = os.Getenv(runsConfigEnvVar) + } + var cfg runs.Config + var backend *runs.Backend + if path != "" { + var err error + if cfg, err = runs.LoadConfig(path); err != nil { + return nil, err + } + if backend, err = runs.BackendFromConfig(cfg); err != nil { + return nil, err + } + } + store, err := runstate.Open(workDir) + if err != nil { + return nil, err + } + svc := runs.New(store, backend, cfg) + reconciled, err := svc.Reconcile() + if err != nil { + return nil, err + } + for _, rec := range reconciled { + fmt.Fprintf(e.Stderr, "crux: runs: %s was in flight at the last shutdown; marked unfinished\n", rec.ID) + } + return svc, nil +} diff --git a/src/crux/cli/verbs_test.go b/src/crux/cli/verbs_test.go index 712e98ced8..aad7ebbbc3 100644 --- a/src/crux/cli/verbs_test.go +++ b/src/crux/cli/verbs_test.go @@ -14,8 +14,9 @@ import ( ) // nonRuntimeVerbs are dispatch cases that do not operate on a runtime: serve -// exposes one, help prints usage, cline-turn executes one pane-side worker. -var nonRuntimeVerbs = map[string]bool{"serve": true, "help": true, "-h": true, "--help": true, "cline-turn": true, "checkout": true} +// exposes one, help prints usage, cline-turn executes one pane-side worker, +// checkout and runs drive work services on a server. +var nonRuntimeVerbs = map[string]bool{"serve": true, "help": true, "-h": true, "--help": true, "cline-turn": true, "checkout": true, "runs": true} func TestVerbsHaveRuntimeMethods(t *testing.T) { rt := reflect.TypeOf((*crux.Runtime)(nil)).Elem() diff --git a/src/crux/config/agent_config.go b/src/crux/config/agent_config.go index 79a4481491..21520d78a8 100644 --- a/src/crux/config/agent_config.go +++ b/src/crux/config/agent_config.go @@ -135,6 +135,10 @@ type AgentRuntimeConfig struct { // recycle policy (#14842). It is encoded under agents.session_recycle by // Config's YAML hooks, like AgentsGitHubAPIHourlyCap. AgentsSessionRecycle SessionRecycleConfig `yaml:"-" json:"-"` + // AgentsCLIMemory is the fleet default for the CLI persistent-memory + // policy (hivecommons/hive#17032), encoded under agents.cli_memory by + // Config's YAML hooks, like AgentsSessionRecycle. + AgentsCLIMemory CLIMemoryConfig `yaml:"-" json:"-"` // Backends is the spoke-wide backend allow/deny list (#11310), enforced // at pack apply and by PUT /api/config/agent/{name}/models. Backends BackendsConfig `yaml:"backends,omitempty" json:"backends,omitempty"` @@ -330,8 +334,12 @@ type AgentConfig struct { // stamps the fleet block into nil pointers so the agent manager sees one // resolved policy per agent. SessionRecycle *SessionRecycleConfig `yaml:"session_recycle,omitempty" json:"session_recycle,omitempty"` - DisplayName string `yaml:"display_name" json:"display_name,omitempty"` - Description string `yaml:"description" json:"description,omitempty"` + // CLIMemory overrides the fleet agents.cli_memory policy for this agent + // (hivecommons/hive#17032). Nil inherits the fleet value, which + // EnabledAgents() stamps into nil pointers like SessionRecycle. + CLIMemory *CLIMemoryConfig `yaml:"cli_memory,omitempty" json:"cli_memory,omitempty"` + DisplayName string `yaml:"display_name" json:"display_name,omitempty"` + Description string `yaml:"description" json:"description,omitempty"` // Bob holds bob-backend-only per-agent options. Empty is default-off. Bob AgentBobConfig `yaml:"bob,omitempty" json:"bob,omitempty"` // BobDisplayName is the legacy flat spelling for Bob.SessionLabel. It is diff --git a/src/crux/config/cli_memory.go b/src/crux/config/cli_memory.go new file mode 100644 index 0000000000..79ff1547ee --- /dev/null +++ b/src/crux/config/cli_memory.go @@ -0,0 +1,46 @@ +package config + +// CLIMemoryConfig governs the persistent, cross-session "memory" the agent +// CLIs keep for themselves under the per-agent HOME (hivecommons/hive#17032): +// Claude Code's auto-memory (~/.claude/projects/<cwd>/memory/), Codex +// memories ($CODEX_HOME/memories*), Copilot CLI's agentic memory, and the +// Gemini CLI's saved ~/.gemini/GEMINI.md. It is written fleet-wide under +// agents.cli_memory and may be overridden per agent under +// agents.<name>.cli_memory. +// +// Hive agents are stateless workers driven by kick templates, beads and the +// knowledge system; a hidden per-CLI notebook that survives /clear is a +// second, unaudited memory that was observed drifting into false and stale +// "facts" (hivecommons/hive#17031). It is therefore OFF unless the operator +// opts in, and may additionally be wiped before every kick. +type CLIMemoryConfig struct { + // AutoMemory lets the CLI keep its own persistent notes across sessions. + // Nil or false pins the CLI's auto-memory feature off at launch + // (CLAUDE_CODE_DISABLE_AUTO_MEMORY=1, codex [features] memories=false, + // copilot settings.json memory=false); true leaves the CLI's own default + // (and un-pins codex/copilot). + AutoMemory *bool `yaml:"auto_memory,omitempty" json:"auto_memory,omitempty"` + // ClearOnKick wipes the agent's persistent memory store before every + // kick, alongside the /clear that resets the conversation, so each turn + // starts from the kick template and the shared knowledge system only. + ClearOnKick bool `yaml:"clear_on_kick,omitempty" json:"clear_on_kick,omitempty"` +} + +// IsZero reports whether no field was set, so an absent block encodes as +// nothing and a per-agent nil pointer inherits the fleet value. +func (c CLIMemoryConfig) IsZero() bool { + return c.AutoMemory == nil && !c.ClearOnKick +} + +// AutoMemoryEnabled reports whether the CLI may keep persistent memory. The +// receiver may be nil (no per-agent override and no fleet block): the +// default is off. +func (c *CLIMemoryConfig) AutoMemoryEnabled() bool { + return c != nil && c.AutoMemory != nil && *c.AutoMemory +} + +// ClearMemoryOnKick reports whether the memory store is wiped before each +// kick. The receiver may be nil: the default is off. +func (c *CLIMemoryConfig) ClearMemoryOnKick() bool { + return c != nil && c.ClearOnKick +} diff --git a/src/crux/cruxtest/recorder_knowledge.go b/src/crux/cruxtest/recorder_knowledge.go new file mode 100644 index 0000000000..01ed6d9085 --- /dev/null +++ b/src/crux/cruxtest/recorder_knowledge.go @@ -0,0 +1,10 @@ +package cruxtest + +import "github.com/hivecommons/hive/crux" + +// SetKnowledgeAdviser records the mid-task knowledge advisor seam +// (hivecommons/hive#17052); it lives apart from recorder.go only because that +// file sits at its size-ratchet baseline. +func (r *Recorder) SetKnowledgeAdviser(adviser crux.KnowledgeAdviser) { + r.record("SetKnowledgeAdviser", adviser != nil) +} diff --git a/src/crux/host_wiring.go b/src/crux/host_wiring.go index ff278ed0ce..227c5e3084 100644 --- a/src/crux/host_wiring.go +++ b/src/crux/host_wiring.go @@ -70,4 +70,9 @@ type Host interface { SetAuditSink(sink AuditSink) SetConditionReporter(r ConditionReporter) SetSpanStarter(fn SpanStarter) + // SetKnowledgeAdviser installs the hive-side matcher the mid-task + // knowledge advisor asks when an agent's work enters a new scope + // (hivecommons/hive#17052). In-process-only in phase 1: the knowledge + // store lives in the hive process and the adviser is a Go call into it. + SetKnowledgeAdviser(adviser KnowledgeAdviser) } diff --git a/src/crux/knowledge_advice.go b/src/crux/knowledge_advice.go new file mode 100644 index 0000000000..a7b5aa3882 --- /dev/null +++ b/src/crux/knowledge_advice.go @@ -0,0 +1,59 @@ +package crux + +import "time" + +// KnowledgeScope is one unit of work context the runtime observed an agent +// enter after its kick (hivecommons/hive#17052): a source directory it read +// or edited, or a GitHub CLI family it started using. Key is stable per +// scope and is what the runtime dedupes on within a kick. +type KnowledgeScope struct { + // Kind is "path" or "gh". + Kind string + // Key is the dedupe key: "src/crux/agent" for a path scope, "gh:pr" for + // a gh family. + Key string + // Path is the relative file path that opened a path scope; "" for gh. + Path string + // Keywords are the search terms the scope contributes to the matcher. + Keywords []string +} + +// KnowledgeAdvice is one knowledge entry the adviser matched to a scope. +// The runtime renders it as a single line typed into the live session. +type KnowledgeAdvice struct { + // Slug identifies the entry; the runtime never delivers a slug twice in + // one kick. + Slug string + // Title is the entry title. + Title string + // Summary is the body, already collapsed to one line and capped by the + // adviser. + Summary string + // Ref tells the agent where the full entry is: a source URL or the + // knowledge entry id. + Ref string +} + +// KnowledgeAdvisorPolicy is the delivery policy for one agent, resolved per +// call off the live hive config so a dashboard change applies without a +// restart. +type KnowledgeAdvisorPolicy struct { + // Enabled false means the runtime neither parses the agent's pane for + // scopes nor types anything. + Enabled bool + // MaxPerKick caps deliveries per kick; non-positive means the default. + MaxPerKick int + // Cooldown is the minimum gap between two deliveries to one agent; + // non-positive means the default. + Cooldown time.Duration +} + +// KnowledgeAdviser is the hive side of the mid-task knowledge advisor. +type KnowledgeAdviser interface { + // Policy returns the delivery policy for agent. + Policy(agent string) KnowledgeAdvisorPolicy + // Advise returns the entries worth surfacing to agent for a scope it has + // just entered, excluding anything its kick already carried. Order is + // best first. It runs on the agent's poll goroutine and must be bounded. + Advise(agent string, scope KnowledgeScope) []KnowledgeAdvice +} diff --git a/src/crux/kubejob/kubejob.go b/src/crux/kubejob/kubejob.go index d930cadfdd..42d4b6a9fd 100644 --- a/src/crux/kubejob/kubejob.go +++ b/src/crux/kubejob/kubejob.go @@ -225,45 +225,50 @@ func (l *Launcher) Run(ctx context.Context, spec sandbox.LaunchSpec) (sandbox.Re done, waitErr := l.wait(ctx, jobPath) // Collect whatever the pod produced BEFORE deciding anything: a timed-out // or failed kick with no transcript is the worst outcome for an operator. - // After a timeout the caller's ctx is already dead, so the collection and - // the cleanup below run on a fresh, request-bounded context. - collectCtx := ctx - if ctx.Err() != nil { - var cancel context.CancelFunc - collectCtx, cancel = context.WithTimeout(context.Background(), requestTimeout) - defer cancel() - } - pod, podErr := l.findPod(collectCtx, ns, name) + // The caller's ctx may be dead already (kick timeout) or die between any + // two of these requests (cancel during log collection), so every step + // re-checks it and falls back to a fresh, request-bounded context. + // Otherwise a readable, Complete pod would report exitCodeUnknown merely + // because ctx was cancelled after the log was read. + var cancels []context.CancelFunc + defer func() { + for _, c := range cancels { + c() + } + }() + live := func() context.Context { + if ctx.Err() == nil { + return ctx + } + fresh, cancel := context.WithTimeout(context.Background(), requestTimeout) + cancels = append(cancels, cancel) + return fresh + } + pod, podErr := l.findPod(live(), ns, name) if podErr == nil && pod != "" { - res.Stdout = l.podLog(collectCtx, ns, pod) - res.ExitCode = l.podExitCode(collectCtx, ns, pod) + res.Stdout = l.podLog(live(), ns, pod) + res.ExitCode = l.podExitCode(live(), ns, pod) } else { res.ExitCode = exitCodeUnknown } if waitErr != nil { // Context ended (kick timeout or cancel). The Job would otherwise // keep running the workload on the accelerator node; stop it. - _ = l.delete(collectCtx, jobPath) + _ = l.delete(live(), jobPath) return res, waitErr } if !done.succeeded { res.Stderr = done.reason return res, fmt.Errorf("kubejob: job %s failed: %s", name, done.reason) } - if res.ExitCode == exitCodeUnknown { - // The Job reports Complete, so the container exited 0 even though the - // pod could not be read back (already GC'd, or RBAC on pods missing). - res.ExitCode = 0 - } - // Collection may have expired the context even on success; use a fresh one - // for cleanup to ensure the finished Job is immediately removed. - deleteCtx := ctx - if ctx.Err() != nil { - var cancel context.CancelFunc - deleteCtx, cancel = context.WithTimeout(context.Background(), requestTimeout) - defer cancel() - } - _ = l.delete(deleteCtx, jobPath) + // When the Job reports Complete but the pod could not be read back + // (already GC'd, or RBAC on pods missing), res.ExitCode stays + // exitCodeUnknown rather than a guessed 0; callers treat a nil error with + // an unknown code as completed-without-code. + // + // Collection may have expired the context even on success; the fresh + // context ensures the finished Job is still removed immediately. + _ = l.delete(live(), jobPath) return res, nil } @@ -454,6 +459,13 @@ func (l *Launcher) manifest(ns, name, subPath string, spec sandbox.LaunchSpec) m } container := map[string]any{ + // The workspace PVC and the agent's home need to stay writable, so the + // root filesystem is deliberately not made read-only. + "securityContext": map[string]any{ + "allowPrivilegeEscalation": false, + "capabilities": map[string]any{"drop": []string{"ALL"}}, + "seccompProfile": map[string]string{"type": "RuntimeDefault"}, + }, "name": containerName, "image": spec.Image, "workingDir": workdir, @@ -471,6 +483,12 @@ func (l *Launcher) manifest(ns, name, subPath string, spec sandbox.LaunchSpec) m "restartPolicy": restartNever, "containers": []map[string]any{container}, "volumes": volumes, + // Nothing in the kick pod calls the Kubernetes API, so the SA token is + // never mounted into a contained run. + "automountServiceAccountToken": false, + "securityContext": map[string]any{ + "seccompProfile": map[string]string{"type": "RuntimeDefault"}, + }, } if len(l.Options.NodeSelector) > 0 { podSpec["nodeSelector"] = l.Options.NodeSelector diff --git a/src/crux/kubejob/kubejob_test.go b/src/crux/kubejob/kubejob_test.go index bd885d22d0..51f0488e07 100644 --- a/src/crux/kubejob/kubejob_test.go +++ b/src/crux/kubejob/kubejob_test.go @@ -219,7 +219,7 @@ func TestRunContextTimeoutDeletesTheJob(t *testing.T) { } } -func TestRunCompleteWithNoPodStillSucceeds(t *testing.T) { +func TestRunCompleteWithNoPodKeepsExitCodeUnknown(t *testing.T) { api := newFakeAPI() api.statuses = []string{statusComplete} api.noPod = true @@ -230,8 +230,8 @@ func TestRunCompleteWithNoPodStillSucceeds(t *testing.T) { if err != nil { t.Fatalf("Run: %v", err) } - if res.ExitCode != 0 || res.Stdout != "" { - t.Errorf("result = %+v, want exit 0 (Complete) and no log", res) + if res.ExitCode != exitCodeUnknown || res.Stdout != "" { + t.Errorf("result = %+v, want unknown exit code (Complete, pod unreadable) and no log", res) } } @@ -359,6 +359,10 @@ func TestManifestShape(t *testing.T) { `"tolerations":[{"effect":"NoSchedule","key":"spyre","operator":"Exists"}]`, `"limits":{"ibm.com/spyre_pf":"2"}`, `"serviceAccountName":"hive"`, + `"automountServiceAccountToken":false`, + `"allowPrivilegeEscalation":false`, + `"capabilities":{"drop":["ALL"]}`, + `"seccompProfile":{"type":"RuntimeDefault"}`, `"envFrom":[{"secretRef":{"name":"artifact-registry"}}]`, `"claimName":"hive-data"`, `"subPath":"agents/sandbox/deps-123"`, diff --git a/src/crux/runs/backend.go b/src/crux/runs/backend.go new file mode 100644 index 0000000000..8b2aea2a57 --- /dev/null +++ b/src/crux/runs/backend.go @@ -0,0 +1,118 @@ +package runs + +import ( + "context" + "fmt" + "os/exec" + "strings" + + "github.com/hivecommons/hive/crux/config" + "github.com/hivecommons/hive/crux/kubejob" + "github.com/hivecommons/hive/crux/sandbox" +) + +// Capabilities is what a backend can enforce. A request for anything it +// cannot is refused before the run starts. +type Capabilities struct { + NetworkNone bool + NetworkRestricted bool +} + +// Backend pairs a sandbox.Launcher with its capabilities and the teardown +// that guarantees a cancelled or timed-out run leaves nothing behind. +type Backend struct { + Name string + Launcher sandbox.Launcher + Capabilities Capabilities + // Teardown, when set, is run after a cancel or timeout with the launch + // name. The podman launcher's client process dies with the context but + // the container it started does not, so podman removes it here; the + // Job launcher deletes its Job itself (propagationPolicy Background) + // and leaves Teardown nil. + Teardown func(ctx context.Context, name string) error +} + +// Supports reports whether the backend can enforce network mode mode; the +// returned string names what is missing when it cannot. +func (b Backend) Supports(network string) (string, bool) { + switch network { + case sandbox.NetworkModeNone: + if !b.Capabilities.NetworkNone { + return fmt.Sprintf("backend %s cannot enforce network %q", b.Name, network), false + } + case sandbox.NetworkModeRestricted: + if !b.Capabilities.NetworkRestricted { + return fmt.Sprintf("backend %s cannot enforce network %q", b.Name, network), false + } + default: + return fmt.Sprintf("unknown network mode %q", network), false + } + return "", true +} + +// BackendFromConfig selects and builds the backend cfg names. +func BackendFromConfig(cfg Config) (*Backend, error) { + switch cfg.Backend { + case BackendPodman: + bin := cfg.PodmanBinary + if bin == "" { + bin = sandbox.PodmanBinary + } + return &Backend{ + Name: BackendPodman, + Launcher: sandbox.PodmanLauncher{Binary: bin}, + Capabilities: Capabilities{NetworkNone: true, NetworkRestricted: cfg.NetworkRestricted}, + Teardown: podmanTeardown(bin), + }, nil + case BackendJob: + if cfg.Job == nil { + return nil, fmt.Errorf("%w: backend %q needs a job block", ErrConfig, BackendJob) + } + opts := jobOptions(*cfg.Job) + if err := opts.Validate(); err != nil { + return nil, fmt.Errorf("%w: %v", ErrConfig, err) + } + return &Backend{ + Name: BackendJob, + Launcher: &kubejob.Launcher{Options: opts}, + // The Job manifest carries no network mode; only an operator's + // NetworkPolicy can enforce one, and only "none" is claimable. + Capabilities: Capabilities{NetworkNone: cfg.JobNetworkPolicy}, + }, nil + } + return nil, fmt.Errorf("%w: unknown backend %q", ErrConfig, cfg.Backend) +} + +// podmanTeardown removes the named container whether or not it is still +// running; --ignore makes an already-removed container a success. +func podmanTeardown(bin string) func(context.Context, string) error { + return func(ctx context.Context, name string) error { + out, err := exec.CommandContext(ctx, bin, "rm", "--force", "--ignore", name).CombinedOutput() + if err != nil { + return fmt.Errorf("podman rm %s: %w: %s", name, err, strings.TrimSpace(string(out))) + } + return nil + } +} + +// jobOptions mirrors the agent sandbox's config-to-launcher mapping +// (agent.JobOptionsFromConfig) without importing the agent manager. +func jobOptions(job config.SandboxJobConfig) kubejob.Options { + opts := kubejob.Options{ + WorkspaceClaim: job.WorkspaceClaim, + WorkspaceClaimMount: job.WorkspaceClaimMount, + NodeSelector: job.NodeSelector, + ServiceAccount: job.ServiceAccount, + SchedulerName: job.SchedulerName, + EnvFromSecrets: job.EnvFromSecrets, + TTLSeconds: job.TTLSeconds, + Resources: kubejob.Resources{Limits: job.Resources.Limits, Requests: job.Resources.Requests}, + } + for _, t := range job.Tolerations { + opts.Tolerations = append(opts.Tolerations, kubejob.Toleration{Key: t.Key, Operator: t.Operator, Value: t.Value, Effect: t.Effect}) + } + for _, v := range job.Volumes { + opts.ExtraVolumes = append(opts.ExtraVolumes, kubejob.VolumeMount{Name: v.Name, Claim: v.Claim, MountPath: v.MountPath, ReadOnly: v.ReadOnly}) + } + return opts +} diff --git a/src/crux/runs/config.go b/src/crux/runs/config.go new file mode 100644 index 0000000000..92040ba151 --- /dev/null +++ b/src/crux/runs/config.go @@ -0,0 +1,159 @@ +// Package runs is the contained-run service of the Crux work services (S2 +// in hivecommons/crux#114): run a command the caller does not trust in a +// sandbox with no network and no credentials, bounded in time and output, +// and report the real exit code — or, when the exit is not knowable, say +// so. Records live in runstate (S7) so a caller that lost its connection +// can ask again by ID. +// +// sandbox.Launcher is the execution seam; Backend pairs a launcher with +// what it can enforce. A request for a limit the selected backend cannot +// enforce is refused with an *UnsupportedError, never run weakened. +package runs + +import ( + "bytes" + "encoding/json" + "errors" + "fmt" + "io" + "os" + "strings" + "time" + + "github.com/hivecommons/hive/crux/config" +) + +// Backend names, Config.Backend. +const ( + BackendPodman = "podman" + BackendJob = "job" +) + +// Limits and defaults. +const ( + DefaultTimeout = 10 * time.Minute + DefaultMaxTimeout = 2 * time.Hour + DefaultMaxOutputBytes = 1 << 20 + // DefaultMaxOutputCap bounds what a caller may ask for; the full output + // is kept as an artifact regardless, so the cap protects the response + // and the record, not the evidence. + DefaultMaxOutputCap = 64 << 20 + maxConfigBytes = 1 << 20 + // TeardownTimeout bounds the container removal after a cancel or + // timeout, run on its own context because the run's is already dead. + TeardownTimeout = 30 * time.Second +) + +// ErrConfig wraps every configuration error. +var ErrConfig = errors.New("runs: invalid configuration") + +// Config is the operator's choice of backend and bounds, loaded by +// LoadConfig from the JSON file `crux serve --runs-config` names. +// Selection is configuration, not per request. +type Config struct { + // Backend is BackendPodman (default) or BackendJob. + Backend string `json:"backend,omitempty"` + // Image is the container image every run uses. Required. + Image string `json:"image"` + // PodmanBinary overrides the podman executable (tests). + PodmanBinary string `json:"podman_binary,omitempty"` + // Job holds the Kubernetes Job settings when Backend is BackendJob; + // the same shape as the agent sandbox's job block. + Job *config.SandboxJobConfig `json:"job,omitempty"` + // JobNetworkPolicy is the operator's assertion that a NetworkPolicy in + // the Job namespace denies egress for pods labelled + // app.kubernetes.io/managed-by=hive-kubejob. The Job launcher cannot + // set a network mode itself, so without this assertion a request for + // network "none" on the job backend is refused. + JobNetworkPolicy bool `json:"job_network_policy,omitempty"` + // NetworkRestricted is the operator's assertion that a container + // network named "restricted" exists on the podman host; without it a + // request for network "restricted" is refused. + NetworkRestricted bool `json:"network_restricted,omitempty"` + // RepoAllowlist is the set of repository URL prefixes the ad-hoc + // worktree form may clone. Empty refuses every worktree request. + RepoAllowlist []string `json:"repo_allowlist,omitempty"` + // WorkspaceRoots is the set of host directories a plain workspace_path + // may lie under. Empty refuses every workspace_path request. + WorkspaceRoots []string `json:"workspace_roots,omitempty"` + // DefaultTimeoutMs and MaxTimeoutMs bound timeout_ms; zero takes the + // package defaults. + DefaultTimeoutMs int64 `json:"default_timeout_ms,omitempty"` + MaxTimeoutMs int64 `json:"max_timeout_ms,omitempty"` + // DefaultMaxOutputBytes and MaxOutputBytesCap bound max_output_bytes; + // zero takes the package defaults. + DefaultMaxOutputBytes int64 `json:"default_max_output_bytes,omitempty"` + MaxOutputBytesCap int64 `json:"max_output_bytes_cap,omitempty"` +} + +// LoadConfig reads and validates the JSON configuration at path. +func LoadConfig(path string) (Config, error) { + f, err := os.Open(path) + if err != nil { + return Config{}, fmt.Errorf("%w: %v", ErrConfig, err) + } + defer f.Close() + return loadConfig(f) +} + +func loadConfig(r io.Reader) (Config, error) { + data, err := io.ReadAll(io.LimitReader(r, maxConfigBytes+1)) + if err != nil || len(data) > maxConfigBytes { + return Config{}, fmt.Errorf("%w: configuration size", ErrConfig) + } + d := json.NewDecoder(bytes.NewReader(data)) + d.DisallowUnknownFields() + var cfg Config + if err := d.Decode(&cfg); err != nil { + return Config{}, fmt.Errorf("%w: %v", ErrConfig, err) + } + cfg.Defaults() + return cfg, cfg.Validate() +} + +// Defaults fills the zero fields. +func (c *Config) Defaults() { + if c.Backend == "" { + c.Backend = BackendPodman + } + if c.DefaultTimeoutMs <= 0 { + c.DefaultTimeoutMs = DefaultTimeout.Milliseconds() + } + if c.MaxTimeoutMs <= 0 { + c.MaxTimeoutMs = DefaultMaxTimeout.Milliseconds() + } + if c.DefaultMaxOutputBytes <= 0 { + c.DefaultMaxOutputBytes = DefaultMaxOutputBytes + } + if c.MaxOutputBytesCap <= 0 { + c.MaxOutputBytesCap = DefaultMaxOutputCap + } +} + +// Validate reports the errors that would otherwise surface as a failed run. +func (c Config) Validate() error { + if strings.TrimSpace(c.Image) == "" { + return fmt.Errorf("%w: image is required", ErrConfig) + } + switch c.Backend { + case BackendPodman: + case BackendJob: + if c.Job == nil { + return fmt.Errorf("%w: backend %q needs a job block", ErrConfig, BackendJob) + } + default: + return fmt.Errorf("%w: backend must be %q or %q", ErrConfig, BackendPodman, BackendJob) + } + if c.DefaultTimeoutMs > c.MaxTimeoutMs { + return fmt.Errorf("%w: default_timeout_ms exceeds max_timeout_ms", ErrConfig) + } + if c.DefaultMaxOutputBytes > c.MaxOutputBytesCap { + return fmt.Errorf("%w: default_max_output_bytes exceeds max_output_bytes_cap", ErrConfig) + } + for _, root := range c.WorkspaceRoots { + if !strings.HasPrefix(root, "/") { + return fmt.Errorf("%w: workspace_roots entries must be absolute: %q", ErrConfig, root) + } + } + return nil +} diff --git a/src/crux/runs/config_test.go b/src/crux/runs/config_test.go new file mode 100644 index 0000000000..0298fecbc7 --- /dev/null +++ b/src/crux/runs/config_test.go @@ -0,0 +1,244 @@ +package runs + +import ( + "context" + "errors" + "os" + "os/exec" + "path/filepath" + "strings" + "testing" + + "github.com/hivecommons/hive/crux/api" + "github.com/hivecommons/hive/crux/config" + "github.com/hivecommons/hive/crux/kubejob" + "github.com/hivecommons/hive/crux/sandbox" +) + +func TestLoadConfig(t *testing.T) { + cases := []struct { + name string + body string + err string + }{ + {"podman defaults", `{"image":"img"}`, ""}, + {"job", `{"backend":"job","image":"img","job":{"workspace_claim":"pvc"}}`, ""}, + {"unknown field", `{"image":"img","bogus":1}`, "bogus"}, + {"no image", `{"backend":"podman"}`, "image is required"}, + {"bad backend", `{"backend":"docker","image":"img"}`, "backend must be"}, + {"job without block", `{"backend":"job","image":"img"}`, "needs a job block"}, + {"timeout order", `{"image":"img","default_timeout_ms":5,"max_timeout_ms":1}`, "default_timeout_ms exceeds"}, + {"output order", `{"image":"img","default_max_output_bytes":5,"max_output_bytes_cap":1}`, "default_max_output_bytes exceeds"}, + {"relative root", `{"image":"img","workspace_roots":["ws"]}`, "must be absolute"}, + {"too big", `{"image":"` + strings.Repeat("x", maxConfigBytes) + `"}`, "configuration size"}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + cfg, err := loadConfig(strings.NewReader(tc.body)) + if tc.err == "" { + if err != nil { + t.Fatal(err) + } + if cfg.DefaultTimeoutMs != DefaultTimeout.Milliseconds() || cfg.MaxOutputBytesCap != DefaultMaxOutputCap { + t.Fatalf("defaults not applied: %+v", cfg) + } + return + } + if err == nil || !errors.Is(err, ErrConfig) || !strings.Contains(err.Error(), tc.err) { + t.Fatalf("err = %v, want %q", err, tc.err) + } + }) + } + path := filepath.Join(t.TempDir(), "runs.json") + if err := os.WriteFile(path, []byte(`{"image":"img","repo_allowlist":["https://github.com/"]}`), 0o600); err != nil { + t.Fatal(err) + } + cfg, err := LoadConfig(path) + if err != nil || cfg.Backend != BackendPodman || len(cfg.RepoAllowlist) != 1 { + t.Fatalf("LoadConfig = %+v, %v", cfg, err) + } + if _, err := LoadConfig(filepath.Join(t.TempDir(), "missing.json")); !errors.Is(err, ErrConfig) { + t.Fatalf("missing file = %v", err) + } +} + +func TestBackendFromConfig(t *testing.T) { + podman, err := BackendFromConfig(Config{Backend: BackendPodman, Image: "img"}) + if err != nil { + t.Fatal(err) + } + if podman.Name != BackendPodman || podman.Teardown == nil { + t.Fatalf("podman = %+v", podman) + } + if l, ok := podman.Launcher.(sandbox.PodmanLauncher); !ok || l.Binary != sandbox.PodmanBinary { + t.Fatalf("launcher = %#v", podman.Launcher) + } + if _, ok := podman.Supports(api.RunNetworkNone); !ok { + t.Fatal("podman cannot do network none") + } + if what, ok := podman.Supports(api.RunNetworkRestricted); ok || !strings.Contains(what, `"restricted"`) { + t.Fatalf("restricted without the flag: %q %v", what, ok) + } + if what, ok := podman.Supports("bridge"); ok || !strings.Contains(what, "unknown network mode") { + t.Fatalf("unknown mode: %q %v", what, ok) + } + restricted, _ := BackendFromConfig(Config{Backend: BackendPodman, Image: "img", NetworkRestricted: true, PodmanBinary: "/opt/podman"}) + if _, ok := restricted.Supports(api.RunNetworkRestricted); !ok { + t.Fatal("restricted flag ignored") + } + if l := restricted.Launcher.(sandbox.PodmanLauncher); l.Binary != "/opt/podman" { + t.Fatalf("binary override = %q", l.Binary) + } + + job := &config.SandboxJobConfig{WorkspaceClaim: "pvc", TTLSeconds: 60} + job.Tolerations = []config.SandboxJobToleration{{Key: "k", Operator: "Exists", Effect: "NoSchedule"}} + job.Volumes = []config.SandboxJobVolume{{Name: "cache", Claim: "c", MountPath: "/cache", ReadOnly: true}} + kube, err := BackendFromConfig(Config{Backend: BackendJob, Image: "img", Job: job}) + if err != nil { + t.Fatal(err) + } + if kube.Teardown != nil || kube.Name != BackendJob { + t.Fatalf("job backend = %+v", kube) + } + if what, ok := kube.Supports(api.RunNetworkNone); ok || !strings.Contains(what, `cannot enforce network "none"`) { + t.Fatalf("job none without a policy: %q %v", what, ok) + } + opts := kube.Launcher.(*kubejob.Launcher).Options + if opts.WorkspaceClaim != "pvc" || opts.TTLSeconds != 60 || len(opts.Tolerations) != 1 || opts.Tolerations[0].Key != "k" || + len(opts.ExtraVolumes) != 1 || opts.ExtraVolumes[0].MountPath != "/cache" || !opts.ExtraVolumes[0].ReadOnly { + t.Fatalf("job options = %+v", opts) + } + policy, _ := BackendFromConfig(Config{Backend: BackendJob, Image: "img", Job: job, JobNetworkPolicy: true}) + if _, ok := policy.Supports(api.RunNetworkNone); !ok { + t.Fatal("job_network_policy ignored") + } + if _, ok := policy.Supports(api.RunNetworkRestricted); ok { + t.Fatal("job claims restricted") + } + + for name, cfg := range map[string]Config{ + "job without block": {Backend: BackendJob, Image: "img"}, + "job invalid": {Backend: BackendJob, Image: "img", Job: &config.SandboxJobConfig{}}, + "unknown": {Backend: "docker", Image: "img"}, + } { + if _, err := BackendFromConfig(cfg); !errors.Is(err, ErrConfig) { + t.Errorf("%s: err = %v", name, err) + } + } +} + +func TestPodmanTeardownReportsFailures(t *testing.T) { + for _, bin := range []string{"true", "false"} { + if _, err := exec.LookPath(bin); err != nil { + t.Skipf("%s not on PATH", bin) + } + } + if err := podmanTeardown("true")(context.Background(), "crux-run-x"); err != nil { + t.Fatalf("true: %v", err) + } + err := podmanTeardown("false")(context.Background(), "crux-run-x") + if err == nil || !strings.Contains(err.Error(), "podman rm crux-run-x") { + t.Fatalf("false: %v", err) + } +} + +func TestGitProvisionerWithARecordedRunner(t *testing.T) { + dir := t.TempDir() + var calls [][]string + runner := func(_ context.Context, cwd, name string, args ...string) ([]byte, error) { + calls = append(calls, append([]string{filepath.Base(cwd), name}, args...)) + if args[0] == "rev-parse" { + return []byte(testSHA + "\n"), nil + } + return nil, nil + } + wt := api.ContainedRunWorktree{Repo: "https://github.com/hivecommons/hive", Commit: testSHA} + path, err := GitProvisioner{Run: runner}.Provision(context.Background(), dir, wt) + if err != nil || path != filepath.Join(dir, WorkspaceDirName) { + t.Fatalf("Provision = %q, %v", path, err) + } + want := [][]string{ + {filepath.Base(dir), "git", "clone", "--no-checkout", "--", wt.Repo, path}, + {WorkspaceDirName, "git", "checkout", "--detach", testSHA}, + {WorkspaceDirName, "git", "rev-parse", "HEAD"}, + } + if len(calls) != len(want) { + t.Fatalf("calls = %v", calls) + } + for i := range want { + if strings.Join(calls[i], " ") != strings.Join(want[i], " ") { + t.Fatalf("call %d = %v, want %v", i, calls[i], want[i]) + } + } + + failing := func(step string, out string) Runner { + return func(_ context.Context, _, _ string, args ...string) ([]byte, error) { + if args[0] == step { + return []byte(out), errors.New("exit 128") + } + if args[0] == "rev-parse" { + return []byte("deadbeef\n"), nil + } + return nil, nil + } + } + for _, tc := range []struct{ step, want string }{ + {"clone", "git clone: exit 128: not found"}, + {"checkout", "git checkout " + testSHA + ": exit 128: not found"}, + {"rev-parse", "git rev-parse HEAD: exit 128"}, + {"none", "checkout pinned " + testSHA + " but HEAD is deadbeef"}, + } { + if _, err := (GitProvisioner{Run: failing(tc.step, "not found")}).Provision(context.Background(), t.TempDir(), wt); err == nil || err.Error() != tc.want { + t.Errorf("%s: err = %v, want %q", tc.step, err, tc.want) + } + } + if _, err := (GitProvisioner{Run: runner}).Provision(context.Background(), filepath.Join(writeTempFile(t), "sub"), wt); err == nil { + t.Fatal("mkdir under a file succeeded") + } +} + +func TestGitProvisionerClonesALocalRepository(t *testing.T) { + if _, err := exec.LookPath("git"); err != nil { + t.Skip("git not on PATH") + } + src := t.TempDir() + git := func(args ...string) string { + t.Helper() + cmd := exec.Command("git", args...) + cmd.Dir = src + cmd.Env = append(os.Environ(), "GIT_AUTHOR_NAME=t", "GIT_AUTHOR_EMAIL=t@x", "GIT_COMMITTER_NAME=t", "GIT_COMMITTER_EMAIL=t@x") + out, err := cmd.CombinedOutput() + if err != nil { + t.Fatalf("git %v: %v: %s", args, err, out) + } + return strings.TrimSpace(string(out)) + } + git("init", "-q", "-b", "main") + if err := os.WriteFile(filepath.Join(src, "f"), []byte("1"), 0o644); err != nil { + t.Fatal(err) + } + git("add", "f") + git("commit", "-q", "-m", "one") + sha := git("rev-parse", "HEAD") + + dir := t.TempDir() + path, err := GitProvisioner{}.Provision(context.Background(), dir, api.ContainedRunWorktree{Repo: src, Commit: sha}) + if err != nil { + t.Fatal(err) + } + if b, err := os.ReadFile(filepath.Join(path, "f")); err != nil || string(b) != "1" { + t.Fatalf("checked-out file = %q, %v", b, err) + } + if _, err := (GitProvisioner{}).Provision(context.Background(), t.TempDir(), api.ContainedRunWorktree{Repo: src, Commit: testSHA}); err == nil || !strings.Contains(err.Error(), "git checkout") { + t.Fatalf("unknown commit = %v", err) + } +} + +func writeTempFile(t *testing.T) string { + t.Helper() + path := filepath.Join(t.TempDir(), "file") + if err := os.WriteFile(path, nil, 0o600); err != nil { + t.Fatal(err) + } + return path +} diff --git a/src/crux/runs/provision.go b/src/crux/runs/provision.go new file mode 100644 index 0000000000..9c8780a8a7 --- /dev/null +++ b/src/crux/runs/provision.go @@ -0,0 +1,78 @@ +package runs + +import ( + "context" + "fmt" + "os" + "os/exec" + "path/filepath" + "strings" + + "github.com/hivecommons/hive/crux/api" + "github.com/hivecommons/hive/crux/sandbox" +) + +// gitEnvAllowlist is what the clone may see of the service's environment. +var gitEnvAllowlist = []string{"PATH", "HOME", "LANG", "LC_ALL", "TMPDIR", "SSL_CERT_FILE", "SSL_CERT_DIR"} + +// WorkspaceDirName is the workspace subdirectory of a run's directory when +// the ad-hoc worktree form provisions one. +const WorkspaceDirName = "workspace" + +// Provisioner materialises the ad-hoc worktree form under dir and returns +// the workspace path. It is the stand-in for the checkout service (S1): +// when that lands, the service delegates to it and worktrees get an owner, +// a size cap and a TTL. +type Provisioner interface { + Provision(ctx context.Context, dir string, wt api.ContainedRunWorktree) (string, error) +} + +// Runner executes one command in dir and returns its combined output; the +// default runs it, tests substitute a script. +type Runner func(ctx context.Context, dir, name string, args ...string) ([]byte, error) + +// GitProvisioner clones the repository with git and pins the commit. +type GitProvisioner struct { + Run Runner +} + +// Provision clones wt.Repo into dir/workspace with every ref, detaches at +// wt.Commit and verifies HEAD is that commit. No credential reaches git: +// the environment is the service's and the repository must be public. +func (p GitProvisioner) Provision(ctx context.Context, dir string, wt api.ContainedRunWorktree) (string, error) { + path := filepath.Join(dir, WorkspaceDirName) + if err := os.MkdirAll(dir, 0o770); err != nil { + return "", err + } + run := p.Run + if run == nil { + run = execRunner + } + if out, err := run(ctx, dir, "git", "clone", "--no-checkout", "--", wt.Repo, path); err != nil { + return "", fmt.Errorf("git clone: %w: %s", err, strings.TrimSpace(string(out))) + } + if out, err := run(ctx, path, "git", "checkout", "--detach", wt.Commit); err != nil { + _ = os.RemoveAll(path) + return "", fmt.Errorf("git checkout %s: %w: %s", wt.Commit, err, strings.TrimSpace(string(out))) + } + head, err := run(ctx, path, "git", "rev-parse", "HEAD") + if err != nil { + _ = os.RemoveAll(path) + return "", fmt.Errorf("git rev-parse HEAD: %w", err) + } + if got := strings.TrimSpace(string(head)); got != wt.Commit { + _ = os.RemoveAll(path) + return "", fmt.Errorf("checkout pinned %s but HEAD is %s", wt.Commit, got) + } + return path, nil +} + +func execRunner(ctx context.Context, dir, name string, args ...string) ([]byte, error) { + cmd := exec.CommandContext(ctx, name, args...) + cmd.Dir = dir + // Never prompt and never carry a credential: the ad-hoc form is for + // public repositories on the allowlist, so git gets the sandbox's + // credential-free environment plus a no-prompt switch. + cmd.Env = append(sandbox.SanitizedEnv(os.Environ(), gitEnvAllowlist, nil), "GIT_TERMINAL_PROMPT=0") + return cmd.CombinedOutput() +} diff --git a/src/crux/runs/service.go b/src/crux/runs/service.go new file mode 100644 index 0000000000..29db74e01b --- /dev/null +++ b/src/crux/runs/service.go @@ -0,0 +1,494 @@ +package runs + +import ( + "context" + "encoding/json" + "errors" + "fmt" + "os" + "path/filepath" + "regexp" + "strings" + "sync" + "time" + + "github.com/hivecommons/hive/crux/api" + "github.com/hivecommons/hive/crux/logscrub" + "github.com/hivecommons/hive/crux/runstate" + "github.com/hivecommons/hive/crux/sandbox" +) + +// Artifact names inside a run's directory: the full scrubbed output. +const ( + StdoutArtifact = "stdout.txt" + StderrArtifact = "stderr.txt" + // launchNamePrefix names the container/Job after the run so a teardown + // can find it. + launchNamePrefix = "crux-run-" + // ReconcileReason is recorded on runs that were in flight when the + // serving process stopped. + ReconcileReason = "crux serve restarted while the run was in flight; the exit is not knowable" + // exitUnknown is the launcher convention for "exit not read". + exitUnknown = -1 +) + +// Typed errors. The serve routes map each onto an api.Code*. +var ( + // ErrNotConfigured: the server has no backend; records are still readable. + ErrNotConfigured = errors.New("runs: no contained-run backend is configured on this server") + // ErrNotFound: unknown run ID. + ErrNotFound = runstate.ErrNotFound +) + +// RequestError is a malformed request (400). +type RequestError struct{ Msg string } + +func (e *RequestError) Error() string { return e.Msg } + +// ForbiddenError is a workspace the configuration does not allow (403). +type ForbiddenError struct{ Msg string } + +func (e *ForbiddenError) Error() string { return e.Msg } + +// UnsupportedError names a requested feature or limit the selected backend +// cannot enforce (501). The run never starts. +type UnsupportedError struct{ What string } + +func (e *UnsupportedError) Error() string { return e.What } + +var fullSHA = regexp.MustCompile(`^[0-9a-f]{40}$`) + +// detail is the service's payload inside the runstate record. +type detail struct { + Profile string `json:"profile"` + Network string `json:"network"` + Backend string `json:"backend"` + Command []string `json:"command"` + Workspace string `json:"workspace,omitempty"` + ExitCode *int `json:"exit_code,omitempty"` + TimedOut bool `json:"timed_out,omitempty"` + Stdout string `json:"stdout,omitempty"` + Stderr string `json:"stderr,omitempty"` + StdoutTruncatedAt *int64 `json:"stdout_truncated_at,omitempty"` + StderrTruncatedAt *int64 `json:"stderr_truncated_at,omitempty"` +} + +// plan is a validated request. +type plan struct { + worktree *api.ContainedRunWorktree + workspace string + command []string + allowlist []string + network string + timeout time.Duration + maxOutput int64 + profile string +} + +type active struct { + cancel context.CancelFunc + done chan struct{} + cancelled bool +} + +// Service accepts, executes, cancels and reports contained runs. +type Service struct { + Store *runstate.Store + Backend *Backend + Config Config + // Provisioner materialises the ad-hoc worktree form; nil uses git. + Provisioner Provisioner + // Environ supplies the base environment the allowlist filters; nil uses + // os.Environ. + Environ func() []string + // Scrub redacts output before it is persisted; nil uses logscrub. + Scrub func(string) string + + mu sync.Mutex + active map[string]*active +} + +// New returns a Service over store. backend nil means not configured: the +// saved records stay readable and every create answers ErrNotConfigured. +func New(store *runstate.Store, backend *Backend, cfg Config) *Service { + cfg.Defaults() + return &Service{Store: store, Backend: backend, Config: cfg, active: map[string]*active{}} +} + +// Configured reports whether runs can be executed here. +func (s *Service) Configured() bool { return s.Backend != nil } + +// Reconcile marks every run left accepted or running by a previous process +// unfinished. Call it once at serve start, before accepting requests. +func (s *Service) Reconcile() ([]runstate.Record, error) { + return s.Store.Reconcile(ReconcileReason) +} + +// Create validates req, saves the accepted record and starts the run under +// launchCtx (which must outlive the request). created is false when +// req.IdempotencyKey matched an existing run, whose record is returned. +func (s *Service) Create(launchCtx context.Context, owner string, req api.ContainedRunRequest) (api.ContainedRun, bool, error) { + if !s.Configured() { + return api.ContainedRun{}, false, ErrNotConfigured + } + p, err := s.validate(req) + if err != nil { + return api.ContainedRun{}, false, err + } + d := detail{Profile: p.profile, Network: p.network, Backend: s.Backend.Name, Command: p.command, Workspace: p.workspace} + raw, err := json.Marshal(d) + if err != nil { + return api.ContainedRun{}, false, err + } + rec, created, err := s.Store.Create(runstate.Record{ + Kind: runstate.KindRun, + Owner: owner, + IdempotencyKey: runstate.DeriveIdempotencyKey(owner, req.IdempotencyKey), + Detail: raw, + }) + if err != nil { + return api.ContainedRun{}, false, err + } + if !created { + return toWire(rec), false, nil + } + ctx, cancel := context.WithCancel(launchCtx) + a := &active{cancel: cancel, done: make(chan struct{})} + s.mu.Lock() + s.active[rec.ID] = a + s.mu.Unlock() + go s.execute(ctx, rec.ID, p, a) + return toWire(rec), true, nil +} + +// Get returns the saved record whatever the process state. +func (s *Service) Get(id string) (api.ContainedRun, error) { + rec, err := s.Store.Get(id) + if err != nil { + return api.ContainedRun{}, err + } + return toWire(rec), nil +} + +// Wait blocks until the run reaches a terminal status or ctx ends, then +// returns the saved record. +func (s *Service) Wait(ctx context.Context, id string) (api.ContainedRun, error) { + s.mu.Lock() + a := s.active[id] + s.mu.Unlock() + if a != nil { + select { + case <-a.done: + case <-ctx.Done(): + return api.ContainedRun{}, ctx.Err() + } + } + return s.Get(id) +} + +// Cancel stops a run in flight and waits for its record to settle. A run +// that already finished is returned unchanged with AlreadyFinished set. +func (s *Service) Cancel(ctx context.Context, id string) (api.ContainedRun, error) { + rec, err := s.Store.Get(id) + if err != nil { + return api.ContainedRun{}, err + } + if runstate.Terminal(rec.Status) { + out := toWire(rec) + out.AlreadyFinished = true + return out, nil + } + s.mu.Lock() + a := s.active[id] + if a != nil { + a.cancelled = true + a.cancel() + } + s.mu.Unlock() + if a == nil { + // Accepted or running with no goroutine: not possible after + // Reconcile ran at start; report the record as it is. + return toWire(rec), nil + } + return s.Wait(ctx, id) +} + +func (s *Service) validate(req api.ContainedRunRequest) (plan, error) { + var p plan + if len(req.Command) == 0 || strings.TrimSpace(req.Command[0]) == "" { + return p, &RequestError{"command is required"} + } + p.command = req.Command + switch p.profile = req.Profile; p.profile { + case "": + p.profile = api.RunProfileExperiment + case api.RunProfileExperiment: + case api.RunProfileAgent: + return p, &UnsupportedError{fmt.Sprintf("profile %q is not available yet (schema-checked agent steps, S6)", req.Profile)} + default: + return p, &RequestError{fmt.Sprintf("profile must be %q or %q", api.RunProfileExperiment, api.RunProfileAgent)} + } + switch p.network = req.Network; p.network { + case "": + p.network = api.RunNetworkNone + case api.RunNetworkNone, api.RunNetworkRestricted: + default: + return p, &RequestError{fmt.Sprintf("network must be %q or %q", api.RunNetworkNone, api.RunNetworkRestricted)} + } + if what, ok := s.Backend.Supports(p.network); !ok { + return p, &UnsupportedError{what} + } + for _, name := range req.EnvAllowlist { + if sandbox.IsCredentialName(name) { + return p, &RequestError{fmt.Sprintf("env_allowlist names credential %q; the experiment profile carries no credentials", name)} + } + } + p.allowlist = req.EnvAllowlist + p.timeout = time.Duration(s.Config.DefaultTimeoutMs) * time.Millisecond + if req.TimeoutMs > 0 { + if req.TimeoutMs > s.Config.MaxTimeoutMs { + return p, &RequestError{fmt.Sprintf("timeout_ms %d exceeds this server's cap of %d", req.TimeoutMs, s.Config.MaxTimeoutMs)} + } + p.timeout = time.Duration(req.TimeoutMs) * time.Millisecond + } + p.maxOutput = s.Config.DefaultMaxOutputBytes + if req.MaxOutputBytes > 0 { + if req.MaxOutputBytes > s.Config.MaxOutputBytesCap { + return p, &RequestError{fmt.Sprintf("max_output_bytes %d exceeds this server's cap of %d", req.MaxOutputBytes, s.Config.MaxOutputBytesCap)} + } + p.maxOutput = req.MaxOutputBytes + } + return p, s.validateWorkspace(req, &p) +} + +func (s *Service) validateWorkspace(req api.ContainedRunRequest, p *plan) error { + sources := 0 + for _, set := range []bool{req.Checkout != "", req.Worktree != nil, req.WorkspacePath != ""} { + if set { + sources++ + } + } + switch { + case sources == 0: + return &RequestError{"one of worktree or workspace_path is required"} + case sources > 1: + return &RequestError{"checkout, worktree and workspace_path are mutually exclusive"} + case req.Checkout != "": + return &UnsupportedError{"checkout ids need the checkout service (S1), which is not available yet; use worktree {repo, commit} or workspace_path"} + case req.Worktree != nil: + wt := *req.Worktree + if strings.TrimSpace(wt.Repo) == "" { + return &RequestError{"worktree.repo is required"} + } + if !fullSHA.MatchString(wt.Commit) { + return &RequestError{"worktree.commit must be a full 40-hex commit SHA; a tag or branch name cannot pin the run"} + } + if !repoAllowed(wt.Repo, s.Config.RepoAllowlist) { + return &ForbiddenError{fmt.Sprintf("repository %q is not on this server's repo_allowlist", wt.Repo)} + } + p.worktree = &wt + return nil + } + path := filepath.Clean(req.WorkspacePath) + if !filepath.IsAbs(path) { + return &RequestError{"workspace_path must be absolute"} + } + if !pathUnder(path, s.Config.WorkspaceRoots) { + return &ForbiddenError{fmt.Sprintf("workspace_path %q is not under this server's workspace_roots", path)} + } + if st, err := os.Stat(path); err != nil || !st.IsDir() { + return &RequestError{fmt.Sprintf("workspace_path %q is not a directory", path)} + } + p.workspace = path + return nil +} + +// repoAllowed reports whether repo starts with one of the allowlisted +// URL prefixes. +func repoAllowed(repo string, prefixes []string) bool { + for _, p := range prefixes { + if p = strings.TrimSpace(p); p != "" && strings.HasPrefix(repo, p) { + return true + } + } + return false +} + +// pathUnder reports whether path is one of roots or lies beneath one. +func pathUnder(path string, roots []string) bool { + for _, root := range roots { + root = filepath.Clean(strings.TrimSpace(root)) + if root == "" || root == "." { + continue + } + if path == root || strings.HasPrefix(path, strings.TrimSuffix(root, "/")+"/") { + return true + } + } + return false +} + +// execute runs one accepted run to a terminal status. Every exit path +// writes the record; nothing is left accepted or running by this process. +func (s *Service) execute(ctx context.Context, id string, p plan, a *active) { + defer func() { + s.mu.Lock() + delete(s.active, id) + s.mu.Unlock() + close(a.done) + }() + finish := func(status, reason string, fill func(*detail)) { + _, _ = s.Store.Update(id, func(rec *runstate.Record) error { + var d detail + _ = json.Unmarshal(rec.Detail, &d) + if fill != nil { + fill(&d) + } + raw, err := json.Marshal(d) + if err != nil { + return err + } + rec.Status, rec.Reason, rec.Detail = status, reason, raw + return nil + }) + } + workspace := p.workspace + if p.worktree != nil { + prov := s.Provisioner + if prov == nil { + prov = GitProvisioner{} + } + path, err := prov.Provision(ctx, s.Store.Path(id), *p.worktree) + if err != nil { + if ctx.Err() != nil { + finish(runstate.StatusCancelled, "cancelled while provisioning the worktree", nil) + } else { + finish(runstate.StatusFailed, "provisioning the worktree: "+s.scrub(err.Error()), nil) + } + return + } + workspace = path + } + if _, err := s.Store.Update(id, func(rec *runstate.Record) error { + var d detail + _ = json.Unmarshal(rec.Detail, &d) + d.Workspace = workspace + raw, err := json.Marshal(d) + rec.Status, rec.Detail = runstate.StatusRunning, raw + return err + }); err != nil { + finish(runstate.StatusFailed, "recording the start: "+err.Error(), nil) + return + } + + runCtx, cancelTimeout := context.WithTimeout(ctx, p.timeout) + defer cancelTimeout() + name := launchNamePrefix + id + spec := sandbox.LaunchSpec{ + Image: s.Config.Image, + Name: name, + Workspace: workspace, + Command: p.command, + Env: s.allowlistedEnv(p.allowlist), + EnvAllowlist: p.allowlist, + NetworkMode: p.network, + } + res, err := s.Backend.Launcher.Run(runCtx, spec) + // A launcher that returned without error finished the command; a + // cancel or deadline that landed after that does not unmake the result. + cancelled := err != nil && ctx.Err() != nil + timedOut := err != nil && !cancelled && errors.Is(runCtx.Err(), context.DeadlineExceeded) + status, reason, exit := classify(res, err, cancelled, timedOut) + if (cancelled || timedOut) && s.Backend.Teardown != nil { + tctx, cancel := context.WithTimeout(context.Background(), TeardownTimeout) + if terr := s.Backend.Teardown(tctx, name); terr != nil { + reason += "; teardown: " + s.scrub(terr.Error()) + } + cancel() + } + stdout, stdoutCut := s.persistOutput(id, StdoutArtifact, res.Stdout, p.maxOutput) + stderr, stderrCut := s.persistOutput(id, StderrArtifact, res.Stderr, p.maxOutput) + finish(status, reason, func(d *detail) { + d.ExitCode, d.TimedOut = exit, timedOut + d.Stdout, d.StdoutTruncatedAt = stdout, stdoutCut + d.Stderr, d.StderrTruncatedAt = stderr, stderrCut + }) +} + +// classify turns the launcher's answer into a status. The exit code is +// reported only when the launcher read one: a zero Result beside an error +// means the launcher refused before anything ran, and the launchers' +// exitUnknown means the process ended without a readable exit. Neither is +// ever turned into a guessed code. +func classify(res sandbox.Result, err error, cancelled, timedOut bool) (status, reason string, exit *int) { + launched := err == nil || res != (sandbox.Result{}) + if launched && res.ExitCode != exitUnknown { + code := res.ExitCode + exit = &code + } + switch { + case cancelled: + return runstate.StatusCancelled, "cancelled by the caller", exit + case timedOut: + return runstate.StatusFailed, "timed out", exit + case err == nil: + return runstate.StatusCompleted, "", exit + case exit != nil: + // The command ran and its exit was read; the error is the backend's + // own description (a Job that reports Failed on a non-zero exit). + return runstate.StatusCompleted, logscrub.ScrubString(err.Error()), exit + case !launched: + return runstate.StatusFailed, logscrub.ScrubString(err.Error()), nil + } + return runstate.StatusUnfinished, logscrub.ScrubString(err.Error()), nil +} + +// persistOutput scrubs raw, writes the whole of it as an artifact and +// returns the response copy, cut at max with the offset when it was. +func (s *Service) persistOutput(id, name, raw string, max int64) (string, *int64) { + text := s.scrub(raw) + _ = os.WriteFile(filepath.Join(s.Store.Path(id), name), []byte(text), 0o660) + if int64(len(text)) <= max { + return text, nil + } + cut := max + return text[:max], &cut +} + +func (s *Service) scrub(v string) string { + if s.Scrub != nil { + return s.Scrub(v) + } + return logscrub.ScrubString(v) +} + +// allowlistedEnv is the explicit environment the container receives: the +// allowlisted names present in the service's environment, credentials +// excluded by sandbox.SanitizedEnv. The podman launcher forwards only +// explicit entries into the container, so the allowlist alone is not +// enough. +func (s *Service) allowlistedEnv(allowlist []string) map[string]string { + environ := os.Environ + if s.Environ != nil { + environ = s.Environ + } + out := map[string]string{} + for _, entry := range sandbox.SanitizedEnv(environ(), allowlist, nil) { + if k, v, ok := strings.Cut(entry, "="); ok { + out[k] = v + } + } + return out +} + +func toWire(rec runstate.Record) api.ContainedRun { + var d detail + _ = json.Unmarshal(rec.Detail, &d) + return api.ContainedRun{ + ID: rec.ID, Status: rec.Status, Owner: rec.Owner, Reason: rec.Reason, + CreatedAt: rec.CreatedAt, StartedAt: rec.StartedAt, FinishedAt: rec.FinishedAt, + Profile: d.Profile, Network: d.Network, Backend: d.Backend, Command: d.Command, Workdir: d.Workspace, + ExitCode: d.ExitCode, TimedOut: d.TimedOut, Stdout: d.Stdout, Stderr: d.Stderr, + StdoutTruncatedAt: d.StdoutTruncatedAt, StderrTruncatedAt: d.StderrTruncatedAt, + } +} diff --git a/src/crux/runs/service_test.go b/src/crux/runs/service_test.go new file mode 100644 index 0000000000..9f2d6ef609 --- /dev/null +++ b/src/crux/runs/service_test.go @@ -0,0 +1,458 @@ +package runs + +import ( + "context" + "errors" + "os" + "path/filepath" + "strings" + "testing" + "time" + + "github.com/hivecommons/hive/crux/api" + "github.com/hivecommons/hive/crux/runstate" + "github.com/hivecommons/hive/crux/sandbox" +) + +// fakeLauncher drives every classify path without a container runtime. +type fakeLauncher struct { + run func(ctx context.Context, spec sandbox.LaunchSpec) (sandbox.Result, error) + specs chan sandbox.LaunchSpec +} + +func newFakeLauncher(run func(ctx context.Context, spec sandbox.LaunchSpec) (sandbox.Result, error)) *fakeLauncher { + return &fakeLauncher{run: run, specs: make(chan sandbox.LaunchSpec, 8)} +} + +func (f *fakeLauncher) Run(ctx context.Context, spec sandbox.LaunchSpec) (sandbox.Result, error) { + f.specs <- spec + return f.run(ctx, spec) +} + +// blocking returns a launcher that waits for ctx and reports its error. +func blocking() *fakeLauncher { + return newFakeLauncher(func(ctx context.Context, _ sandbox.LaunchSpec) (sandbox.Result, error) { + <-ctx.Done() + return sandbox.Result{ExitCode: -1}, ctx.Err() + }) +} + +type fixture struct { + t *testing.T + svc *Service + launcher *fakeLauncher + torn chan string + root string +} + +const testSHA = "0123456789abcdef0123456789abcdef01234567" + +func newFixture(t *testing.T, launcher *fakeLauncher) *fixture { + t.Helper() + workDir := t.TempDir() + store, err := runstate.Open(workDir) + if err != nil { + t.Fatal(err) + } + root := filepath.Join(t.TempDir(), "ws") + if err := os.MkdirAll(filepath.Join(root, "proj"), 0o755); err != nil { + t.Fatal(err) + } + f := &fixture{t: t, launcher: launcher, torn: make(chan string, 8), root: root} + backend := &Backend{ + Name: "fake", + Launcher: launcher, + Capabilities: Capabilities{NetworkNone: true}, + Teardown: func(_ context.Context, name string) error { f.torn <- name; return nil }, + } + cfg := Config{ + Image: "img:1", + RepoAllowlist: []string{"https://github.com/hivecommons/"}, + WorkspaceRoots: []string{root}, + MaxTimeoutMs: time.Minute.Milliseconds(), + } + f.svc = New(store, backend, cfg) + f.svc.Environ = func() []string { return []string{"KEEP=yes", "GITHUB_TOKEN=secret", "DROP=no"} } + return f +} + +func (f *fixture) workspace() string { return filepath.Join(f.root, "proj") } + +func (f *fixture) start(req api.ContainedRunRequest) api.ContainedRun { + f.t.Helper() + run, created, err := f.svc.Create(context.Background(), "operator", req) + if err != nil || !created { + f.t.Fatalf("Create: %v created=%v", err, created) + } + if run.Status != api.RunAccepted || run.ID == "" { + f.t.Fatalf("accepted record = %+v", run) + } + return run +} + +func (f *fixture) wait(id string) api.ContainedRun { + f.t.Helper() + ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second) + defer cancel() + run, err := f.svc.Wait(ctx, id) + if err != nil { + f.t.Fatal(err) + } + return run +} + +func (f *fixture) spec() sandbox.LaunchSpec { + f.t.Helper() + select { + case s := <-f.launcher.specs: + return s + case <-time.After(10 * time.Second): + f.t.Fatal("launcher was never called") + } + return sandbox.LaunchSpec{} +} + +func TestCompletedRunCarriesOutputAndSanitizedEnv(t *testing.T) { + f := newFixture(t, newFakeLauncher(func(_ context.Context, _ sandbox.LaunchSpec) (sandbox.Result, error) { + return sandbox.Result{Stdout: "hello\n", Stderr: "warn\n"}, nil + })) + run := f.start(api.ContainedRunRequest{ + WorkspacePath: f.workspace(), Command: []string{"echo", "hello"}, + EnvAllowlist: []string{"KEEP", "MISSING"}, + }) + spec := f.spec() + if spec.Image != "img:1" || spec.Name != "crux-run-"+run.ID || spec.Workspace != f.workspace() || spec.NetworkMode != "none" { + t.Fatalf("spec = %+v", spec) + } + if spec.Env["KEEP"] != "yes" || len(spec.Env) != 1 { + t.Fatalf("env = %v", spec.Env) + } + done := f.wait(run.ID) + if done.Status != api.RunCompleted || done.ExitCode == nil || *done.ExitCode != 0 || done.Stdout != "hello\n" || done.Stderr != "warn\n" { + t.Fatalf("completed = %+v", done) + } + if done.Profile != api.RunProfileExperiment || done.Network != api.RunNetworkNone || done.Backend != "fake" || done.Workdir != f.workspace() { + t.Fatalf("plan not recorded: %+v", done) + } + if done.StartedAt == nil || done.FinishedAt == nil || done.Owner != "operator" { + t.Fatalf("timestamps/owner = %+v", done) + } + if out, _ := os.ReadFile(filepath.Join(f.svc.Store.Path(run.ID), StdoutArtifact)); string(out) != "hello\n" { + t.Fatalf("stdout artifact = %q", out) + } + if got, err := f.svc.Get(run.ID); err != nil || got.Status != api.RunCompleted { + t.Fatalf("Get = %+v, %v", got, err) + } + if len(f.torn) != 0 { + t.Fatal("teardown ran for a completed run") + } +} + +func TestNonZeroExitIsCompletedWithTheCode(t *testing.T) { + f := newFixture(t, newFakeLauncher(func(_ context.Context, _ sandbox.LaunchSpec) (sandbox.Result, error) { + return sandbox.Result{Stderr: "boom", ExitCode: 3}, errors.New("podman: exit status 3") + })) + run := f.wait(f.start(api.ContainedRunRequest{WorkspacePath: f.workspace(), Command: []string{"false"}}).ID) + if run.Status != api.RunCompleted || run.ExitCode == nil || *run.ExitCode != 3 || run.Reason != "podman: exit status 3" { + t.Fatalf("non-zero = %+v", run) + } +} + +func TestLauncherRefusalIsFailedWithoutAnExitCode(t *testing.T) { + f := newFixture(t, newFakeLauncher(func(_ context.Context, _ sandbox.LaunchSpec) (sandbox.Result, error) { + return sandbox.Result{}, errors.New("image pull failed") + })) + run := f.wait(f.start(api.ContainedRunRequest{WorkspacePath: f.workspace(), Command: []string{"x"}}).ID) + if run.Status != api.RunFailed || run.ExitCode != nil || run.Reason != "image pull failed" { + t.Fatalf("refusal = %+v", run) + } +} + +func TestUnknownExitIsUnfinishedNeverGuessed(t *testing.T) { + f := newFixture(t, newFakeLauncher(func(_ context.Context, _ sandbox.LaunchSpec) (sandbox.Result, error) { + return sandbox.Result{Stdout: "partial", ExitCode: -1}, errors.New("pod vanished") + })) + run := f.wait(f.start(api.ContainedRunRequest{WorkspacePath: f.workspace(), Command: []string{"x"}}).ID) + if run.Status != api.RunUnfinished || run.ExitCode != nil || run.Stdout != "partial" || run.Reason != "pod vanished" { + t.Fatalf("unknown exit = %+v", run) + } +} + +func TestTimeoutFailsAndTearsDown(t *testing.T) { + f := newFixture(t, blocking()) + run := f.start(api.ContainedRunRequest{WorkspacePath: f.workspace(), Command: []string{"sleep"}, TimeoutMs: 20}) + done := f.wait(run.ID) + if done.Status != api.RunFailed || !done.TimedOut || done.ExitCode != nil || done.Reason != "timed out" { + t.Fatalf("timeout = %+v", done) + } + if name := <-f.torn; name != "crux-run-"+run.ID { + t.Fatalf("teardown name = %q", name) + } +} + +func TestCancelTearsDownAndLateCancelReportsAlreadyFinished(t *testing.T) { + f := newFixture(t, blocking()) + run := f.start(api.ContainedRunRequest{WorkspacePath: f.workspace(), Command: []string{"sleep"}}) + f.spec() + f.svc.Backend.Teardown = func(context.Context, string) error { return errors.New("rm: token=abc123 gone") } + ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second) + defer cancel() + cancelled, err := f.svc.Cancel(ctx, run.ID) + if err != nil { + t.Fatal(err) + } + if cancelled.Status != api.RunCancelled || cancelled.AlreadyFinished || cancelled.ExitCode != nil { + t.Fatalf("cancel = %+v", cancelled) + } + if !strings.HasPrefix(cancelled.Reason, "cancelled by the caller; teardown: ") { + t.Fatalf("teardown error not recorded: %q", cancelled.Reason) + } + late, err := f.svc.Cancel(ctx, run.ID) + if err != nil || !late.AlreadyFinished || late.Status != api.RunCancelled { + t.Fatalf("late cancel = %+v, %v", late, err) + } + if _, err := f.svc.Cancel(ctx, "run_missing"); !errors.Is(err, ErrNotFound) { + t.Fatalf("cancel unknown = %v", err) + } + if _, err := f.svc.Get("run_missing"); !errors.Is(err, ErrNotFound) { + t.Fatalf("get unknown = %v", err) + } +} + +func TestCancelWithoutAGoroutineReportsTheRecord(t *testing.T) { + f := newFixture(t, blocking()) + rec, _, err := f.svc.Store.Create(runstate.Record{}) + if err != nil { + t.Fatal(err) + } + run, err := f.svc.Cancel(context.Background(), rec.ID) + if err != nil || run.Status != api.RunAccepted || run.AlreadyFinished { + t.Fatalf("orphan cancel = %+v, %v", run, err) + } + changed, err := f.svc.Reconcile() + if err != nil || len(changed) != 1 || changed[0].Status != runstate.StatusUnfinished || changed[0].Reason != ReconcileReason { + t.Fatalf("Reconcile = %+v, %v", changed, err) + } +} + +func TestWaitHonoursItsContext(t *testing.T) { + f := newFixture(t, blocking()) + run := f.start(api.ContainedRunRequest{WorkspacePath: f.workspace(), Command: []string{"sleep"}}) + ctx, cancel := context.WithCancel(context.Background()) + cancel() + if _, err := f.svc.Wait(ctx, run.ID); !errors.Is(err, context.Canceled) { + t.Fatalf("Wait = %v", err) + } + f.svc.Cancel(context.Background(), run.ID) +} + +func TestOutputIsScrubbedAndTruncatedWithTheOffsetRecorded(t *testing.T) { + long := strings.Repeat("a", 50) + "secret" + strings.Repeat("b", 50) + f := newFixture(t, newFakeLauncher(func(_ context.Context, _ sandbox.LaunchSpec) (sandbox.Result, error) { + return sandbox.Result{Stdout: long, Stderr: "short"}, nil + })) + f.svc.Scrub = func(v string) string { return strings.ReplaceAll(v, "secret", "[x]") } + run := f.wait(f.start(api.ContainedRunRequest{WorkspacePath: f.workspace(), Command: []string{"x"}, MaxOutputBytes: 10}).ID) + if run.Stdout != strings.Repeat("a", 10) || run.StdoutTruncatedAt == nil || *run.StdoutTruncatedAt != 10 { + t.Fatalf("truncated stdout = %q at %v", run.Stdout, run.StdoutTruncatedAt) + } + if run.Stderr != "short" || run.StderrTruncatedAt != nil { + t.Fatalf("stderr = %q at %v", run.Stderr, run.StderrTruncatedAt) + } + full, err := os.ReadFile(filepath.Join(f.svc.Store.Path(run.ID), StdoutArtifact)) + if err != nil { + t.Fatal(err) + } + if want := strings.ReplaceAll(long, "secret", "[x]"); string(full) != want { + t.Fatalf("artifact = %q", full) + } +} + +func TestDefaultScrubRedactsCredentials(t *testing.T) { + f := newFixture(t, newFakeLauncher(func(_ context.Context, _ sandbox.LaunchSpec) (sandbox.Result, error) { + return sandbox.Result{Stdout: "token ghp_abcdefghijklmnopqrstuvwxyz0123456789 ok"}, nil + })) + run := f.wait(f.start(api.ContainedRunRequest{WorkspacePath: f.workspace(), Command: []string{"x"}}).ID) + if strings.Contains(run.Stdout, "ghp_abcdefghijklmnopqrstuvwxyz0123456789") { + t.Fatalf("token survived scrubbing: %q", run.Stdout) + } +} + +func TestIdempotencyKeyReturnsTheExistingRun(t *testing.T) { + f := newFixture(t, newFakeLauncher(func(_ context.Context, _ sandbox.LaunchSpec) (sandbox.Result, error) { + return sandbox.Result{Stdout: "once"}, nil + })) + req := api.ContainedRunRequest{WorkspacePath: f.workspace(), Command: []string{"x"}, IdempotencyKey: "k1"} + first := f.wait(f.start(req).ID) + again, created, err := f.svc.Create(context.Background(), "operator", req) + if err != nil || created || again.ID != first.ID || again.Status != api.RunCompleted || again.Stdout != "once" { + t.Fatalf("replay = %+v created=%v err=%v", again, created, err) + } + other, created, err := f.svc.Create(context.Background(), "someone-else", req) + if err != nil || !created || other.ID == first.ID { + t.Fatalf("other owner shared the record: %+v created=%v err=%v", other, created, err) + } + f.wait(other.ID) + if len(f.launcher.specs) != 2 { + t.Fatalf("launches = %d, want 2", len(f.launcher.specs)) + } +} + +func TestWorktreeIsProvisionedBeforeLaunch(t *testing.T) { + f := newFixture(t, newFakeLauncher(func(_ context.Context, _ sandbox.LaunchSpec) (sandbox.Result, error) { + return sandbox.Result{}, nil + })) + var got api.ContainedRunWorktree + f.svc.Provisioner = provisionFunc(func(_ context.Context, dir string, wt api.ContainedRunWorktree) (string, error) { + got = wt + return filepath.Join(dir, "workspace"), nil + }) + wt := &api.ContainedRunWorktree{Repo: "https://github.com/hivecommons/hive", Commit: testSHA} + run := f.start(api.ContainedRunRequest{Worktree: wt, Command: []string{"make"}}) + spec := f.spec() + done := f.wait(run.ID) + if got != *wt || spec.Workspace != filepath.Join(f.svc.Store.Path(run.ID), "workspace") || done.Workdir != spec.Workspace { + t.Fatalf("worktree = %+v spec.Workspace=%q done=%+v", got, spec.Workspace, done) + } + if done.Status != api.RunCompleted { + t.Fatalf("status = %s", done.Status) + } +} + +func TestProvisionFailureIsFailedOrCancelled(t *testing.T) { + f := newFixture(t, blocking()) + f.svc.Provisioner = provisionFunc(func(context.Context, string, api.ContainedRunWorktree) (string, error) { + return "", errors.New("clone refused") + }) + wt := &api.ContainedRunWorktree{Repo: "https://github.com/hivecommons/hive", Commit: testSHA} + run := f.wait(f.start(api.ContainedRunRequest{Worktree: wt, Command: []string{"make"}}).ID) + if run.Status != api.RunFailed || run.Reason != "provisioning the worktree: clone refused" { + t.Fatalf("failed provision = %+v", run) + } + + f.svc.Provisioner = provisionFunc(func(ctx context.Context, _ string, _ api.ContainedRunWorktree) (string, error) { + <-ctx.Done() + return "", ctx.Err() + }) + run = f.start(api.ContainedRunRequest{Worktree: wt, Command: []string{"make"}}) + cancelled, err := f.svc.Cancel(context.Background(), run.ID) + if err != nil || cancelled.Status != api.RunCancelled || cancelled.Reason != "cancelled while provisioning the worktree" { + t.Fatalf("cancelled provision = %+v, %v", cancelled, err) + } + if len(f.launcher.specs) != 0 { + t.Fatal("launcher ran without a workspace") + } +} + +type provisionFunc func(ctx context.Context, dir string, wt api.ContainedRunWorktree) (string, error) + +func (p provisionFunc) Provision(ctx context.Context, dir string, wt api.ContainedRunWorktree) (string, error) { + return p(ctx, dir, wt) +} + +func TestValidationErrors(t *testing.T) { + f := newFixture(t, blocking()) + ws := f.workspace() + wt := &api.ContainedRunWorktree{Repo: "https://github.com/hivecommons/hive", Commit: testSHA} + cases := []struct { + name string + req api.ContainedRunRequest + want any + msg string + }{ + {"no command", api.ContainedRunRequest{WorkspacePath: ws}, &RequestError{}, "command is required"}, + {"blank command", api.ContainedRunRequest{WorkspacePath: ws, Command: []string{" "}}, &RequestError{}, "command is required"}, + {"agent profile", api.ContainedRunRequest{WorkspacePath: ws, Command: []string{"x"}, Profile: "agent"}, &UnsupportedError{}, "S6"}, + {"bad profile", api.ContainedRunRequest{WorkspacePath: ws, Command: []string{"x"}, Profile: "root"}, &RequestError{}, "profile must be"}, + {"bad network", api.ContainedRunRequest{WorkspacePath: ws, Command: []string{"x"}, Network: "host"}, &RequestError{}, "network must be"}, + {"restricted unsupported", api.ContainedRunRequest{WorkspacePath: ws, Command: []string{"x"}, Network: "restricted"}, &UnsupportedError{}, `cannot enforce network "restricted"`}, + {"credential env", api.ContainedRunRequest{WorkspacePath: ws, Command: []string{"x"}, EnvAllowlist: []string{"GITHUB_TOKEN"}}, &RequestError{}, "credential"}, + {"timeout cap", api.ContainedRunRequest{WorkspacePath: ws, Command: []string{"x"}, TimeoutMs: time.Hour.Milliseconds()}, &RequestError{}, "timeout_ms"}, + {"output cap", api.ContainedRunRequest{WorkspacePath: ws, Command: []string{"x"}, MaxOutputBytes: DefaultMaxOutputCap + 1}, &RequestError{}, "max_output_bytes"}, + {"no source", api.ContainedRunRequest{Command: []string{"x"}}, &RequestError{}, "one of worktree or workspace_path"}, + {"two sources", api.ContainedRunRequest{Command: []string{"x"}, WorkspacePath: ws, Worktree: wt}, &RequestError{}, "mutually exclusive"}, + {"checkout id", api.ContainedRunRequest{Command: []string{"x"}, Checkout: "chk_1"}, &UnsupportedError{}, "S1"}, + {"worktree repo", api.ContainedRunRequest{Command: []string{"x"}, Worktree: &api.ContainedRunWorktree{Commit: testSHA}}, &RequestError{}, "worktree.repo"}, + {"worktree short sha", api.ContainedRunRequest{Command: []string{"x"}, Worktree: &api.ContainedRunWorktree{Repo: wt.Repo, Commit: "main"}}, &RequestError{}, "40-hex"}, + {"worktree forbidden", api.ContainedRunRequest{Command: []string{"x"}, Worktree: &api.ContainedRunWorktree{Repo: "https://example.com/r", Commit: testSHA}}, &ForbiddenError{}, "repo_allowlist"}, + {"relative workspace", api.ContainedRunRequest{Command: []string{"x"}, WorkspacePath: "proj"}, &RequestError{}, "absolute"}, + {"workspace outside roots", api.ContainedRunRequest{Command: []string{"x"}, WorkspacePath: filepath.Dir(f.root)}, &ForbiddenError{}, "workspace_roots"}, + {"workspace sibling prefix", api.ContainedRunRequest{Command: []string{"x"}, WorkspacePath: f.root + "2"}, &ForbiddenError{}, "workspace_roots"}, + {"workspace missing", api.ContainedRunRequest{Command: []string{"x"}, WorkspacePath: filepath.Join(ws, "nope")}, &RequestError{}, "not a directory"}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + _, created, err := f.svc.Create(context.Background(), "operator", tc.req) + if created || err == nil { + t.Fatalf("Create accepted: created=%v err=%v", created, err) + } + var ok bool + switch tc.want.(type) { + case *RequestError: + var e *RequestError + ok = errors.As(err, &e) + case *ForbiddenError: + var e *ForbiddenError + ok = errors.As(err, &e) + case *UnsupportedError: + var e *UnsupportedError + ok = errors.As(err, &e) + } + if !ok || !strings.Contains(err.Error(), tc.msg) { + t.Fatalf("err = %T %v, want %T containing %q", err, err, tc.want, tc.msg) + } + }) + } + if len(f.launcher.specs) != 0 { + t.Fatal("a refused request reached the launcher") + } +} + +func TestNotConfiguredServesRecordsButRefusesCreates(t *testing.T) { + store, err := runstate.Open(t.TempDir()) + if err != nil { + t.Fatal(err) + } + svc := New(store, nil, Config{}) + if svc.Configured() { + t.Fatal("Configured without a backend") + } + if _, _, err := svc.Create(context.Background(), "operator", api.ContainedRunRequest{Command: []string{"x"}}); !errors.Is(err, ErrNotConfigured) { + t.Fatalf("Create = %v", err) + } + rec, _, _ := store.Create(runstate.Record{}) + if run, err := svc.Get(rec.ID); err != nil || run.ID != rec.ID { + t.Fatalf("Get = %+v, %v", run, err) + } +} + +func TestClassifyTable(t *testing.T) { + unknown := sandbox.Result{ExitCode: -1} + boom := errors.New("boom") + cases := []struct { + name string + res sandbox.Result + err error + cancelled bool + timedOut bool + status string + wantExit *int + wantReason string + }{ + {"ok", sandbox.Result{}, nil, false, false, runstate.StatusCompleted, ptr(0), ""}, + {"non-zero", sandbox.Result{ExitCode: 2}, boom, false, false, runstate.StatusCompleted, ptr(2), "boom"}, + {"refused", sandbox.Result{}, boom, false, false, runstate.StatusFailed, nil, "boom"}, + {"unknown", unknown, boom, false, false, runstate.StatusUnfinished, nil, "boom"}, + {"cancelled", unknown, context.Canceled, true, false, runstate.StatusCancelled, nil, "cancelled by the caller"}, + {"cancelled with exit", sandbox.Result{ExitCode: 137}, boom, true, false, runstate.StatusCancelled, ptr(137), "cancelled by the caller"}, + {"timed out", unknown, context.DeadlineExceeded, false, true, runstate.StatusFailed, nil, "timed out"}, + } + for _, tc := range cases { + status, reason, exit := classify(tc.res, tc.err, tc.cancelled, tc.timedOut) + if status != tc.status || reason != tc.wantReason || (exit == nil) != (tc.wantExit == nil) || (exit != nil && *exit != *tc.wantExit) { + t.Errorf("%s: got %s %q %v", tc.name, status, reason, exit) + } + } +} + +func ptr(v int) *int { return &v } diff --git a/src/crux/runstate/runstate.go b/src/crux/runstate/runstate.go new file mode 100644 index 0000000000..97771f2e95 --- /dev/null +++ b/src/crux/runstate/runstate.go @@ -0,0 +1,362 @@ +// Package runstate is the saved-run-results store of the Crux work services +// (S7 in hivecommons/crux#114): a stable, caller-visible ID assigned at +// accept time, an explicit status set, one JSON record per item under +// WorkDir()/runs/<id>/record.json and an append-only runs/index.jsonl +// history, mirroring the sandbox-runs conventions in sandbox_run.go. +// +// The store never guesses. A record that was accepted or running when the +// serving process stopped is reconciled to StatusUnfinished on the next +// start (Reconcile); the caller decides whether to re-run. An idempotency +// key supplied by the caller makes a repeated create return the existing +// record instead of a second one. +package runstate + +import ( + "crypto/rand" + "crypto/sha256" + "encoding/hex" + "encoding/json" + "errors" + "fmt" + "os" + "path/filepath" + "sort" + "strings" + "sync" + "time" +) + +// Statuses. The set is closed: a driver maps these onto its own meaning; +// crux only ever reports what happened to the step. +const ( + StatusAccepted = "accepted" + StatusRunning = "running" + StatusWaiting = "waiting" + StatusCompleted = "completed" + StatusFailed = "failed" + StatusCancelled = "cancelled" + StatusUnfinished = "unfinished" + StatusUnsupported = "unsupported" +) + +const ( + // DirName is the per-concern directory under the work dir. + DirName = "runs" + // RecordName is the per-item record file inside the item's directory. + RecordName = "record.json" + // IndexName is the append-only status history, one IndexEntry per line. + IndexName = "index.jsonl" + // KindRun is a contained run (S2); S6 steps add their own kind later. + KindRun = "run" + + idRandomBytes = 6 + maxIDLen = 64 + dirMode = 0o770 + fileMode = 0o660 +) + +// ErrNotFound is returned by Get and Update for an unknown ID. +var ErrNotFound = errors.New("runstate: record not found") + +// Record is the saved state of one item. Detail carries the owning service's +// payload (for S2 the command result) and is opaque to this package. +type Record struct { + ID string `json:"id"` + Kind string `json:"kind"` + Status string `json:"status"` + Owner string `json:"owner,omitempty"` + IdempotencyKey string `json:"idempotency_key,omitempty"` + CreatedAt time.Time `json:"created_at"` + StartedAt *time.Time `json:"started_at,omitempty"` + FinishedAt *time.Time `json:"finished_at,omitempty"` + Reason string `json:"reason,omitempty"` + Detail json.RawMessage `json:"detail,omitempty"` +} + +// IndexEntry is one line of the append-only history: every status the item +// passed through, in order. +type IndexEntry struct { + At time.Time `json:"at"` + ID string `json:"id"` + Kind string `json:"kind"` + Status string `json:"status"` + Reason string `json:"reason,omitempty"` +} + +// Terminal reports whether status is final: nothing moves out of it. +func Terminal(status string) bool { + switch status { + case StatusCompleted, StatusFailed, StatusCancelled, StatusUnfinished, StatusUnsupported: + return true + } + return false +} + +// Valid reports whether status is one of the closed set. +func Valid(status string) bool { + switch status { + case StatusAccepted, StatusRunning, StatusWaiting: + return true + } + return Terminal(status) +} + +// Dir is the runs directory under workDir. +func Dir(workDir string) string { return filepath.Join(workDir, DirName) } + +// DeriveIdempotencyKey scopes a caller-supplied key to its owner so two +// callers using the same key cannot read each other's records. The result +// is what Record.IdempotencyKey stores; an empty key derives to "". +func DeriveIdempotencyKey(owner, key string) string { + if strings.TrimSpace(key) == "" { + return "" + } + h := sha256.New() + for _, p := range []string{owner, key} { + h.Write([]byte(p)) + h.Write([]byte{0}) + } + return hex.EncodeToString(h.Sum(nil)) +} + +// Store is the on-disk record store for one work dir. It is safe for +// concurrent use within one process; a work dir is served by one process. +type Store struct { + dir string + + mu sync.Mutex + keys map[string]string // derived idempotency key -> id + // Now and NewID are overridable for tests. + Now func() time.Time + NewID func() string +} + +// Open loads the store at Dir(workDir), creating the directory and +// rebuilding the idempotency index from the records already on disk. +func Open(workDir string) (*Store, error) { + s := &Store{dir: Dir(workDir), keys: map[string]string{}, Now: time.Now, NewID: newID} + if err := os.MkdirAll(s.dir, dirMode); err != nil { + return nil, fmt.Errorf("runstate: %w", err) + } + recs, err := s.List() + if err != nil { + return nil, err + } + for _, r := range recs { + if r.IdempotencyKey != "" { + s.keys[r.IdempotencyKey] = r.ID + } + } + return s, nil +} + +// Path is the directory of one item: its record and the owning service's +// artifacts live there. +func (s *Store) Path(id string) string { return filepath.Join(s.dir, id) } + +// Create saves rec as a new item in StatusAccepted and returns it with its +// ID and timestamps filled in. When rec.IdempotencyKey names an existing +// item, that item's current record is returned with created=false and +// nothing is written. +func (s *Store) Create(rec Record) (Record, bool, error) { + s.mu.Lock() + defer s.mu.Unlock() + if rec.IdempotencyKey != "" { + if id, ok := s.keys[rec.IdempotencyKey]; ok { + existing, err := s.read(id) + return existing, false, err + } + } + if rec.Kind == "" { + rec.Kind = KindRun + } + rec.ID = s.NewID() + rec.Status = StatusAccepted + rec.CreatedAt = s.Now().UTC() + rec.StartedAt, rec.FinishedAt = nil, nil + if err := os.MkdirAll(s.Path(rec.ID), dirMode); err != nil { + return Record{}, false, fmt.Errorf("runstate: %w", err) + } + if err := s.write(rec); err != nil { + return Record{}, false, err + } + if rec.IdempotencyKey != "" { + s.keys[rec.IdempotencyKey] = rec.ID + } + return rec, true, nil +} + +// Get returns the saved record whatever the process state. +func (s *Store) Get(id string) (Record, error) { + s.mu.Lock() + defer s.mu.Unlock() + return s.read(id) +} + +// Update applies fn to the saved record and writes the result. fn may change +// Status (validated against the closed set), Reason and Detail; a terminal +// record is never moved to another status. Timestamps are maintained here: +// StartedAt on the move to running, FinishedAt on the move to a terminal +// status. +func (s *Store) Update(id string, fn func(*Record) error) (Record, error) { + s.mu.Lock() + defer s.mu.Unlock() + rec, err := s.read(id) + if err != nil { + return Record{}, err + } + before := rec.Status + if err := fn(&rec); err != nil { + return Record{}, err + } + rec.ID = id + if !Valid(rec.Status) { + return Record{}, fmt.Errorf("runstate: invalid status %q", rec.Status) + } + if Terminal(before) && rec.Status != before { + return Record{}, fmt.Errorf("runstate: %s is already %s", id, before) + } + if rec.Status != before { + now := s.Now().UTC() + if rec.Status == StatusRunning && rec.StartedAt == nil { + rec.StartedAt = &now + } + if Terminal(rec.Status) && rec.FinishedAt == nil { + rec.FinishedAt = &now + } + } + if err := s.write(rec); err != nil { + return Record{}, err + } + return rec, nil +} + +// List returns every saved record, oldest first. +func (s *Store) List() ([]Record, error) { + entries, err := os.ReadDir(s.dir) + if err != nil { + if os.IsNotExist(err) { + return nil, nil + } + return nil, fmt.Errorf("runstate: %w", err) + } + var out []Record + for _, e := range entries { + if !e.IsDir() { + continue + } + rec, err := s.read(e.Name()) + if err != nil { + if errors.Is(err, ErrNotFound) { + continue // a directory with artifacts but no record yet + } + return nil, err + } + out = append(out, rec) + } + sort.Slice(out, func(i, j int) bool { + if out[i].CreatedAt.Equal(out[j].CreatedAt) { + return out[i].ID < out[j].ID + } + return out[i].CreatedAt.Before(out[j].CreatedAt) + }) + return out, nil +} + +// Reconcile moves every accepted or running record to StatusUnfinished with +// reason and returns the records it changed. It runs at `crux serve` start: +// the process that owned those items is gone, so their exit is not knowable +// and they are never restarted silently. +func (s *Store) Reconcile(reason string) ([]Record, error) { + recs, err := s.List() + if err != nil { + return nil, err + } + var changed []Record + for _, r := range recs { + if r.Status != StatusAccepted && r.Status != StatusRunning { + continue + } + rec, err := s.Update(r.ID, func(rec *Record) error { + rec.Status = StatusUnfinished + rec.Reason = reason + return nil + }) + if err != nil { + return changed, err + } + changed = append(changed, rec) + } + return changed, nil +} + +func (s *Store) read(id string) (Record, error) { + if !validID(id) { + return Record{}, ErrNotFound + } + data, err := os.ReadFile(filepath.Join(s.Path(id), RecordName)) + if err != nil { + if os.IsNotExist(err) { + return Record{}, ErrNotFound + } + return Record{}, fmt.Errorf("runstate: %w", err) + } + var rec Record + if err := json.Unmarshal(data, &rec); err != nil { + return Record{}, fmt.Errorf("runstate: %s: %w", id, err) + } + return rec, nil +} + +// write replaces the record atomically and appends the status to the index. +func (s *Store) write(rec Record) error { + data, err := json.Marshal(rec) + if err != nil { + return fmt.Errorf("runstate: %w", err) + } + path := filepath.Join(s.Path(rec.ID), RecordName) + tmp := path + ".tmp" + if err := os.WriteFile(tmp, data, fileMode); err != nil { + return fmt.Errorf("runstate: %w", err) + } + if err := os.Rename(tmp, path); err != nil { + return fmt.Errorf("runstate: %w", err) + } + line, err := json.Marshal(IndexEntry{At: s.Now().UTC(), ID: rec.ID, Kind: rec.Kind, Status: rec.Status, Reason: rec.Reason}) + if err != nil { + return fmt.Errorf("runstate: %w", err) + } + f, err := os.OpenFile(filepath.Join(s.dir, IndexName), os.O_CREATE|os.O_APPEND|os.O_WRONLY, fileMode) + if err != nil { + return fmt.Errorf("runstate: %w", err) + } + _, werr := f.Write(append(line, '\n')) + if cerr := f.Close(); werr == nil { + werr = cerr + } + if werr != nil { + return fmt.Errorf("runstate: %w", werr) + } + return nil +} + +// validID keeps a caller-supplied ID from escaping the runs directory. +func validID(id string) bool { + if id == "" || len(id) > maxIDLen { + return false + } + for _, r := range id { + if !(r >= 'a' && r <= 'z' || r >= '0' && r <= '9' || r == '_' || r == '-') { + return false + } + } + return true +} + +func newID() string { + var b [idRandomBytes]byte + if _, err := rand.Read(b[:]); err != nil { + panic(fmt.Sprintf("runstate: crypto/rand: %v", err)) + } + return "run_" + hex.EncodeToString(b[:]) +} diff --git a/src/crux/runstate/runstate_test.go b/src/crux/runstate/runstate_test.go new file mode 100644 index 0000000000..7ecdfe7e55 --- /dev/null +++ b/src/crux/runstate/runstate_test.go @@ -0,0 +1,381 @@ +package runstate + +import ( + "bufio" + "encoding/json" + "errors" + "os" + "path/filepath" + "strings" + "testing" + "time" +) + +func newStore(t *testing.T) (*Store, string) { + t.Helper() + dir := t.TempDir() + s, err := Open(dir) + if err != nil { + t.Fatal(err) + } + ids := 0 + s.NewID = func() string { ids++; return "run_" + strings.Repeat("0", 11) + string(rune('a'+ids-1)) } + now := time.Date(2026, 11, 1, 12, 0, 0, 0, time.UTC) + s.Now = func() time.Time { now = now.Add(time.Second); return now } + return s, dir +} + +func TestCreateGetAndIndex(t *testing.T) { + s, dir := newStore(t) + rec, created, err := s.Create(Record{Owner: "operator", Detail: json.RawMessage(`{"x":1}`)}) + if err != nil || !created { + t.Fatalf("Create: %v created=%v", err, created) + } + if rec.ID == "" || rec.Status != StatusAccepted || rec.Kind != KindRun || rec.CreatedAt.IsZero() { + t.Fatalf("record not filled in: %+v", rec) + } + got, err := s.Get(rec.ID) + if err != nil { + t.Fatal(err) + } + if got.ID != rec.ID || got.Owner != "operator" || string(got.Detail) != `{"x":1}` { + t.Fatalf("Get = %+v", got) + } + if _, err := os.Stat(filepath.Join(Dir(dir), rec.ID, RecordName)); err != nil { + t.Fatal(err) + } + if _, err := s.Get("nope"); !errors.Is(err, ErrNotFound) { + t.Fatalf("Get missing = %v", err) + } + if _, err := s.Get("../escape"); !errors.Is(err, ErrNotFound) { + t.Fatalf("Get invalid id = %v", err) + } + entries := readIndex(t, dir) + if len(entries) != 1 || entries[0].ID != rec.ID || entries[0].Status != StatusAccepted { + t.Fatalf("index = %+v", entries) + } +} + +func TestUpdateTimestampsAndTerminalGuard(t *testing.T) { + s, dir := newStore(t) + rec, _, _ := s.Create(Record{}) + run, err := s.Update(rec.ID, func(r *Record) error { r.Status = StatusRunning; return nil }) + if err != nil { + t.Fatal(err) + } + if run.StartedAt == nil || run.FinishedAt != nil { + t.Fatalf("running timestamps = %+v", run) + } + done, err := s.Update(rec.ID, func(r *Record) error { + r.Status = StatusCompleted + r.Reason = "ok" + r.ID = "forged" + return nil + }) + if err != nil { + t.Fatal(err) + } + if done.ID != rec.ID || done.FinishedAt == nil || !done.FinishedAt.After(*done.StartedAt) || done.Reason != "ok" { + t.Fatalf("completed = %+v", done) + } + if _, err := s.Update(rec.ID, func(r *Record) error { r.Status = StatusRunning; return nil }); err == nil || !strings.Contains(err.Error(), "already completed") { + t.Fatalf("leaving terminal: %v", err) + } + // Reason may still be amended on a terminal record. + if _, err := s.Update(rec.ID, func(r *Record) error { r.Reason = "ok; late note"; return nil }); err != nil { + t.Fatal(err) + } + if _, err := s.Update(rec.ID, func(r *Record) error { r.Status = "bogus"; return nil }); err == nil || !strings.Contains(err.Error(), "invalid status") { + t.Fatalf("invalid status: %v", err) + } + boom := errors.New("boom") + if _, err := s.Update(rec.ID, func(r *Record) error { return boom }); !errors.Is(err, boom) { + t.Fatalf("fn error: %v", err) + } + if _, err := s.Update("missing", func(r *Record) error { return nil }); !errors.Is(err, ErrNotFound) { + t.Fatalf("missing: %v", err) + } + statuses := []string{} + for _, e := range readIndex(t, dir) { + statuses = append(statuses, e.Status) + } + if want := "accepted running completed completed"; strings.Join(statuses, " ") != want { + t.Fatalf("index statuses = %v", statuses) + } +} + +func TestIdempotencyAcrossReopen(t *testing.T) { + s, dir := newStore(t) + key := DeriveIdempotencyKey("operator", "k1") + if key == "" || key == DeriveIdempotencyKey("other", "k1") || DeriveIdempotencyKey("operator", " ") != "" { + t.Fatalf("DeriveIdempotencyKey scoping broken") + } + first, created, err := s.Create(Record{IdempotencyKey: key}) + if err != nil || !created { + t.Fatal(err, created) + } + if _, err := s.Update(first.ID, func(r *Record) error { r.Status = StatusFailed; return nil }); err != nil { + t.Fatal(err) + } + again, created, err := s.Create(Record{IdempotencyKey: key}) + if err != nil || created || again.ID != first.ID || again.Status != StatusFailed { + t.Fatalf("replay = %+v created=%v err=%v", again, created, err) + } + other, created, _ := s.Create(Record{IdempotencyKey: DeriveIdempotencyKey("operator", "k2")}) + if !created || other.ID == first.ID { + t.Fatalf("different key reused record") + } + reopened, err := Open(dir) + if err != nil { + t.Fatal(err) + } + replay, created, err := reopened.Create(Record{IdempotencyKey: key}) + if err != nil || created || replay.ID != first.ID { + t.Fatalf("after reopen = %+v created=%v err=%v", replay, created, err) + } +} + +func TestListAndReconcile(t *testing.T) { + s, dir := newStore(t) + a, _, _ := s.Create(Record{}) + b, _, _ := s.Create(Record{}) + c, _, _ := s.Create(Record{}) + s.Update(b.ID, func(r *Record) error { r.Status = StatusRunning; return nil }) + s.Update(c.ID, func(r *Record) error { r.Status = StatusCompleted; return nil }) + // A directory with artifacts but no record is skipped, not an error. + if err := os.MkdirAll(filepath.Join(Dir(dir), "run_orphan"), 0o770); err != nil { + t.Fatal(err) + } + list, err := s.List() + if err != nil { + t.Fatal(err) + } + if len(list) != 3 || list[0].ID != a.ID || list[1].ID != b.ID || list[2].ID != c.ID { + t.Fatalf("List = %+v", list) + } + changed, err := s.Reconcile("restarted") + if err != nil { + t.Fatal(err) + } + if len(changed) != 2 || changed[0].ID != a.ID || changed[1].ID != b.ID { + t.Fatalf("Reconcile changed %+v", changed) + } + for _, id := range []string{a.ID, b.ID} { + rec, _ := s.Get(id) + if rec.Status != StatusUnfinished || rec.Reason != "restarted" || rec.FinishedAt == nil { + t.Fatalf("%s = %+v", id, rec) + } + } + if rec, _ := s.Get(c.ID); rec.Status != StatusCompleted { + t.Fatalf("completed record touched: %+v", rec) + } + if again, _ := s.Reconcile("x"); len(again) != 0 { + t.Fatalf("second reconcile changed %+v", again) + } + empty := &Store{dir: filepath.Join(t.TempDir(), "none"), Now: time.Now, NewID: newID} + if list, err := empty.List(); err != nil || list != nil { + t.Fatalf("missing dir List = %v, %v", list, err) + } +} + +func TestCorruptRecordIsAnError(t *testing.T) { + s, dir := newStore(t) + rec, _, _ := s.Create(Record{}) + if err := os.WriteFile(filepath.Join(Dir(dir), rec.ID, RecordName), []byte("{"), 0o660); err != nil { + t.Fatal(err) + } + if _, err := s.Get(rec.ID); err == nil || errors.Is(err, ErrNotFound) { + t.Fatalf("corrupt Get = %v", err) + } + if _, err := s.List(); err == nil { + t.Fatal("corrupt List succeeded") + } + if _, err := Open(dir); err == nil { + t.Fatal("Open over a corrupt record succeeded") + } +} + +func TestOpenFailsOnUnwritableWorkDir(t *testing.T) { + file := filepath.Join(t.TempDir(), "file") + if err := os.WriteFile(file, nil, 0o600); err != nil { + t.Fatal(err) + } + if _, err := Open(file); err == nil { + t.Fatal("Open under a file succeeded") + } +} + +func TestStatusSets(t *testing.T) { + for _, st := range []string{StatusCompleted, StatusFailed, StatusCancelled, StatusUnfinished, StatusUnsupported} { + if !Terminal(st) || !Valid(st) { + t.Errorf("%s should be terminal and valid", st) + } + } + for _, st := range []string{StatusAccepted, StatusRunning, StatusWaiting} { + if Terminal(st) || !Valid(st) { + t.Errorf("%s should be valid and not terminal", st) + } + } + if Valid("") || Valid("done") { + t.Error("unknown statuses accepted") + } + if !validID(newID()) || validID("") || validID(strings.Repeat("a", maxIDLen+1)) || validID("A") { + t.Error("validID") + } +} + +func readIndex(t *testing.T, workDir string) []IndexEntry { + t.Helper() + f, err := os.Open(filepath.Join(Dir(workDir), IndexName)) + if err != nil { + t.Fatal(err) + } + defer f.Close() + var out []IndexEntry + sc := bufio.NewScanner(f) + for sc.Scan() { + var e IndexEntry + if err := json.Unmarshal(sc.Bytes(), &e); err != nil { + t.Fatal(err) + } + out = append(out, e) + } + return out +} + +func TestUpdateRejectsUnknownStatus(t *testing.T) { + s, _ := newStore(t) + rec, _, _ := s.Create(Record{}) + if _, err := s.Update(rec.ID, func(r *Record) error { r.Status = "paused"; return nil }); err == nil || !strings.Contains(err.Error(), "invalid status") { + t.Fatalf("Update with unknown status = %v", err) + } + if got, _ := s.Get(rec.ID); got.Status != StatusAccepted { + t.Fatalf("rejected update was written: %+v", got) + } +} + +func TestInvalidIDsAreNotFound(t *testing.T) { + s, _ := newStore(t) + for _, id := range []string{"Run_ABC", "run/x", "run x", strings.Repeat("a", maxIDLen+1)} { + if _, err := s.Get(id); !errors.Is(err, ErrNotFound) { + t.Errorf("Get(%q) = %v, want ErrNotFound", id, err) + } + } +} + +// Filesystem obstacles in the item's directory surface as errors rather +// than a half-written record: the item dir is a file, the temp file is a +// directory, the record is a non-empty directory, the index is a directory. +func TestCreateReportsWriteObstacles(t *testing.T) { + cases := map[string]func(t *testing.T, dir, id string){ + "item dir is a file": func(t *testing.T, dir, id string) { + if err := os.WriteFile(filepath.Join(Dir(dir), id), nil, 0o600); err != nil { + t.Fatal(err) + } + }, + "temp file is a directory": func(t *testing.T, dir, id string) { + if err := os.MkdirAll(filepath.Join(Dir(dir), id, RecordName+".tmp"), 0o770); err != nil { + t.Fatal(err) + } + }, + "record is a non-empty directory": func(t *testing.T, dir, id string) { + if err := os.MkdirAll(filepath.Join(Dir(dir), id, RecordName, "child"), 0o770); err != nil { + t.Fatal(err) + } + }, + "index is a directory": func(t *testing.T, dir, id string) { + if err := os.MkdirAll(filepath.Join(Dir(dir), IndexName), 0o770); err != nil { + t.Fatal(err) + } + }, + } + for name, obstruct := range cases { + t.Run(name, func(t *testing.T) { + s, dir := newStore(t) + obstruct(t, dir, s.NewID()) + s.NewID = func() string { return "run_" + strings.Repeat("0", 11) + "a" } + if _, _, err := s.Create(Record{}); err == nil { + t.Fatal("Create succeeded through the obstacle") + } + }) + } +} + +func TestUnreadableRecordIsAnErrorNotMissing(t *testing.T) { + s, dir := newStore(t) + rec, _, _ := s.Create(Record{}) + // A record that is a directory cannot be read; it is not ErrNotFound. + if err := os.Remove(filepath.Join(Dir(dir), rec.ID, RecordName)); err != nil { + t.Fatal(err) + } + if err := os.Mkdir(filepath.Join(Dir(dir), rec.ID, RecordName), 0o770); err != nil { + t.Fatal(err) + } + if _, err := s.Get(rec.ID); err == nil || errors.Is(err, ErrNotFound) { + t.Fatalf("Get = %v, want a read error", err) + } + if _, err := s.List(); err == nil || errors.Is(err, ErrNotFound) { + t.Fatalf("List = %v, want a read error", err) + } + if _, err := s.Reconcile("restart"); err == nil { + t.Fatal("Reconcile succeeded over an unreadable record") + } +} + +func TestReconcileReportsWriteFailure(t *testing.T) { + s, dir := newStore(t) + rec, _, _ := s.Create(Record{}) + if err := os.Mkdir(filepath.Join(Dir(dir), rec.ID, RecordName+".tmp"), 0o770); err != nil { + t.Fatal(err) + } + changed, err := s.Reconcile("restart") + if err == nil || len(changed) != 0 { + t.Fatalf("Reconcile = %+v, %v; want a write error", changed, err) + } + if got, _ := s.Get(rec.ID); got.Status != StatusAccepted { + t.Fatalf("record moved despite the failed write: %+v", got) + } +} + +func TestListFailsWhenDirIsAFile(t *testing.T) { + file := filepath.Join(t.TempDir(), "runs") + if err := os.WriteFile(file, nil, 0o600); err != nil { + t.Fatal(err) + } + s := &Store{dir: file, keys: map[string]string{}, Now: time.Now, NewID: newID} + if _, err := s.List(); err == nil || errors.Is(err, ErrNotFound) { + t.Fatalf("List over a file = %v", err) + } +} + +func TestListBreaksCreatedAtTiesByID(t *testing.T) { + s, _ := newStore(t) + fixed := time.Date(2026, 11, 1, 12, 0, 0, 0, time.UTC) + s.Now = func() time.Time { return fixed } + ids := []string{"run_00000000000c", "run_00000000000a", "run_00000000000b"} + next := 0 + s.NewID = func() string { id := ids[next]; next++; return id } + for range ids { + if _, _, err := s.Create(Record{}); err != nil { + t.Fatal(err) + } + } + list, err := s.List() + if err != nil { + t.Fatal(err) + } + var got []string + for _, r := range list { + got = append(got, r.ID) + } + if strings.Join(got, ",") != "run_00000000000a,run_00000000000b,run_00000000000c" { + t.Fatalf("List order = %v", got) + } +} + +func TestNewIDShape(t *testing.T) { + a, b := newID(), newID() + if a == b || !validID(a) || !strings.HasPrefix(a, "run_") { + t.Fatalf("newID = %q, %q", a, b) + } +} diff --git a/src/crux/serve/runs.go b/src/crux/serve/runs.go new file mode 100644 index 0000000000..13933037e6 --- /dev/null +++ b/src/crux/serve/runs.go @@ -0,0 +1,121 @@ +package serve + +import ( + "context" + "errors" + "net/http" + + "github.com/hivecommons/hive/crux/api" + "github.com/hivecommons/hive/crux/runs" +) + +// runsOwner is the principal a contained run is recorded under. +// +// TODO(S0): switch to CallerFrom(r.Context()) once the caller-principal +// change lands; until then every authenticated caller is the operator, +// which is exactly what the bearer-token check already establishes. +func runsOwner(r *http.Request) string { + return "operator" +} + +// registerRuns mounts the contained-run family (RFC crux#114 S2 + S7). +// The routes are always present so a server without a backend answers +// with a clear not_supported instead of a bare 404. +func (s *Server) registerRuns(mux *http.ServeMux) { + mux.HandleFunc("POST "+api.PathRuns, s.handleRunsCreate) + mux.HandleFunc("GET "+api.PathRuns+"/{id}", s.handleRunsGet) + mux.HandleFunc("POST "+api.PathRuns+"/{id}/cancel", s.handleRunsCancel) +} + +// runsReady reports whether the run service exists; when it does not, a +// 501 has been written. A service without a backend still serves saved +// records, so only Create checks Configured separately. +func (s *Server) runsReady(w http.ResponseWriter) bool { + if s.Runs == nil { + s.writeError(w, http.StatusNotImplemented, api.CodeNotSupported, "contained runs are not enabled on this server") + return false + } + return true +} + +func (s *Server) handleRunsCreate(w http.ResponseWriter, r *http.Request) { + if !s.runsReady(w) { + return + } + var req api.ContainedRunRequest + if !s.readJSON(w, r, &req) { + return + } + run, created, err := s.Runs.Create(s.LaunchContext, runsOwner(r), req) + if err != nil { + s.writeRunsError(w, err) + return + } + if !created { + // Idempotency hit: the earlier record, whatever state it is in. + s.writeJSON(w, http.StatusOK, run) + return + } + if req.Detach { + s.writeJSON(w, http.StatusAccepted, run) + return + } + // The run itself is bound to LaunchContext; only the wait is bound to + // the request, so a caller that goes away leaves the run in flight. + run, err = s.Runs.Wait(r.Context(), run.ID) + if err != nil { + if errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded) { + return + } + s.writeRunsError(w, err) + return + } + s.writeJSON(w, http.StatusOK, run) +} + +func (s *Server) handleRunsGet(w http.ResponseWriter, r *http.Request) { + if !s.runsReady(w) { + return + } + run, err := s.Runs.Get(r.PathValue("id")) + if err != nil { + s.writeRunsError(w, err) + return + } + s.writeJSON(w, http.StatusOK, run) +} + +func (s *Server) handleRunsCancel(w http.ResponseWriter, r *http.Request) { + if !s.runsReady(w) { + return + } + run, err := s.Runs.Cancel(r.Context(), r.PathValue("id")) + if err != nil { + s.writeRunsError(w, err) + return + } + s.writeJSON(w, http.StatusOK, run) +} + +// writeRunsError maps the run service's typed errors onto wire codes. The +// refusals keep their own codes so a caller can tell "you asked for +// something wrong" from "this backend cannot enforce that". +func (s *Server) writeRunsError(w http.ResponseWriter, err error) { + var reqErr *runs.RequestError + var forbidden *runs.ForbiddenError + var unsupported *runs.UnsupportedError + switch { + case errors.Is(err, runs.ErrNotConfigured): + s.writeError(w, http.StatusNotImplemented, api.CodeNotSupported, err.Error()) + case errors.Is(err, runs.ErrNotFound): + s.writeError(w, http.StatusNotFound, api.CodeNotFound, "run not found") + case errors.As(err, &reqErr): + s.writeError(w, http.StatusBadRequest, api.CodeBadRequest, err.Error()) + case errors.As(err, &forbidden): + s.writeError(w, http.StatusForbidden, api.CodeForbidden, err.Error()) + case errors.As(err, &unsupported): + s.writeError(w, http.StatusNotImplemented, api.CodeUnsupported, err.Error()) + default: + s.writeError(w, http.StatusInternalServerError, api.CodeRuntime, err.Error()) + } +} diff --git a/src/crux/serve/runs_test.go b/src/crux/serve/runs_test.go new file mode 100644 index 0000000000..bedfb47ed2 --- /dev/null +++ b/src/crux/serve/runs_test.go @@ -0,0 +1,131 @@ +package serve + +import ( + "context" + "net/http" + "os" + "path/filepath" + "testing" + "time" + + "github.com/hivecommons/hive/crux/api" + "github.com/hivecommons/hive/crux/runs" + "github.com/hivecommons/hive/crux/runstate" + "github.com/hivecommons/hive/crux/sandbox" +) + +type runsLauncher func(ctx context.Context, spec sandbox.LaunchSpec) (sandbox.Result, error) + +func (l runsLauncher) Run(ctx context.Context, spec sandbox.LaunchSpec) (sandbox.Result, error) { + return l(ctx, spec) +} + +// newRunsServer wires a run service with a fake launcher onto a family +// server; the workspace root holds one directory, "proj". +func newRunsServer(t *testing.T, launcher runsLauncher) (*famServer, string) { + t.Helper() + f := newFamServer(t) + store, err := runstate.Open(t.TempDir()) + if err != nil { + t.Fatal(err) + } + root := t.TempDir() + ws := filepath.Join(root, "proj") + if err := os.MkdirAll(ws, 0o755); err != nil { + t.Fatal(err) + } + backend := &runs.Backend{Name: "fake", Launcher: launcher, Capabilities: runs.Capabilities{NetworkNone: true}} + f.srv.Runs = runs.New(store, backend, runs.Config{Image: "img", WorkspaceRoots: []string{root}}) + return f, ws +} + +func TestRunsRoutesAnswerNotSupportedWithoutAService(t *testing.T) { + f := newFamServer(t) + f.expectCode(http.MethodPost, api.PathRuns, api.ContainedRunRequest{Command: []string{"x"}}, http.StatusNotImplemented, api.CodeNotSupported) + f.expectCode(http.MethodGet, api.RunPath("run_x"), nil, http.StatusNotImplemented, api.CodeNotSupported) + f.expectCode(http.MethodPost, api.RunCancelPath("run_x"), nil, http.StatusNotImplemented, api.CodeNotSupported) +} + +func TestRunsWithoutABackendStillServesRecords(t *testing.T) { + f := newFamServer(t) + store, err := runstate.Open(t.TempDir()) + if err != nil { + t.Fatal(err) + } + f.srv.Runs = runs.New(store, nil, runs.Config{}) + rec, _, err := store.Create(runstate.Record{Owner: "operator"}) + if err != nil { + t.Fatal(err) + } + f.expectCode(http.MethodPost, api.PathRuns, api.ContainedRunRequest{Command: []string{"x"}}, http.StatusNotImplemented, api.CodeNotSupported) + var run api.ContainedRun + f.expect(http.MethodGet, api.RunPath(rec.ID), nil, http.StatusOK, &run) + if run.ID != rec.ID || run.Status != api.RunAccepted { + t.Fatalf("GET = %+v", run) + } +} + +func TestRunsCreateWaitsAndReturnsTheRecord(t *testing.T) { + f, ws := newRunsServer(t, func(_ context.Context, spec sandbox.LaunchSpec) (sandbox.Result, error) { + return sandbox.Result{Stdout: "ran " + spec.Command[0]}, nil + }) + req := api.ContainedRunRequest{WorkspacePath: ws, Command: []string{"make", "test"}, IdempotencyKey: "k"} + var run api.ContainedRun + f.expect(http.MethodPost, api.PathRuns, req, http.StatusOK, &run) + if run.Status != api.RunCompleted || run.Stdout != "ran make" || run.ExitCode == nil || *run.ExitCode != 0 || run.Owner != "operator" { + t.Fatalf("POST = %+v", run) + } + var again api.ContainedRun + f.expect(http.MethodPost, api.PathRuns, req, http.StatusOK, &again) + if again.ID != run.ID { + t.Fatalf("idempotent replay returned %s, want %s", again.ID, run.ID) + } + var got api.ContainedRun + f.expect(http.MethodGet, api.RunPath(run.ID), nil, http.StatusOK, &got) + if got.ID != run.ID || got.Status != api.RunCompleted { + t.Fatalf("GET = %+v", got) + } + var late api.ContainedRun + f.expect(http.MethodPost, api.RunCancelPath(run.ID), nil, http.StatusOK, &late) + if !late.AlreadyFinished || late.Status != api.RunCompleted { + t.Fatalf("late cancel = %+v", late) + } +} + +func TestRunsDetachAndCancel(t *testing.T) { + started := make(chan struct{}, 1) + f, ws := newRunsServer(t, func(ctx context.Context, _ sandbox.LaunchSpec) (sandbox.Result, error) { + started <- struct{}{} + <-ctx.Done() + return sandbox.Result{ExitCode: -1}, ctx.Err() + }) + var run api.ContainedRun + f.expect(http.MethodPost, api.PathRuns, api.ContainedRunRequest{WorkspacePath: ws, Command: []string{"sleep"}, Detach: true}, http.StatusAccepted, &run) + if run.Status != api.RunAccepted || run.ID == "" { + t.Fatalf("detached = %+v", run) + } + select { + case <-started: + case <-time.After(10 * time.Second): + t.Fatal("launcher never started") + } + var cancelled api.ContainedRun + f.expect(http.MethodPost, api.RunCancelPath(run.ID), nil, http.StatusOK, &cancelled) + if cancelled.Status != api.RunCancelled || cancelled.AlreadyFinished || cancelled.ExitCode != nil { + t.Fatalf("cancel = %+v", cancelled) + } +} + +func TestRunsErrorCodes(t *testing.T) { + f, ws := newRunsServer(t, func(context.Context, sandbox.LaunchSpec) (sandbox.Result, error) { + return sandbox.Result{}, nil + }) + f.expectCode(http.MethodPost, api.PathRuns, "{not json", http.StatusBadRequest, api.CodeBadRequest) + f.expectCode(http.MethodPost, api.PathRuns, api.ContainedRunRequest{WorkspacePath: ws}, http.StatusBadRequest, api.CodeBadRequest) + f.expectCode(http.MethodPost, api.PathRuns, api.ContainedRunRequest{WorkspacePath: ws, Command: []string{"x"}, Profile: api.RunProfileAgent}, http.StatusNotImplemented, api.CodeUnsupported) + f.expectCode(http.MethodPost, api.PathRuns, api.ContainedRunRequest{WorkspacePath: ws, Command: []string{"x"}, Network: api.RunNetworkRestricted}, http.StatusNotImplemented, api.CodeUnsupported) + f.expectCode(http.MethodPost, api.PathRuns, api.ContainedRunRequest{Checkout: "chk_1", Command: []string{"x"}}, http.StatusNotImplemented, api.CodeUnsupported) + f.expectCode(http.MethodPost, api.PathRuns, api.ContainedRunRequest{WorkspacePath: "/elsewhere", Command: []string{"x"}}, http.StatusForbidden, api.CodeForbidden) + f.expectCode(http.MethodGet, api.RunPath("run_missing"), nil, http.StatusNotFound, api.CodeNotFound) + f.expectCode(http.MethodPost, api.RunCancelPath("run_missing"), nil, http.StatusNotFound, api.CodeNotFound) +} diff --git a/src/crux/serve/serve.go b/src/crux/serve/serve.go index c020ef905d..813e2b778d 100644 --- a/src/crux/serve/serve.go +++ b/src/crux/serve/serve.go @@ -38,6 +38,7 @@ import ( "github.com/hivecommons/hive/crux/checkout" "github.com/hivecommons/hive/crux/config" "github.com/hivecommons/hive/crux/lanes" + "github.com/hivecommons/hive/crux/runs" ) const ( @@ -109,6 +110,10 @@ type Server struct { // (api.PathCheckouts); nil answers those routes 501. Checkouts *checkout.Service + // Runs, when set, serves the contained-run family (RFC crux#114 S2 + + // S7); nil answers those routes with not_supported. + Runs *runs.Service + now func() time.Time started time.Time @@ -166,6 +171,7 @@ func (s *Server) Handler() http.Handler { mux.HandleFunc("GET "+api.PathEvents, s.handleEvents) s.registerFamilies(mux) s.registerCheckouts(mux) + s.registerRuns(mux) return s.laneHandler(s.authenticate(mux)) } diff --git a/src/docs/agent-configuration.md b/src/docs/agent-configuration.md index 49d77ec494..bb878179e6 100644 --- a/src/docs/agent-configuration.md +++ b/src/docs/agent-configuration.md @@ -341,6 +341,9 @@ spec omits `launch_cmd`, Hive still builds the backend command normally. max_rss_mb: 1536 # policy: recycle this agent's CLI session (a normal max_age: 6h # restart) once idle at the prompt and over the RSS min_idle: 2m # or age budget; enabled: false turns it off + cli_memory: # optional override of the fleet agents.cli_memory + auto_memory: false # policy: CLI auto-memory (Claude MEMORY.md, Codex + clear_on_kick: false # memories, Copilot memory) off; wipe before each kick restart_strategy: immediate # how to bring a dead session back beads_dir: /data/beads/scanner # work-record (bead) storage; default per-agent replicas: 3 # materialize scanner, scanner-2, scanner-3 (max 5) @@ -657,6 +660,43 @@ Two rules of thumb: Only `POST /v1/messages` is translated into an OpenAI `/v1/chat/completions` call. The Claude CLI also talks to its Anthropic host for housekeeping — telemetry batches (`/api/event_logging/...`), error reports, `POST /v1/messages/count_tokens` — and none of that has a meaning to an OpenAI-compatible gateway; forwarding it used to cost a gateway `400 Missing required parameter: 'messages'` per call, charged against the provider's request rate limit (roughly two failures per real completion in practice). The translator and the MITM reroute now answer those locally: `count_tokens` returns a chars-based estimate, anything under `/api/` returns `{}`, and any other path is a 404 in Anthropic error shape with a `WARN` log line naming the method and path, so a new CLI endpoint shows up in the hive log rather than as gateway noise. Inference-routed `claude` sessions are additionally launched with `DISABLE_TELEMETRY=1`, `DISABLE_ERROR_REPORTING=1`, `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1`, and `CLAUDE_CODE_AUTO_MODE_SERVER=0`; subscription sessions are not. The last one matters for Claude Code's [auto-mode classifier](https://code.claude.com/docs/en/auto-mode-classifier-billing): the CLI otherwise asks the inference host for a server-side safety verdict (`safeguards` field in, `safeguard_results` out) that an OpenAI-compatible gateway can never return, then halts the session on an interactive "this session isn't eligible because your requests go through 127.0.0.1:18444 … Enter to continue" notice. With the variable set the CLI runs its own classifier requests through the translator like any other call. Should the notice still appear (for example from a settings file that re-enables the server check), the lifetime prompt watcher presses Enter for it. +### Per-agent homes: what is shared and what is private + +Each per-UID agent runs with its own durable `HOME` under `/data/home/agents/<name>`. "One login authenticates the fleet" is implemented by *bridging* — symlinks from the per-agent home back to the same path under the shared `/data/home` — and the bridge list is deliberately narrow: + +| Path under the agent home | Kind | Shared? | Why | +|---|---|---|---| +| `.config/`, `.codex/`, `.cache/` | whole directory | yes | credential/config state only (gh `hosts.yml`, goose keys, codex auth) and tool caches; codex session state lives under a per-agent `CODEX_HOME` | +| `.claude/.credentials.json`, `.claude/settings.json` | file | yes | the Claude OAuth token and the fleet-wide settings hive seeds | +| `.claude/projects/`, `.claude/todos/`, `.claude/history.jsonl` | per-agent | **no** | transcripts, todos, and Claude Code's auto-memory (`projects/-data-agents-<name>/memory/MEMORY.md`, keyed by the agent's cwd) | +| `.gemini/antigravity-cli/`, `.gemini/settings.json`, `oauth_creds.json`, `google_accounts.json`, `installation_id` | dir / file | yes | agy and Gemini CLI sign-in and settings | +| `.gemini/GEMINI.md`, `.gemini/tmp/` | per-agent | **no** | Gemini's saved memory and session checkpoints | +| `.bob/settings.json`, `.bob/settings/` | file / dir | yes | the auth-method/provider pins hive asserts for every bob agent | +| `.bob/tmp/`, `.bob/trustedFolders.json` | per-agent | **no** | chat recordings and folder trust | +| `.copilot/config.json` | file | yes | the Copilot CLI token map | +| `.copilot/session-state/` | per-agent | **no** | Copilot CLI transcripts | +| `.claude.json`, `.bash_history`, `.npm/`, `.local/`, `.gitconfig` | per-agent | **no** | contended session identity, shell history, npm cache, XDG data/state, git identity | + +Before [#17031](https://github.com/hivecommons/hive/issues/17031) `.claude`, `.gemini` and `.bob` were bridged whole, so every agent's CLI state sat in one tree that any agent could read and rewrite: the user-level `~/.claude/CLAUDE.md`, `history.jsonl` and `todos/` were a single shared copy, and each agent's cwd-keyed auto-memory (`projects/-data-agents-<name>/memory/MEMORY.md`, per-agent by path) was writable by every other agent and persisted on the PVC forever. Provisioning now retires those whole-directory bridges on the next launch, keeps only the login/settings entries above, and never deletes or moves anything under `/data/home`: a pre-existing shared memory store is left in place and logged once (`shared CLI home still holds a persistent memory store …`) so you can review or drain it ([#17033](https://github.com/hivecommons/hive/issues/17033)) before removing it by hand. The dashboard's token/cost scanners (`data.claude_sessions_dir`, `data.bob_sessions_dir`, `data.copilot_sessions_dir`) walk the shared path **and** every `/data/home/agents/*/…` sibling, attributing each per-agent tree to its owner, so cost accounting does not regress. `HIVE_SHARED_AGENT_HOME=1` restores the legacy single shared `HOME` for every agent (and with it the shared memory). + +### CLI auto-memory (`agents.cli_memory`) + +Subscription CLIs keep their own long-lived "memory" next to the transcripts: Claude Code's auto-memory (`~/.claude/projects/-data-agents-<name>/memory/MEMORY.md`), Codex memories (`$CODEX_HOME/memories/`), Copilot CLI's `memory` setting, and Gemini's `~/.gemini/GEMINI.md`. Hive agents already get their durable context from beads, the knowledge store, and the kick prompt, so a hidden per-CLI notebook mostly accumulates stale one-off inferences ([#17032](https://github.com/hivecommons/hive/issues/17032)). The `agents.cli_memory` block controls it fleet-wide, and each agent may override it with its own `cli_memory:` block: + +```yaml +agents: + cli_memory: + auto_memory: false # default false: pin every CLI's auto-memory feature off + clear_on_kick: false # default false: true wipes this agent's memory stores before each kick +``` + +| Key | Default | Effect | +|---|---|---| +| `auto_memory` | `false` | When false hive pins the vendor switch off at launch: Claude Code gets `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1` in its environment ([docs](https://code.claude.com/docs/en/memory)); Codex gets `[features] memories = false` merged into `$CODEX_HOME/config.toml` ([docs](https://developers.openai.com/codex/memories)); Copilot CLI gets `"memory": false` in its per-agent `~/.copilot/settings.json` (`copilot help config`). `true` writes the opposite pin so an operator's own setting is never silently shadowed. Gemini CLI has no equivalent switch. | +| `clear_on_kick` | `false` | Before every non-resume kick (next to the `/clear` sent by `clear_on_kick`), remove this agent's `~/.claude/projects/*/memory/`, `$CODEX_HOME/memories*/`, and `~/.gemini/GEMINI.md`. Only the per-agent home under `/data/home/agents/<name>` is touched; nothing under the shared `/data/home` is removed, and agents running with `HIVE_SHARED_AGENT_HOME=1` or as uid 0 are skipped. Copilot memory is server-side and has no local store. | + +Set `auto_memory: true` on a single agent to let it keep a private notebook while the rest of the fleet stays stateless between kicks. The two knobs are independent: `auto_memory: true` with `clear_on_kick: true` gives a memory that lives for exactly one kick. + Every Model Gateway (and the bob backend) also accepts an optional `key_name` — a human-chosen LABEL for the configured key, e.g. `key_name: openrouter-prod-key`. It is safe-to-show metadata, not a secret: the dashboard's gateway row displays it as "Using key: `<name>`", or "(unnamed)" when no label is set, so operators can tell keys apart without ever seeing the value. For gateway keys, the row and settings/status APIs also expose `keySHA256`, the lowercase SHA-256 of the exact effective key string Hive will inject through the inference proxy; this lets operators compare Hive with LiteLLM/OpenRouter key-hash displays without revealing the secret. Saving a replacement key refreshes live inference proxy routes for running agents, so the next kick uses the new key without an agent restart. See [`inference-backends.md`](../../docs/inference-backends.md) for a full YAML example. ### Claude Managed Agents hosted execution diff --git a/src/docs/agent-knowledge-and-memory.md b/src/docs/agent-knowledge-and-memory.md new file mode 100644 index 0000000000..7528d9d3f7 --- /dev/null +++ b/src/docs/agent-knowledge-and-memory.md @@ -0,0 +1,238 @@ +# How Hive injects knowledge and memory into agents + +> Written to answer the 2026-11-05 community-meeting question "how does +> Hive's memory/knowledge injection work today?". It describes `v5` as of +> this page's merge; the [Known gaps](#known-gaps--in-progress) section links +> the work that will change the memory half. + +Hive agents receive context from **three distinct layers**, and only one of +them is Hive's own: + +| Layer | Who owns it | Where it lives | Hive's role | +|---|---|---|---| +| **Knowledge** — curated facts about the repos and the fleet | Hive (`pkg/knowledge`) | File vaults under `/data/knowledge/…`, optional HTTP wiki layers | Selects a few facts per kick and **pushes** them into the kick prompt; also serves them for **pull** via API/MCP/`hivectl` | +| **Conversation** — the current chat in the CLI pane | The CLI | In the CLI process | Resets it before every kick (`/clear`) | +| **CLI memory** — the CLI's own persistent, cross-session notes (Claude Code auto-memory, Codex memories, Gemini `GEMINI.md`, …) | The CLI | Dot-directories under the agent's `HOME` | **None.** Hive neither feeds, reads, filters nor clears it; it only decides which agents share the directory | + +The confusion at the meeting was between layers 2 and 3: "every agent clears +its context before it runs" is true of the conversation and false of CLI +memory. + +## 1. Knowledge: the kick primer (push) + +``` + knowledge.vaults / git_sources / connectors / bead_synthesizer vault + (FileStore per source; HTTP wiki layers for personal/project/org/community) + │ + registerKnowledgeStores (cmd/hive/boot_knowledge_primer.go) + ▼ + ┌───────────────── Scheduler.primeKnowledge (pkg/scheduler/kick_priming.go) ───┐ + │ 1. extractKeywords ← titles + labels of the agent's first │ + │ maxIssuesToPrime (=5) queued issues │ + │ 2. scope ← knowledge.agent_scopes[<agent>] (or base agent for a replica) │ + │ 3. Primer.PrimeScoped (pkg/knowledge/primer.go) │ + │ search every layer/store → merge by layer precedence → │ + │ FilterByLifecycle (approved only) → scope.Filter → │ + │ Fisher-Rao rerank → type priority → cap at max_facts (25) → │ + │ expandWithGraph (never past the scope) → Context7 hints │ + │ 4. PrimedKnowledge.Render (primer_render.go): "# Relevant Knowledge", │ + │ grouped by type, whole facts dropped past max_bytes (4096), │ + │ "_… truncated: N facts / M bytes omitted (size cap)._" marker │ + └──────────────────────────────────────────────────────────────────────────────┘ + │ + templates.go: skills section + AGENTS.md section + knowledge section + substituted into the agent's kick template; lane kicks (lane_messages.go) + append the knowledge section for scanner / quality / architect / <agent> + ▼ + tmux: [/clear ⏎] then the kick text ⏎ (crux/agent/manager_kick.go) +``` + +**Where the facts come from.** Everything the primer searches is registered +in `registerKnowledgeStores` (`src/cmd/hive/boot_knowledge_primer.go`): +configured `knowledge.vaults` (personal layer), `knowledge.git_sources` +(layer from config), connector output, the **bead synthesizer vault** +(closed beads from every agent, classified into fact types — the main +organic source on a running hive), plus any HTTP wiki layers in +`knowledge.layers`. The repo's own docs are *not* a source unless you index +them through a git source, connector or code map +([knowledge-curator.md](knowledge-curator.md)). + +**How it is scoped.** + +- *By the work, not the repo:* the query is keywords from the titles and + labels of the agent's first five queued issues (`extractKeywords`, + `isNoiseLabel`). There is no automatic per-repo or per-issue filter; a fact + tagged with another repo can surface if the keywords match. +- *By agent:* `knowledge.agent_scopes.<agent>` is an allow-list of `layers`, + `repos`, `types`, `tags` (`KnowledgeAgentScope` in + `src/pkg/config/knowledge_config.go`). It is applied inside + `Primer.PrimeScoped` *after* the lifecycle filter and can only narrow; graph + expansion never pulls in an out-of-scope fact. A replica inherits its base + agent's entry (`Config.KnowledgeAgentScope`). No entry means unrestricted. +- *By lifecycle:* kicks carry **approved facts only** by default. The kick + primer is built with no `IncludeStates` (`newKnowledgePrimer` in + `src/cmd/hive/main.go`), so `deprecated` and `superseded` never reach a kick + and `agent_scopes.include_states` only widens API/TOC reads that already + asked for those states ([knowledge-lifecycle.md](knowledge-lifecycle.md)). + The one kick-path exception is an agent's **own drafts** (#17076): when the + agent's `agent_scopes` entry lists `draft` (or `all`) in `include_states`, + drafts whose `author:` (or `owner:`) frontmatter is that agent, its base + agent or one of the hive's owner logins are primed too, each marked + `(draft)` in the kick (`kickDraftAuthors` in `kick_priming.go`, + `TOCScope.DraftAuthors`). Drafts by anyone else, and drafts with no author, + are still excluded. + +**Size caps** (all drop whole units, never clip, and leave a visible marker): + +| Block | Cap | Config | +|---|---|---| +| `# Relevant Knowledge` | 25 facts, 4096 bytes (floor 512) | `knowledge.primer.max_facts`, `knowledge.primer.max_bytes` | +| Repo `AGENTS.md` | 8192 bytes (floor 2048), whole sections | `project.agents_md_max_bytes` (`agentsmd.DefaultMaxInjectionBytes`) | +| Declared skills | 8192 bytes, whole skills | `maxSkillsInjectionBytes` in `kick_priming.go` (fixed) | + +**Switches.** `knowledge.enabled` gates the primer only — the bead synthesizer +still writes facts when it is off, they just reach no kick. The dashboard +knowledge toggle registers/unregisters the primer live +(`knowledgePrimerControl`). `knowledge.enabled: false` or an empty keyword set +means the kick simply has no knowledge section. + +## 2. Knowledge: pull access + +Agents (and external tools) can fetch what the primer did not push: +`GET /api/knowledge/toc` and `/api/knowledge/entry/{id}` (pass `agent=` to +apply that agent's scope), `GET /api/knowledge/effective?agent=` to see what +a given agent is allowed to see and why entries are excluded, the public +`POST /mcp/knowledge` MCP (`knowledge_toc`, `knowledge_get`), `hivectl +knowledge search|list`, and `bd kb search` inside the pod. See +[knowledge-toc.md](knowledge-toc.md) and +[public-knowledge-mcp.md](public-knowledge-mcp.md). + +## 3. AGENTS.md / CLAUDE.md: injected by Hive, not read natively + +Each agent's CLI starts in `/data/agents/<name>` (`crux.DefaultWorkDir`), +not inside a repository checkout, so the CLIs' native instruction-file +discovery (`AGENTS.md` for Codex/Copilot, `CLAUDE.md` for Claude Code, +`GEMINI.md`) finds **nothing from the monitored repo** at launch. Repo +instructions reach agents only through the scheduler: `primeAgentsMd` parses +`<project.checkouts_dir>/<repo>/AGENTS.md` for the agent's *primary* repo and +prepends the rendered block to the knowledge section (`templates.go`). Without +`project.checkouts_dir` (or a matching `policies.local_dir`) the block is +empty — see [agents-md.md](agents-md.md). Skills declared on the agent are +prepended the same way ([skills.md](skills.md)); the hive-wide house style +precedes both ([house-style.md](house-style.md)). + +Two instruction files *are* read natively: a user-level +`~/.claude/CLAUDE.md` / `~/.gemini/GEMINI.md` if one exists. Since +[#17031](https://github.com/hivecommons/hive/issues/17031) those files live in +each agent's own `~/.claude` / `~/.gemini` (next section), so such a file +applies to that agent only. + +## 4. CLI memory and conversation: what Hive does and does not touch + +**Conversation.** `clear_on_kick` defaults to `true` (`ClearOnKick`, +`src/pkg/config/config.go`). `deliverKickLocked` in +`src/crux/agent/manager_kick.go` types `/clear` ⏎ before the kick text for +every TUI backend (agy headless starts a new conversation instead). The one +exception is a PR follow-up delivered with `SendResumeKick` +(`pr_session_resume.go`), which deliberately continues the authoring +conversation. `/clear` empties the chat; it does not touch anything on disk. + +**Home layout** (`interactive_home.go`, `manager_env.go`, `manager_homes.go`): + +- Per-UID agents get `HOME=/data/home/agents/<name>` (`AgentHome`, + `interactiveHomePath`) with per-agent `XDG_DATA_HOME`/`XDG_STATE_HOME` under + `~/.local` (`setupAgentXDGDirs`). `/data/home` is the persistent volume. +- `interactiveHomeBridgeDirs` symlinks `.config`, `.codex` and `.cache` from + every per-agent home to the **same** directories under `/data/home`, so one + login authenticates the fleet. Those hold credentials/config and caches only. +- Real per-agent directories with narrow, credential-only bridges inside them + (`perAgentCLIHomes`, [#17031](https://github.com/hivecommons/hive/issues/17031)): + `~/.claude` (only `.credentials.json` and `settings.json` shared — + `projects/` with transcripts and auto-memory, `todos/`, `history.jsonl` and a + user-level `CLAUDE.md` are per-agent), `~/.gemini` (only sign-in files, + `settings.json` and `antigravity-cli/` shared — `GEMINI.md` and `tmp/` + per-agent), `~/.bob` (only `settings.json` / `settings/` shared), `~/.copilot` + (only `config.json` shared, #9444). Also per-agent: `~/.local`, + `.claude.json`, `.npm`, `.gitconfig` (#9478). Codex gets + `CODEX_HOME=/data/home/.codex-<name>` with only `auth.json` symlinked to the + shared login (`setupCodexHome`, `codexHomePath`). Legacy whole-directory + symlinks are retired on the next launch; nothing under `/data/home` is + deleted — a pre-isolation `projects/*/memory` store is logged once for review. + The full table is in [agent-configuration.md](agent-configuration.md#per-agent-homes-what-is-shared-and-what-is-private). +- `HIVE_SHARED_AGENT_HOME=1` forces the legacy single shared home for all. +- Inference (API-routed) agents use throwaway homes under + `/tmp/.claude-inference-home-<name>` that vanish with the pod. +- Contributor containers stage only `.credentials.json` and `settings.json` + into the container (`CLAUDE_STAGE_ALLOWLIST` in the `justfile`, #7836); + transcripts, history and memory stay on the host. This is the one place + memory is isolated by construction. + +**Memory policy** (`agents.cli_memory`, `cli_memory.go`, +[#17032](https://github.com/hivecommons/hive/issues/17032)). `auto_memory` +defaults to **false**: Claude Code is launched with +`CLAUDE_CODE_DISABLE_AUTO_MEMORY=1`, Codex gets `[features] memories = false` +in `$CODEX_HOME/config.toml`, Copilot CLI gets `"memory": false` in its +per-agent `~/.copilot/settings.json`; Gemini has no equivalent switch. +`clear_on_kick` (default false) removes this agent's +`~/.claude/projects/*/memory/`, `$CODEX_HOME/memories*/` and +`~/.gemini/GEMINI.md` before each non-resume kick, next to the `/clear`. Both +keys can be overridden per agent. With both off, what each CLI remembers it +remembers across kicks and pod restarts — but, since #17031, not across +agents. See [agent-configuration.md](agent-configuration.md#cli-auto-memory-agentscli_memory). + +### What persists across what + +Columns: a cadence **kick**; an explicit **`/clear`**; a **pod restart**; a +**new agent** added to the same hive. ✓ = survives / is visible, ✗ = gone / +not visible. + +| | Kick | `/clear` | Pod restart | New agent in same hive | +|---|---|---|---|---| +| **Knowledge** (`# Relevant Knowledge`, AGENTS.md, skills) | re-selected for *this* kick's issues | n/a — re-injected next kick | ✓ vaults on `/data` | ✓ same stores, filtered by its own `agent_scopes` | +| **Conversation** — all CLIs | ✗ (`/clear` first, unless `clear_on_kick: false` or a resume kick) | ✗ | ✗ (CLI relaunched) | ✗ | +| **Claude Code memory** (`~/.claude/projects/-data-agents-<name>/memory/`, `~/.claude/CLAUDE.md`, `history.jsonl`) | ✓ unless `cli_memory.clear_on_kick` (and off by default: `auto_memory: false`) | ✓ | ✓ (`/data/home/agents/<name>/.claude` is persistent) | ✗ per-agent dir (#17031); only `.credentials.json` / `settings.json` shared. Before #17031 the whole tree was one bridged copy any agent could read or rewrite | +| **Codex memory** (`$CODEX_HOME`) | ✓ unless `cli_memory.clear_on_kick` (off by default) | ✓ | ✓ (`/data/home/.codex-<name>`) | ✗ per-agent dir; only `auth.json` shared | +| **Copilot CLI memory/sessions** (`~/.copilot`) | ✓ | ✓ | ✓ | ✗ per-agent dir (#9444); only `config.json` shared | +| **Gemini memory** (`~/.gemini/GEMINI.md`, state) | ✓ unless `cli_memory.clear_on_kick` | ✓ | ✓ | ✗ per-agent dir (#17031); only sign-in files, `settings.json`, `antigravity-cli/` shared | +| **Bob memory/settings** (`~/.bob`) | ✓ | ✓ | ✓ | ✗ per-agent dir (#17031); only `settings.json` / `settings/` shared | + +The dashboard's cost accounting reads `data.claude_sessions_dir` (default +`/data/home/.claude/projects`) **and** every per-agent sibling +`/data/home/agents/*/.claude/projects` (`ClaudeSessionTrees`, +`src/pkg/tokens/agent_home_trees.go`), attributing each per-agent tree to its +owner and falling back to the `-data-agents-<name>` project slug for the +shared tree (`claude_scanner.go`); `bob_sessions_dir` and +`copilot_sessions_dir` work the same way. + +## Known gaps / in progress + +Do not treat the following as current behaviour; follow the links. + +- [#17031](https://github.com/hivecommons/hive/issues/17031) — fixed by + [PR #17039](https://github.com/hivecommons/hive/pull/17039) (per-agent + `.claude`/`.gemini`/`.bob`, described above). Hives upgraded from before it + still hold the old shared store under `/data/home/.claude/projects`; it is + left in place and logged once, remove or drain it by hand. +- [#17032](https://github.com/hivecommons/hive/issues/17032) — done: + `agents.cli_memory.auto_memory` (default off) and + `agents.cli_memory.clear_on_kick`, described above. +- [#17033](https://github.com/hivecommons/hive/issues/17033) — drain CLI + auto-memory into beads/knowledge at session end instead of a hidden + `MEMORY.md` (revives open question 5 of + [design/knowledge-system.md](design/knowledge-system.md)). +- Repo `AGENTS.md` injection still requires `project.checkouts_dir`; nearest- + file (`ParseNearest`) targeting is deferred ([agents-md.md](agents-md.md)). + +Closed history worth knowing: #7836 (contributor `~/.claude` staging), #9444 +(Copilot session-state isolation), #9478 (per-agent `.gitconfig`), #11201 +(`knowledge.agent_scopes`), #12124/#12129 (primer and AGENTS.md size caps), +#10524 (knowledge TOC, lifecycle, suggest). + +## Related + +[design/knowledge-system.md](design/knowledge-system.md) · +[knowledge-curator.md](knowledge-curator.md) · +[knowledge-lifecycle.md](knowledge-lifecycle.md) · +[knowledge-toc.md](knowledge-toc.md) · [agents-md.md](agents-md.md) · +[skills.md](skills.md) · [agent-configuration.md](agent-configuration.md) · +[contributor-relay.md](contributor-relay.md) diff --git a/src/docs/agents-md.md b/src/docs/agents-md.md index 827c9598cd..a060cb6f24 100644 --- a/src/docs/agents-md.md +++ b/src/docs/agents-md.md @@ -252,6 +252,10 @@ still wins. ## What to read next +- [agent-knowledge-and-memory.md](agent-knowledge-and-memory.md) — where this + block sits in the whole kick (skills, AGENTS.md, `# Relevant Knowledge`), why + the CLI does not read the repo's `AGENTS.md` natively, and what `/clear` + does and does not reset. - [house-style.md](house-style.md) — the short, hive-wide *how to change things* section that precedes this block in every kick; a repo overrides it with a root `HIVE_STYLE.md`, read from the same checkout root. diff --git a/src/docs/api-reference/packs-and-acmm.md b/src/docs/api-reference/packs-and-acmm.md index 91ea9f781f..31d001023a 100644 --- a/src/docs/api-reference/packs-and-acmm.md +++ b/src/docs/api-reference/packs-and-acmm.md @@ -16,11 +16,11 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f | `GET` | `/api/repos/{owner}/{repo}/hold-permission` | Dashboard auth/session | Reports whether the signed-in user can toggle hold chips for a repository card. Owners are allowed; otherwise the server checks GitHub `repos/{owner}/{repo}/collaborators/{user}/permission` and briefly caches the effective permission | `pkg/dashboard/api.go:362`, `pkg/dashboard/api_repo_hold.go` | | `GET` | `/api/repos/{owner}/{repo}/items/{number}` | Dashboard session | Per-item detail for the activity monitor's decision badge: `{repo, number, stage, stage_slug, operator_actions[], operator_action_count, last_operator_action}`. `operator_actions[]` is the server-side ledger of every row action submitted from the dashboard (hold/release, decision, decide-delegated, send-to-human, accept-triage — recorded by `recordOperatorAction` around those routes) as `{action, actor, at, note, target, outcome: pending|applied|no-op|failed, detail, head_sha, stage}`; `last_operator_action` adds the derived `state` (`waiting|addressed|stuck|pending|failed`), `stuck_after_seconds` and `followed[]` (the stage hops after the action). The same `last_operator_action` / `operator_action_count` ride every stage-tracker row and linked PR. Persisted in `/data/operator-actions.json`; `HIVE_OPERATOR_ACTION_STUCK_AFTER` (default `30m`) sets the stuck window. Rows also carry `rebase_merge: {state: approved|rebasing|ci-pending|merged|failed, actor, base, text, fail_reason, conflict_files[], armed_at}` while a *Rebase, then merge as maintainer* follow-through is live or just settled (persisted in `/data/rebase-merge-followups.json`; `fail_reason: foreign-head` when the head moved after the approval by someone other than the hive, so nothing merged), and `rebase: {attempt, max, exhausted, head, text}` on a conflicting PR the fixer is rebasing under the two-attempt loop guard (`/data/rebase-attempts.json`). | `pkg/dashboard/api.go`, `pkg/dashboard/operator_actions.go` | -| `POST` | `/api/repos/{owner}/{repo}/items/{number}/hold` | Owner or repo write/maintain/admin | Add or remove a dashboard hold chip for an issue or PR. Body `{"held": true}` adds the hive's exact-match canonical `hive-pause/<hive-id>` label; `{"held": false}` removes exactly the labels causing the hold (`hive-pause/<hive-id>` and/or generic hold labels) and never removes `hive/<hive-id>` provenance. Every toggle writes an audit-log entry; the #8851 upgrade migration writes `/data/hive-hold-migration-<hive-id>.json` with audit-backed, provenance-only, and ambiguous legacy `hive/<hive-id>` classifications. | `pkg/dashboard/api.go:366`, `pkg/dashboard/api_repo_hold.go` | -| `POST` | `/api/repos/{owner}/{repo}/items/{number}/decision` | Owner or repo write/maintain/admin, signed-in GitHub user | Record an operator decision from the activity monitor's row menu / selection bar. Body `{"decision": "approve"|"direction"|"close-superseded"|"close-wontfix"|"adopt"|"reroute"|"re-author"|"merge-now"|"queue-merge", "comment": "…", "type": "issue"|"pr", "superseded_by": "#458", "force": true, "to": "<login>"|"any"}` (`force` only with `adopt`, `to` only with `reroute`; an unknown `decision` is a 400). On an issue parked at 045, `approve`/`direction` act exactly as a maintainer's `/hive approve` / `/hive decision <text>` comment would (labels, `approved-direction`, stage-engine Unparked fact, reply comment naming the operator). On a PR parked at 085 (`type: "pr"`), `approve` posts the `/lgtm` and `/approve` commands as two comments attributed to the operator, records the approval against the head as the human answer to a `requires_human` / decision-requested verdict (the lanes and the stage engine honour it like a trusted merger's Approve review), lifts `needs-human`, clears the sentinel label and acknowledges the bundle's sentinel findings for that head, re-derives the stage and drops the tracker cache — the response adds `released` (`approval-recorded`, `needs-human`, `sentinel-label`, `sentinel-acknowledged`) and `stage`; the merge gate decides from there (no review as the operator, no merge) — and `direction` records the text as a human change request against the head — the `/hive decision` fix lane — on a hive-authored PR, and on a contributor's clanker PR (`author/clanker` / hive attribution markers) where the text is posted to the contributor's hive and the PR moves to `stage/072-returned-to-contributor` (`status: "direction-returned-to-contributor"`); a person's PR, which no hive can carry direction to, answers 409. The close variants post a comment naming the operator (and the superseding PR when `superseded_by` is given) and close the item as not planned. `adopt` and `re-author` require `type: "pr"` and queue adoption via the `adoption/supersede` label (409 unless `governor.labels.stage.adoption` is enabled). `adopt` with `"force": true` is *Adopt now* ([#15038](https://github.com/hivecommons/hive/issues/15038)): it bypasses the author's presence, the grace window and `maintainer_policy`, marks the stage record and nudges the automerge sweep so the adoption engine supersedes the head at once (responds `status: "already-adopted"` when nothing is left to do; 400 on the hive's own PR). `reroute` (`type: "pr"`, `"to": "<clanker login>"|"any"`) hands the PR's follow-up work to another online clanker through the contributor fix queue, posts a `<!-- hive:rerouted … -->` note and arms a pickup timer that falls back to Adopt now after `governor.reroute.pickup_timeout`; answers `status: "rerouted"`, 409 when no clanker is online or adoption is disabled. On a PR at 090, `queue-merge` (*Approve and let hive merge*, the lead action) records an approval attributed to the operator and applies the automerge label, returning `status: "queued-for-merge"` (on the hive's own PR, which the App cannot review, the queue note is a comment and the operator's approval is recorded as `approve` records it — `released` lists `approval-recorded`, `admitted`); hive's merge sweep merges on its next tick once CI is green and the head has soaked, and that recorded operator approval is the one thing that lets the sweep merge an untrusted-author PR (the merge comment names the operator). `merge-now` (*Merge now as maintainer*, secondary) posts an attributed comment and merges immediately through the hive's GitHub App, returning `status: "merged"`. Both require `type: "pr"` and a verified owner or `merger` role in addition to the route's repo permission check; both refuse closed/merged PRs and the operator's own PR. `merge-now` on a PR whose `mergeable_state` is `dirty`/`behind` instead answers `202` with `status: "rebase-queued"` (approval recorded, rebase kicked, merge follows via the follow-through once the hive's own rebase is green; a head pushed by anyone else fails the follow-through closed; `head-not-pushable` refusal on a fork without maintainer edits). `approve` on such a PR adds `rebase: {attempt, max, exhausted, head, text}` for the rebase episode it opened. Every decision writes an audit-log entry (`repo_item_decision_*`, e.g. `repo_item_decision_adopt_now`, `repo_item_decision_reroute`). | `pkg/dashboard/api.go:367`, `pkg/dashboard/api_repo_item_decision.go` | -| `POST` / `GET` | `/api/repos/{owner}/{repo}/items/{number}/decide-delegated` | Same as `…/hold` (owner or repo write), signed-in GitHub user; `decisions.delegate.enabled` (403 when off) | *Let hive decide*: enqueue a delegated-decision job in which the hive decides the parked item itself as the owner's delegate under `pkg/delegatedecision.PolicyText` and records it as a human decision (`/hive decision` comment with the `<!-- hive:delegated-decision … -->` marker, park labels off, `triage/accepted`, queue approval on a PR head). Body `{"type": "issue"|"pr", "reason", "caption", "sentinel_reason"}`. `POST` answers 202 with the job (`{id, status: "running"|"done"|"failed", decision: {verdict, rule, text, rationale, actions, keeps_park, ladder?: {decision, reason, ruled_out[]}}, notes, error}`; `ladder` is set on contributor-PR decisions and names the rung that decided — `already-fixed` → `mergeable-as-is` → `rebase-then-merge` → `return-to-contributor` → `contributor-offline` — and why each rung above it did not apply); 409 with the running job while one is in flight; `GET` reads it. Rails: never merges, refuses items wearing `hold`, never grants secrets/permissions (`needs-owner` + `hold` instead), recommends only on hive policy/governance questions (keeps 085). Audited as `repo_item_decision_delegated[_failed]`. See [dashboard-sections.md](../dashboard-sections/activity-monitor.md#let-hive-decide). | `pkg/dashboard/api.go:329`, `pkg/dashboard/api_repo_item_decide_delegated.go` | -| `POST` | `/api/repos/{owner}/{repo}/items/{number}/decide-delegated/plan` | Same as `…/decide-delegated` | Preview for *Let hive decide*: runs the same owner-delegate policy with **no side effects** (nothing written, no job) and answers `{would, rule, acting, title, summary, why, consequences[], ladder, mergeable_as_is, alternatives[], writes: false, prior, notes, saw[], rule_plain, rationale, why_not[]}` — `summary` is one verb-first sentence with no "Hive would:" prefix (*Send #15332 back to its author with one instruction: make CI green, nothing else.*), `why` one short line (*CI is red.*), `consequences` at most two items, `ladder` the rung that decided with its `ruled_out` list, `saw` every fact the rules read as `{label, value, state}` (`state` is `ok`, `blocks` or `info`), `rule_plain` and `rationale` the deciding rule in plain words and its whole reason (`rationale` omitted when it only repeats `why`), `why_not` the ruled-out rungs as `{option, because}`, and `mergeable_as_is` whether an as-is merge is honest (the queue-merge and merge-now alternatives are dropped when it is not). The dialog shows **Cancel** / **Let hive do that**, plus **Approve and let hive merge** (or **Merge now as maintainer** when the hive would approve anyway) only when `mergeable_as_is`; only then does the SPA post `…/decide-delegated` with `chosen` naming the button. A transient GitHub failure (5xx, timeout) is retried twice with backoff before the plan gives up. A plan that cannot read the item says why, never with 502 or 503 (the hosted Ingress replaces those with its own *hive unavailable* page, hivecommons/hive#16776): the failure body is `{ok: false, error, reason, retryable, attempts, elapsed_ms, hive, hint}` under **429** with `Retry-After` while GitHub rate-limits the hive (*GitHub API rate limit for this hive is exhausted; resets at 17:32Z*, or the secondary limit's *retry after* time; `reason: github`), **409** when the item is no longer open (`not-open`), or **424** when a read it depends on failed (`github` — a 404, a permission 403, a 5xx that outlasted the retries, or an unreachable GitHub), is not configured (`config`) or the plan itself failed (`plan`). See [dashboard-sections.md](../dashboard-sections/activity-monitor.md#let-hive-decide). | `pkg/dashboard/api.go:371`, `pkg/dashboard/api_repo_item_decide_delegated_plan.go`, `pkg/dashboard/delegated_gather_error.go` | -| `POST` | `/api/repos/{owner}/{repo}/items/{number}/blocker/recheck` | Same as `…/hold` (owner or repo write), signed-in GitHub user | *Re-check permissions* on an issue parked on a capability blocker (#15099): probes the GitHub App installation's permissions; when a non-workflows permission is granted, clears its ledger entries and un-parks the item; workflows blockers require a separate hand-off (`{result: {outcome: "released", …}}`), otherwise `{result: {outcome: "no-effect", reason: "blocker", options: [...]}}`; 404 when the item has no blocker, 409 when the blocker is not a capability gap | `pkg/dashboard/api.go:372` | +| `POST` | `/api/repos/{owner}/{repo}/items/{number}/hold` | Owner or repo write/maintain/admin | Add or remove a dashboard hold chip for an issue or PR. Body `{"held": true}` adds the hive's exact-match canonical `hive-pause/<hive-id>` label (shortened with a hash suffix when the plain spelling would exceed GitHub's 50-character label cap, [#17037](https://github.com/hivecommons/hive/issues/17037)); `{"held": false}` removes exactly the labels causing the hold (`hive-pause/<hive-id>` and/or generic hold labels) and never removes `hive/<hive-id>` provenance. A GitHub failure answers `424` with the step and GitHub's reason — never `502`/`503`, which the hosted Ingress replaces with its generic "hive unavailable" page. Every toggle writes an audit-log entry; the #8851 upgrade migration writes `/data/hive-hold-migration-<hive-id>.json` with audit-backed, provenance-only, and ambiguous legacy `hive/<hive-id>` classifications. | `pkg/dashboard/api.go:366`, `pkg/dashboard/api_repo_hold.go` | +| `POST` | `/api/repos/{owner}/{repo}/items/{number}/decision` | Owner or repo write/maintain/admin, signed-in GitHub user | Record an operator decision from the activity monitor's row menu / selection bar. Body `{"decision": "approve"|"direction"|"close-superseded"|"close-wontfix"|"close-read"|"close-issue"|"adopt"|"reroute"|"re-author"|"merge-now"|"queue-merge", "comment": "…", "type": "issue"|"pr", "superseded_by": "#458", "force": true, "to": "<login>"|"any"}` (`force` only with `adopt`, `to` only with `reroute`; an unknown `decision` is a 400). On an issue parked at 045, `approve`/`direction` act exactly as a maintainer's `/hive approve` / `/hive decision <text>` comment would (labels, `approved-direction`, stage-engine Unparked fact, reply comment naming the operator). On a PR parked at 085 (`type: "pr"`), `approve` posts the `/lgtm` and `/approve` commands as two comments attributed to the operator, records the approval against the head as the human answer to a `requires_human` / decision-requested verdict (the lanes and the stage engine honour it like a trusted merger's Approve review), lifts `needs-human`, clears the sentinel label and acknowledges the bundle's sentinel findings for that head, re-derives the stage and drops the tracker cache — the response adds `released` (`approval-recorded`, `needs-human`, `sentinel-label`, `sentinel-acknowledged`) and `stage`; the merge gate decides from there (no review as the operator, no merge) — and `direction` records the text as a human change request against the head — the `/hive decision` fix lane — on a hive-authored PR, and on a contributor's clanker PR (`author/clanker` / hive attribution markers) where the text is posted to the contributor's hive and the PR moves to `stage/072-returned-to-contributor` (`status: "direction-returned-to-contributor"`); a person's PR, which no hive can carry direction to, answers 409. The close variants first post a required comment naming the operator (and the superseding PR when `superseded_by` is given); a failed comment prevents closure. `close-superseded` and `close-wontfix` close as **not planned**; `close-read` acknowledges an advisory issue and closes it **as completed**. `close-issue` (`type: "issue"` only) closes the single named open issue **as completed**, at any stage, leaving linked PRs and other issues untouched; it returns 400 for a PR (including one sent as an issue), 404 when the issue is not found, and 409 when already closed. It retains the existing permission and mutation gates, including the paused-repo `status: "refused"` result without writes. `adopt` and `re-author` require `type: "pr"` and queue adoption via the `adoption/supersede` label (409 unless `governor.labels.stage.adoption` is enabled). `adopt` with `"force": true` is *Adopt now* ([#15038](https://github.com/hivecommons/hive/issues/15038)): it bypasses the author's presence, the grace window and `maintainer_policy`, marks the stage record and nudges the automerge sweep so the adoption engine supersedes the head at once (responds `status: "already-adopted"` when nothing is left to do; 400 on the hive's own PR). `reroute` (`type: "pr"`, `"to": "<clanker login>"|"any"`) hands the PR's follow-up work to another online clanker through the contributor fix queue, posts a `<!-- hive:rerouted … -->` note and arms a pickup timer that falls back to Adopt now after `governor.reroute.pickup_timeout`; answers `status: "rerouted"`, 409 when no clanker is online or adoption is disabled. On a PR at 090, `queue-merge` (*Approve and let hive merge*, the lead action) records an approval attributed to the operator and applies the automerge label, returning `status: "queued-for-merge"` (on the hive's own PR, which the App cannot review, the queue note is a comment and the operator's approval is recorded as `approve` records it — `released` lists `approval-recorded`, `admitted`); hive's merge sweep merges on its next tick once CI is green and the head has soaked, and that recorded operator approval is the one thing that lets the sweep merge an untrusted-author PR (the merge comment names the operator). `merge-now` (*Merge now as maintainer*, secondary) posts an attributed comment and merges immediately through the hive's GitHub App, returning `status: "merged"`. Both require `type: "pr"` and a verified owner or `merger` role in addition to the route's repo permission check; both refuse closed/merged PRs and the operator's own PR. `merge-now` on a PR whose `mergeable_state` is `dirty`/`behind` instead answers `202` with `status: "rebase-queued"` (approval recorded, rebase kicked, merge follows via the follow-through once the hive's own rebase is green; a head pushed by anyone else fails the follow-through closed; `head-not-pushable` refusal on a fork without maintainer edits). `approve` on such a PR adds `rebase: {attempt, max, exhausted, head, text}` for the rebase episode it opened. Every decision writes an audit-log entry (`repo_item_decision_*`, e.g. `repo_item_decision_adopt_now`, `repo_item_decision_reroute`). | `pkg/dashboard/api.go:367`, `pkg/dashboard/api_repo_item_decision.go` | +| `POST` / `GET` | `/api/repos/{owner}/{repo}/items/{number}/decide-delegated` | Same as `…/hold` (owner or repo write), signed-in GitHub user; `decisions.delegate.enabled` (403 when off) | *Let hive decide*: enqueue a delegated-decision job in which the hive decides the parked item itself as the owner's delegate under `pkg/delegatedecision.PolicyText` and records it as a human decision (`/hive decision` comment with the `<!-- hive:delegated-decision … -->` marker, park labels off, `triage/accepted`, queue approval on a PR head). Body `{"type": "issue"|"pr", "reason", "caption", "sentinel_reason"}`. `POST` answers 202 with the job (`{id, status: "running"|"done"|"failed", decision: {verdict, rule, text, rationale, actions, keeps_park, ladder?: {decision, reason, ruled_out[]}}, notes, error}`; `ladder` is set on contributor-PR decisions and names the rung that decided — `already-fixed` → `mergeable-as-is` → `rebase-then-merge` → `return-to-contributor` → `contributor-offline` — and why each rung above it did not apply); 409 with the running job while one is in flight; `GET` reads it. Rails: never merges, refuses items wearing `hold`, never grants secrets/permissions (`needs-owner` + `hold` instead), recommends only on hive policy/governance questions (keeps 085). Audited as `repo_item_decision_delegated[_failed]`. See [dashboard-sections.md](../dashboard-sections.md#let-hive-decide). | `pkg/dashboard/api.go:329`, `pkg/dashboard/api_repo_item_decide_delegated.go` | +| `POST` | `/api/repos/{owner}/{repo}/items/{number}/decide-delegated/plan` | Same as `…/decide-delegated` | Preview for *Let hive decide*: runs the same owner-delegate policy with **no side effects** (nothing written, no job) and answers `{would, rule, acting, title, summary, why, consequences[], ladder, mergeable_as_is, alternatives[], writes: false, prior, notes}` — `summary` is one verb-first sentence with no "Hive would:" prefix (*Send #15332 back to its author with one instruction: make CI green, nothing else.*), `why` one short line (*CI is red.*), `consequences` at most two items, `ladder` the rung that decided with its `ruled_out` list, and `mergeable_as_is` whether an as-is merge is honest (the queue-merge and merge-now alternatives are dropped when it is not). The dialog shows **Cancel** / **Let hive do that**, plus **Approve and let hive merge** (or **Merge now as maintainer** when the hive would approve anyway) only when `mergeable_as_is`; only then does the SPA post `…/decide-delegated` with `chosen` naming the button. A transient GitHub failure (5xx, rate limit, timeout) is retried twice with backoff before the plan gives up. A failure answers `{ok: false, error, reason, retryable, attempts, elapsed_ms, hive, hint}` under **409** when the item is no longer open (`reason: not-open`) or **424** when a read it depends on failed (`github`), is not configured (`config`) or the plan itself failed (`plan`) — never 502/503, which the hosted Ingress intercepts and replaces with its generic *hive unavailable* page (hivecommons/hive#16776). See [dashboard-sections.md](../dashboard-sections.md#let-hive-decide). | `pkg/dashboard/api.go:371`, `pkg/dashboard/api_repo_item_decide_delegated_plan.go` | +| `POST` | `/api/repos/{owner}/{repo}/items/{number}/blocker/recheck` | Same as `…/hold` (owner or repo write), signed-in GitHub user | *Re-check permissions* on an issue parked on a capability blocker (#15099): probes the GitHub App installation's permissions; when the missing permission is granted, clears every ledger entry blocked on it and un-parks the item (`{result: {outcome: "released", …}}`), otherwise `{result: {outcome: "no-effect", reason: "blocker", options: [...]}}`; 404 when the item has no blocker, 409 when the blocker is not a capability gap | `pkg/dashboard/api.go:372` | | `POST` | `/api/repos/{owner}/{repo}/items/{number}/blocker/handoff` | Same as `…/hold`, signed-in GitHub user | With a workflows blocker, verified App permission and capable lane, records the decision, clears the park and routes the issue to that lane; rejects held or ineligible issues | `pkg/dashboard/api.go:373` | | `POST` | `/api/repos/{owner}/{repo}/items/{number}/blocker/close-partial` | Same as `…/hold` (owner or repo write), signed-in GitHub user | Option (c) on a capability blocker (#15099): labels the issue `hive/partially-addressed`, posts the operator's `{"comment"}` naming what remains and closes it; the ledger entry is cleared | `pkg/dashboard/api.go:374` | | `POST` | `/api/repos/{owner}/{repo}/items/{number}/accept-triage` | Owner or repo write/maintain/admin | Accept triage on an issue from the activity monitor's row menu — what a maintainer accepting triage on GitHub does by hand: adds the reporter-trust triage label (`triage/accepted`, or the first of `issue_filter.reporter_trust.untrusted_require_labels`; the label is created in the repo if missing) and removes the awaiting label (`needs-triage` / `reporter_trust.awaiting_label`) and a Hive-written `stage/015-triage-needed`. Empty body. Returns `{ok, repo, number, acceptLabel, added, removed, alreadyAccepted, minStatusSeq}`; an issue already carrying the accept label with nothing left to remove is a no-op (`alreadyAccepted: true`, no write, no audit). 404 for a pull request or an unknown item. The status snapshot's labels are patched so the next reconcile reads 010 Actionable before the engine's own 015 → 010 derivation. Every write is audited as `repo_item_accept_triage` under the dashboard user. | `pkg/dashboard/api.go:582`, `pkg/dashboard/api_repo_item_accept_triage.go` | diff --git a/src/docs/crux-serve.md b/src/docs/crux-serve.md index e5d7a33d77..e401bd2693 100644 --- a/src/docs/crux-serve.md +++ b/src/docs/crux-serve.md @@ -37,6 +37,7 @@ runtime and every agent must arrive as a definition on `POST /v1/agents`. | `--checkout-allow PREFIX,…`, `CRUX_CHECKOUT_ALLOWLIST` | repository URL prefixes `POST /v1/checkouts` may clone; unset means no checkout service ([design](design/crux-work-services.md)). | | `--checkout-dir PATH`, `CRUX_CHECKOUT_DIR` | where pinned checkouts live. Default `<workdir>/checkouts`. | | `--lanes-config PATH`, `CRUX_LANES_CONFIG` | opt into [durable event/work lanes](crux-lanes.md) on this same server, backed by NATS JetStream. Lane project credentials are separate from agent-control credentials. | +| `--runs-config PATH`, `CRUX_RUNS_CONFIG` | contained-run configuration file that supplies the sandbox backend for `POST /v1/runs`. Without it the server still serves saved run records under `<workdir>/runs` (`GET /v1/runs/{id}`), and `POST /v1/runs` answers `501`; runs left in flight by an earlier process are marked unfinished at startup ([design](design/crux-work-services.md)). | | `--hive-callback ADDR`, `CRUX_HIVE_SOCKET` (+ `CRUX_HIVE_TOKEN`) | dial hive's callback endpoint (`crux/api/callback`) for the capabilities hive owns — scoped GitHub tokens, PR creation, Linear credentials, text/canary scanners, conditions — and feed the runtime's seams from it instead of leaving them nil. Health reports it under `hive_callback`; an unreachable endpoint raises the `hive_callback_unavailable` condition. (#14246) When the runtime is a manager it also polls hive's host policy from the same endpoint; see [Host policy from hive](#host-policy-from-hive-14138-stage-4). | `serve` does not use the per-work-dir control socket that a foreground @@ -95,6 +96,7 @@ and [lane error codes and failure behavior](crux-lanes.md#bounds-and-failure-beh | `POST /v1/agents/{name}/stop` | | `Lifecycle.Stop` | `{"agent","process"}` | | `GET /v1/events` | | watcher + `Kicker.SetKickObserver` + the `crux.Host` observers | `text/event-stream` of `Event` records | | `POST /v1/checkouts`, `GET /v1/checkouts[?owner=]`, `GET`/`DELETE /v1/checkouts/{id}` | `{"repo","commit","owner"?,"branches"?,"max_bytes"?,"ttl"?}` | `checkout.Service` | Work service (S1): a worktree pinned at a full SHA, owned by the caller principal; `501` without `--checkout-allow`; [routes, codes and semantics](design/crux-work-services.md) | +| `POST /v1/runs`, `GET /v1/runs/{id}`, `POST /v1/runs/{id}/cancel` | contained-run request (see `ContainedRunRequest` in `crux/api/runs.go`) | `runs.Service` | Work service (S2/S7): run an untrusted command in a sandbox and read the saved record whatever the process state; cancel after completion returns the result; `501` on `POST` without `--runs-config`; restart and listing routes are [deferred](design/crux-work-services.md#deferred-runs-routes) | | `GET /v1/lanes` and lane/group subroutes | Publish/recovery/receipt JSON; [request shapes](crux-lanes.md#public-http-and-go-api) | `lanes.Broker` | Opt-in only; lane-project credential and capability ACLs; JSON or `204`; [full routes and responses](crux-lanes.md#public-http-and-go-api) | ### Runtime families (#14138 stage 3) diff --git a/src/docs/design/README.md b/src/docs/design/README.md index 647247c3b7..bcaa60bb17 100644 --- a/src/docs/design/README.md +++ b/src/docs/design/README.md @@ -56,6 +56,8 @@ that status is the thing to check before treating a page as current behaviour: `local`, so an assistant-mediated action is indistinguishable from a dashboard one. - [Crux: the agent runtime boundary](crux.md) — **Stage 1 shipped (v5); Stage 2 blocked on `pkg/config`.** RFC [#13536](https://github.com/hivecommons/hive/issues/13536): names the agent runtime inside Hive (`pkg/agent` and its ring) as Crux, lists what stays in Hive, records the staged plan (in-repo boundary → nested module → `crux serve`) and the naming decision. Inbound and outbound ratchets in `src/internal/testutil/crux_*_ratchet_test.go`, the tmux funnel, `crux.Runtime`, Crux-owned value types, CI path filters and the `crux` CLI are live; the nested module waits on an agent-runtime config leaf (the doc lists the measured outbound edges and prerequisites). +- [Draining CLI auto-memory into draft knowledge](cli-memory-drain.md) — **Design only.** #17033: turns each coding CLI's hidden memory store (Claude Code `projects/*/memory`, Codex `memories`, Gemini `GEMINI.md`) into `draft` knowledge facts tagged `auto-memory` and `agent:<name>`. Claude Code drains through a `SessionEnd` hook; the others drain on the manager side at kick time, before `clear_on_kick`. Decides content-hash dedup across agents, an ingest-only drain with the existing curator as the only promoter, and untrusted-content handling (never primed while draft). Implementation is split into three child issues. + - [Crux: generic tool policy for the MITM proxy](crux-tool-policy.md) — **Design only (proposed).** #14228, child of #14138: a shared operation vocabulary with per-forge adapters, a `relay(<command>)` verdict, deny-by-default for unrecognised operations, and the proxy's evaluation pipeline written down once. It also covers migrating behind a parity test and treating #14211 as the first non-GitHub adapter. - [PR follow-up session resume](pr-follow-up-resume.md) - **shipped (v5, default off).** #9583: ties each agent-opened PR to the CLI session that authored it (a `pkg/turn` envelope per PR) and feeds CI failures, changes-requested reviews, new review-bot threads and comments from people with write access back into that session without `/clear` while it is still live. When the session is gone (a restart or the next regular kick), the follow-up takes the fix-before-new path and the agent's next kick carries a compact handoff note of the PR's original reasoning. Pointers are pruned on merge or close; a live-review soak is the remaining follow-up. diff --git a/src/docs/design/cli-memory-drain.md b/src/docs/design/cli-memory-drain.md new file mode 100644 index 0000000000..fc6e94af44 --- /dev/null +++ b/src/docs/design/cli-memory-drain.md @@ -0,0 +1,382 @@ +# Draining CLI auto-memory into draft knowledge (#17033) + +Status: **design only.** Nothing described here is implemented yet. The three +open questions in #17033 are decided below; the work is cut into three +implementation children, listed in [Implementation plan](#implementation-plan). + +All citations are against `origin/v5` at `7a929356`. The CLI-memory isolation +and disable work this design builds on (#17031, #17032) is in open PRs +[#17039](https://github.com/hivecommons/hive/pull/17039) and +[#17040](https://github.com/hivecommons/hive/pull/17040). Their symbols are +named below without line numbers because they are not on `v5` yet. + +## The problem: a hidden, per-agent store + +Every coding CLI Hive drives keeps its own persistent memory across sessions: + +| CLI | Store | Written by | +|---|---|---| +| Claude Code | `~/.claude/projects/<project>/memory/MEMORY.md` plus sibling topic files | auto memory | +| Codex | `$CODEX_HOME/memories`, `$CODEX_HOME/memories_v2` | the memories feature | +| Gemini CLI | `~/.gemini/GEMINI.md` (the `save_memory` tool appends to it) | the model | +| Copilot CLI | none on disk — Copilot Memory is stored on GitHub | — | + +Hive does not see what is in those stores. A one-off inference written on +Tuesday comes back on every later session, it is not scoped, nobody reviews +it, and until #17039 lands it is shared across agents: v5 bridges `~/.claude`, +`~/.gemini` and `~/.codex` whole into the shared home +(`src/crux/agent/interactive_home.go:68-71`). + +From the 2026-11-05 community meeting, quoted in #17033: + +> the CLIs' built-in memory "creates its own hidden bead storage … like 60% of +> these should have been beads … is there a create-memory hook where instead +> we could overload that for our CLIs and make it inject a bead instead? I +> pulled them down locally, created them as beads, and turned that feature off +> on the CLI." + +#17040 does the "turned that feature off" half. With `agents.cli_memory` it +seeds each CLI's documented disable (`autoMemoryEnabled: false` for Claude +Code, `[features] memories = false` for Codex). With `clear_on_kick` it wipes +the agent's own store before each kick (`clearCLIMemoryLocked`, called from +`deliverKickLocked`). This design does the "created them as beads" half: what +a CLI writes to its memory store becomes a reviewable, scoped, +lifecycle-managed knowledge entry instead of being lost or kept hidden. + +## The destination already exists + +Nothing new is needed on the read side. + +- **Lifecycle states.** Every fact is `draft`, `approved`, `deprecated` or + `superseded` (`src/pkg/knowledge/lifecycle.go:16-21`). Only `approved` + passes `lifecycleAllowed` unless a caller opts other states in + (`src/pkg/knowledge/lifecycle.go:88-98`). The kick primer filters with + `FilterByLifecycle` (`src/pkg/knowledge/primer.go:144`). See + [Knowledge lifecycle states](../knowledge-lifecycle.md). +- **Per-agent scope.** `knowledge.agent_scopes` + (`src/pkg/config/knowledge_config.go:43-46`) binds an agent to layers, + repos, types, tags and admitted states. It is resolved for the kick primer in + `primeKnowledge` (`src/pkg/scheduler/kick_priming.go:256-305`). See + [Scoped knowledge table of contents](../knowledge-toc.md). +- **A write path.** `POST /api/knowledge/create` + (`src/pkg/dashboard/api.go:389`, handler at + `src/pkg/dashboard/api_knowledge.go:577-610`) creates a fact from a + `CreateFactRequest` (`src/pkg/knowledge/api.go:293-300`) and audits it as + `knowledge_create_fact`. `bd kb` already talks to the dashboard API rather + than the local bead store ([Beads CLI](../beads-cli.md)). +- **State changes and review.** `PUT /api/knowledge/entry/{id}/state` and + `hivectl knowledge state` move a local-channel fact between states with an + audit entry. `UpdateFactRequest` (`src/pkg/knowledge/api.go:335-344`) + already carries `tags` and `state`. +- **The curator.** `knowledge.curator` (`KnowledgeCurator`, + `src/pkg/config/knowledge_config.go:269-289`) drives + `Promoter.AutoPromoteCandidates` (`src/pkg/knowledge/promote.go:127`) on a + schedule through `PromotionScheduler` + (`src/pkg/knowledge/curator_schedule.go:31`). It is opt-in and off by + default. See [Knowledge promotion configuration](../knowledge-curator.md). + +Two gaps on the write side remain, and phase 1 closes them: + +1. `bd create` has no `knowledge` type (`src/docs/beads-cli.md:11` lists the + types), and there is no `bd` verb that creates a fact. +2. `CreateFactRequest` has no `state` field, so there is no way to create a + fact as `draft`. A fact with no `state:` frontmatter loads as `approved`, so + a drained entry written through today's create path would reach primers + immediately. That is the reason the field is required, not a nicety. + +What is missing is the **drain**: a step that moves what is in each store into +`draft` facts, then empties the store. + +## Bead shape + +Each memory entry becomes one knowledge fact, created through the same verb +the hook and the manager both use: + +```bash +bd create --type knowledge --state draft \ + --tag auto-memory --tag agent:<name> --tag cli:<claude|codex|gemini> \ + --tag memhash:<16 hex> \ + --title "<first line of the entry, ≤ 80 chars>" --body-file <entry> +``` + +- `bd create --type knowledge` is routed to `POST /api/knowledge/create` (as + `bd kb` is), not to the local bead store. That keeps facts in one place: the + vault the curator, the TOC and `hivectl knowledge state` already work on. +- **Layer:** `project`, in the local vault channel, so the existing + `hivectl knowledge state` path (local channels only) can approve or discard + it. Type defaults to `pattern`, the existing create default. +- **State:** always `draft`. The create path rejects `--tag auto-memory` + with any other state, so a caller cannot create an approved entry directly. +- **Tags:** an allow-list, set only by the drain code and never parsed out of + the entry: `auto-memory`, `agent:<name>`, `cli:<backend>`, `memhash:<hex>`. + `<name>` must match the agent-name grammar and `<backend>` is one of the + three CLIs. Anything else is refused. +- **Entry splitting.** Claude Code: one entry per topic file in the memory + directory, plus one per top-level bullet or `##` section of `MEMORY.md` + (the index lines that only link to a topic file are dropped). Gemini: one + entry per bullet under the `## Gemini Added Memories` heading of + `GEMINI.md`; the rest of the file is operator context and is never touched. + Codex: one entry per file under `memories/` and `memories_v2/` (the on-disk + format is not a stable contract, so files are taken whole). +- **Content hash.** `memhash` is the first 16 hex characters of the SHA-256 + of the normalised entry: LF line endings, trailing whitespace stripped, + runs of blank lines collapsed. The hash is over the body only, never the + title or the agent. +- **Size cap.** An entry over 8 KiB is stored truncated with a visible + `[truncated by drain]` marker. The hash covers the full normalised entry. + +### Truncating the store + +The store is emptied only after every entry from that file has either created +a fact or matched an existing one (see dedup below). Claude topic files are +removed and `MEMORY.md` is truncated to zero bytes. The Gemini memories section +is removed and the rest of `GEMINI.md` is kept. Codex files are removed. + +A file whose drain fails part-way is left untouched and retried on the next +drain. That is safe because dedup makes the drain idempotent. + +Reads and the truncate follow the same rules as #17040's +`cliMemoryStores`. Only stores private to the agent are drained; every path +component is checked with `Lstat`, so a planted symlink is never followed. The +truncate and remove run as the agent through the same `su-exec` path as +`cliMemoryRemover`. A store that is still shared (a legacy whole-directory +bridge, a UID 0 agent, `HIVE_SHARED_AGENT_HOME=1`) is **not** drained. It +cannot be attributed to one agent, and truncating it would wipe other agents' +memory. It is logged once per agent, exactly like `clear_on_kick`, and is left +to the one-shot legacy migration in phase 3. + +## The drain, per CLI + +The drain logic lives in one Go package inside the Crux module +(`src/crux/agent/memdrain`, beside `cli_memory.go`). It does not live in +`src/pkg`: the agent manager that calls it is in `src/crux`, and the Crux +outbound ratchet (`src/internal/testutil/crux_outbound_ratchet_test.go`) +forbids new imports from Crux into `src/pkg`. The package talks to the +knowledge store only over the dashboard API, the same way `bd` does, so it +needs no `pkg/knowledge` import. A thin `hive memory-drain` subcommand wraps +it for the Claude hook. + +### Claude Code: a `SessionEnd` hook + +Claude Code has a hook surface +([hooks reference](https://code.claude.com/docs/en/hooks)), so its drain runs +inside the session's own lifecycle rather than waiting for the next kick: + +- **`SessionEnd`** runs `hive memory-drain --cli claude --agent "$HIVE_AGENT"` + over `$HOME/.claude/projects/*/memory/`. The hook gets the session `cwd` on + stdin, which narrows the drain to that project's directory. +- **`PostToolUse`** on `Write|Edit|MultiEdit` is optional and off by default. + Its command exits at once unless the tool's `file_path` is under + `~/.claude/projects/*/memory/`, so the cost on every other write is one + process spawn and a path compare. It exists for long-lived sessions that + rarely end. `SessionEnd` alone is the floor. +- **Seeding.** The hooks are merged into the settings Hive already seeds. For + interactive agents that is `sharedClaudeSettingsFile` + (`src/crux/agent/claude_remote_control.go:44-46`), which #17039 keeps as a + per-agent bridge to one fleet file. For inference agents it is the two files + `ensureClaudeSettings` writes (`src/crux/agent/manager_homes.go:624`). The + merge goes through `seedJSONFile` (`src/crux/agent/manager_homes.go:582`), + so an operator's own `hooks` entries are kept and Hive adds its entry only + when it is absent. The command reads the agent from `HIVE_AGENT`, so one + fleet-wide entry serves every agent. +- **Backstop.** A session killed hard does not run `SessionEnd`, so the + manager also drains Claude stores at kick time (below). Dedup makes the + double coverage free. + +### Codex, Gemini CLI: manager-side, at kick time + +Neither CLI documents a hook that fires on a memory write. The manager drains +their stores itself at the same point #17040 clears them: inside +`deliverKickLocked` (`src/crux/agent/manager_kick.go:242`), after +`rotateKickLogOnKickLocked` (`src/crux/agent/manager_kick.go:271`) and +**before** `clearCLIMemoryLocked`. + +- **Codex:** `$CODEX_HOME/memories` and `$CODEX_HOME/memories_v2`, the paths + `cliMemoryStores` already resolves for `codexBackend`. +- **Gemini CLI:** the `## Gemini Added Memories` section of + `$HOME/.gemini/GEMINI.md`, the file `cliMemoryStores` already resolves. +- **Claude Code:** the hook backstop described above, over the same + `projects/*/memory` paths. +- **Copilot CLI:** nothing to drain. Copilot Memory is stored on GitHub, not on + disk, as #17040 records. `~/.copilot/session-state` holds transcripts, not + memory, and is out of scope. If Copilot CLI ships a local memory store, it + joins the table above. + +Ordering with `clear_on_kick`: drain first, then clear. If the drain fails +(dashboard unreachable, knowledge disabled), the files are **moved** into a +Hive-owned spool (`/data/knowledge/auto-memory-spool/<agent>/`) instead of +being left in place. The clear still runs, so the kick still starts clean, and +the next drain retries the spool first. Neither the drain nor the spool ever +blocks a kick. Both are best-effort and logged, like `clearCLIMemoryLocked`. + +### Configuration + +One new key next to #17040's block, off by default: + +```yaml +agents: + cli_memory: + auto_memory: false # #17040 + clear_on_kick: true # #17040 + drain: false # this design: drain stores into draft knowledge + drain_on_write: false # Claude PostToolUse hook (needs drain: true) +``` + +`drain` is useful mainly to operators who turn `auto_memory` back on, and to +the one-shot migration of stores written before #17040. It needs +`knowledge.enabled`. With knowledge off, the drain logs once and does nothing, +and the store is left alone (or cleared, if `clear_on_kick` says so). + +## Decisions on the open questions + +#17033 left three questions open. They are decided here. The maintainer can +override any of them on #17033 or on the phase that implements it. + +### 1. Dedup and merge across agents + +**Decision taken by hive:** dedup on the content hash at create time. Before +creating, the drain looks up `memhash:<hex>` across **every** lifecycle state. + +- No match: create a new `draft`. +- Match: no new fact is created. If the match lacks this agent's + `agent:<name>` tag, the drain adds it through `UpdateFactRequest.Tags`. A + second agent reaching the same inference becomes a second tag on the one + fact, not a second fact. +- Match in `deprecated` or `superseded`: the tag is still added, but the state + is **not** reset. A discarded memory that a CLI writes again stays discarded. + Otherwise the drain would undo the reviewer's work every session. + +Semantic merge (two differently-worded entries that say the same thing) is +**not** done by the drain. That is the reviewer's call, made with the existing +`superseded_by` link. + +**Rationale.** An exact hash is deterministic, cheap and cannot merge two +different claims by mistake. Hive's knowledge design already prefers +deterministic steps over using one model to verify another +([knowledge system](knowledge-system.md#context)). The `agent:` tag count is +also a useful review signal: an entry three agents wrote on their own is worth +reading first. + +### 2. The curator or a bespoke hook + +**Decision taken by hive:** the drain is a thin **ingest** step, a hook for +Claude Code and the manager for the rest. It only ever creates `draft` facts +and adds tags. The existing `knowledge.curator` remains the **sole promoter**; +no second curator is built. Approval of a drained draft goes through the paths +that already exist: `hivectl knowledge state <id> approved`, +`PUT /api/knowledge/entry/{id}/state`, or the dashboard knowledge view. + +**Rationale.** The curator answers *what is worth promoting*; the drain only +answers *where this text goes*. Running ingest through the curator would tie +memory capture to `knowledge.curator.enabled`, which is off by default. It +would also run on the curator's schedule rather than at session end, and would +mix untrusted input into the only component allowed to raise trust. A +second promoter would split review across two places. So the drain is +ingest-only and the curator stays the only path to `approved`. `knowledge.curator` +today only promotes facts between layers. Phase 3 makes sure it never selects +an `auto-memory` draft. + +### 3. Prompt-injection posture + +**Decision taken by hive:** drained text is **untrusted, agent-written +content**. + +- The body is stored verbatim as the fact body. It is never interpreted, so + nothing in it can set the title's provenance, the tags, the state, the layer + or the type. Frontmatter-looking lines in the body are escaped so they + cannot become frontmatter. +- Tags come only from the allow-list above and are set by the drain code, + never parsed from the entry. +- No `auto-memory` fact is rendered into any kick, primer, TOC entry an agent + reads, or public MCP response while it is `draft`. This holds even for an + agent whose `knowledge.agent_scopes` entry admits `draft` through + `include_states`. Phase 3 adds that hard exclusion to the primer and the + agent-identified TOC/entry reads. A human, or the curator's approval path, + must move the fact to `approved` first. Operator reads (`GET /api/knowledge`, + the dashboard) still show drafts so they can be reviewed. +- The drain never runs the content and never follows links in it. + +**Rationale.** A memory file is written by a model that may have read +attacker-controlled text (an issue body, a PR comment, a fetched page). If the +drain auto-primed that text, a single poisoned session would become an +instruction delivered to every later kick, across agents. That is worse than +the per-agent store it replaces. Keeping it `draft` and unread until a reviewer +approves it is the scoping asked for in #17033: "I don't want a developer agent +working another ticket to pull that information in yet." + +## Relation to the knowledge-system design + +This resolves open question 5 of [knowledge-system.md](knowledge-system.md) +("should `~/.claude/projects/*/memory/` be migrated into the wiki?"). The +answer is yes: as `draft` knowledge facts, through the drain, after which the +memory file is emptied. The destination is the project layer's local vault +rather than a separate personal wiki, so the existing review and scope tooling +applies. + +## Implementation plan + +Each phase is one child issue of #17033. Phases 2 and 3 are blocked by phase 1. +Phase 1 depends on #17040 (it reuses `cliMemoryStores` and runs beside +`clearCLIMemoryLocked`). Attribution to one agent depends on #17039 (per-agent +CLI homes). + +### Phase 1 — drain library and manager-side drain (Codex, Gemini, Claude backstop) + +Child: #17056. + +- `CreateFactRequest` gains `state` (`draft` or `approved`, default unchanged). + `POST /api/knowledge/create` refuses `auto-memory`-tagged requests that are + not `draft`, and refuses tags outside the allow-list on those requests. +- `bd create --type knowledge [--state] [--tag]…` routes to that endpoint. + Documented in [Beads CLI](../beads-cli.md). +- `src/crux/agent/memdrain`: read a private store, split, normalise, hash, look + up `memhash` across all states, create the draft or add the `agent:` tag, + truncate after success, spool on failure. +- `agents.cli_memory.drain` config key with the settings-parity entry. +- Manager drain in `deliverKickLocked` before `clearCLIMemoryLocked`, for + Codex, Gemini and (as backstop) Claude Code stores. +- Tests: splitting per CLI, hash stability, dedup-adds-tag, a discarded fact is + not revived, partial failure leaves the file, symlinked or shared stores are + skipped, spool and retry, kick never blocked. + +### Phase 2 — Claude Code `SessionEnd` and `PostToolUse` hooks + +Child: #17057. + +- `hive memory-drain` subcommand wrapping the phase-1 library (reads hook JSON + on stdin, `HIVE_AGENT` from the environment). +- Seed `hooks.SessionEnd` (and `hooks.PostToolUse`, matcher + `Write|Edit|MultiEdit`, when `drain_on_write` is on) into the Hive-seeded + Claude settings through `seedJSONFile`, merge-only, and remove Hive's own + entry when `drain` is turned off. +- Tests: seed and merge keep operator hooks, the hook exits fast on writes + outside the memory directory, end-to-end hook → draft fact → empty + `MEMORY.md`. + +### Phase 3 — review flow, draft exclusion, legacy migration, operator docs + +Child: #17058. + +- Hard-exclude `auto-memory` facts in `draft` from the kick primer, + agent-identified TOC and entry reads, and the public MCP, even when + `include_states` admits `draft`. Make sure `Promoter.AutoPromoteCandidates` + never selects them. +- A dashboard knowledge filter for `auto-memory` drafts that shows the + `agent:` tags and approve and discard actions (backed by the existing state + API). +- `hivectl knowledge drain-memory --legacy`: a one-shot, operator-run drain of + the shared `/data/home/.claude/projects/*/memory` store that #17039 leaves + behind. Tagged `agent:shared`, never truncated without `--truncate`. +- Operator docs: an `agents.cli_memory.drain` section in the operator + reference, an "Auto-memory drafts" section in + [Knowledge lifecycle states](../knowledge-lifecycle.md), and the status line + in [the design index](README.md) moved to partly shipped or shipped. + +## References + +- #17033 — this design's issue. +- #17031 / [#17039](https://github.com/hivecommons/hive/pull/17039) — per-agent CLI homes. +- #17032 / [#17040](https://github.com/hivecommons/hive/pull/17040) — `agents.cli_memory`: disable auto-memory, clear on kick. +- #11102 — knowledge lifecycle states. +- [Knowledge system design](knowledge-system.md), [knowledge lifecycle](../knowledge-lifecycle.md), + [scoped knowledge TOC](../knowledge-toc.md), [knowledge curator](../knowledge-curator.md). diff --git a/src/docs/design/crux-work-services.md b/src/docs/design/crux-work-services.md index 1530515246..1071465854 100644 --- a/src/docs/design/crux-work-services.md +++ b/src/docs/design/crux-work-services.md @@ -1,8 +1,7 @@ # Crux work services: S1 pinned checkout (hivecommons/crux#114) Status: **S0 caller principals and S1 pinned checkout shipped in hive -`src/crux` (v5).** S2 contained run and S7 minimum are in flight in a -sibling change; everything else in the RFC is unscheduled. This records +`src/crux` (v5).** S2 contained run and S7 minimum shipped in #17014; everything else in the RFC is unscheduled. This records S1 *as implemented*, including where it is weaker than the RFC text. The RFC asks for "a working copy of this repo at this commit, owned by @@ -143,12 +142,18 @@ a `.jsonl` index. - TTL sweeper (recorded, not enforced). - `--filter=blob:limit=` partial clones; the cap is post-hoc only. - A per-owner allowlist; one list per server. -- Wiring `InUse` to live runs: that is S2's side of the seam. +- Wiring `InUse` to live runs: that is S2's side of the seam; the S2 commit (#17014) did not wire it, so it remains an open follow-up. - `ssh://` and `http://` repositories; `git@` syntax. - Anything about the hivecommons/crux repository or the publish path: the service lives in hive `src/crux` and ships through the existing mirror unchanged. +## Deferred runs routes + +The runs routes (`POST /v1/runs`, `GET /v1/runs/{id}`, +`POST /v1/runs/{id}/cancel`) shipped in #17014. Restart and listing routes +for runs are deferred and not scheduled. + ## Package map | Path | Role | diff --git a/src/docs/design/crux.md b/src/docs/design/crux.md index 00f7365461..3e1f2ef6ec 100644 --- a/src/docs/design/crux.md +++ b/src/docs/design/crux.md @@ -708,6 +708,7 @@ setter is added without one. | `SetLinearCredentialResolver`, `SetSandboxPushMinter`, `SetSandboxPRClient` | callback | `GET /v1/linear/credential`, `POST /v1/tokens`, `POST /v1/pulls` (stage 2) | | observers (`SetKickOutcomeObserver`, `SetPauseTransitionObserver`, `SetRelaunchObserver`, `SetPersistPauseCallback`, `SetRecordPromptCallback`, `SetSandboxAuditCallback`, `SetAuditSink`, `SetConditionReporter`) | event | the `/v1/events` stream (stage 3); conditions also `POST /v1/conditions` | | `SetSpanStarter` | in-process-only | a span is a Go value wrapping a call in one address space. The sidecar's manager starts spans on the OpenTelemetry global tracer (a no-op without an exporter in the runtime's process); trajectory events do not depend on it | +| `SetKnowledgeAdviser` | in-process-only | the mid-task knowledge advisor (#17052) asks hive's `knowledge.Primer` on the poll tick for every new scope an agent enters; phase 1 keeps it in-process (the sidecar runs with no adviser, so the feature is off there) until a `/v1/knowledge/advise` capability is worth its round trip | No setter is served from a `runtime:` config key: every value is already resolved hive-side from the live config, so a reload reaches the runtime diff --git a/src/docs/design/knowledge-system.md b/src/docs/design/knowledge-system.md index ce22a5d98b..d7047054db 100644 --- a/src/docs/design/knowledge-system.md +++ b/src/docs/design/knowledge-system.md @@ -564,3 +564,4 @@ All endpoints proxy to llm-wiki MCP tools. Dashboard auth (bearer token) applies 3. **Knowledge curation approval** — Auto-extracted facts go to project wiki at confidence < 0.9. Auto-promote to org wiki at confidence >= 0.9. Human approval for community wiki (PR-based). 4. **Cross-project fact promotion** — Automatic when seen in 3+ repos AND confidence > 0.9. Otherwise manual. 5. **Personal wiki bootstrapping** — Should `hive init` create a personal wiki from Claude Code's existing memory files? (e.g., migrate `~/.claude/projects/*/memory/` → `~/.hive/wiki/`) + - **Answered (#17033):** yes, but as `draft` knowledge facts rather than a personal wiki. A drain moves each CLI's memory store (Claude Code `~/.claude/projects/*/memory/`, Codex `$CODEX_HOME/memories`, Gemini's `GEMINI.md` memories section) into draft facts tagged `auto-memory` and `agent:<name>` in the project layer, then empties the store. Nothing reaches a kick until it is approved. See [Draining CLI auto-memory into draft knowledge](cli-memory-drain.md). diff --git a/src/docs/documentation-map.md b/src/docs/documentation-map.md index f9d3addf17..064e9efe9b 100644 --- a/src/docs/documentation-map.md +++ b/src/docs/documentation-map.md @@ -169,6 +169,7 @@ Documentation for the current Hive line (branch `v5`; the code and docs live und - [Custom dashboard stylesheets](custom-stylesheets.md) — operator-supplied CSS for the dashboard and public snapshot. - [Branding a hive](branding.md) — persistent per-deployment name, mark, and colours via `<data>/branding/branding.json` and `custom.css` (`HIVE_BRANDING_JSON`/`HIVE_BRANDING_CSS`); distinct from the per-request `?style=` stylesheets above. - [Portable AgentDefinition format](../AGENT-DEFINITION.md) — standalone YAML schema for importing/exporting agent definitions. +- [How Hive injects knowledge and memory into agents](agent-knowledge-and-memory.md) — the three context layers (Hive knowledge primer, CLI conversation, CLI persistent memory), the kick-primer path and its scoping/caps, why repo `AGENTS.md` is injected rather than read natively, which per-agent home directories are fleet-shared, and what survives a kick, `/clear`, pod restart or a new agent. - [Knowledge connectors](knowledge-connectors.md) — **Owner configuration:** connect, validate, and sync external document/wiki sources; includes scope and API reference. - [Knowledge curator](knowledge-curator.md) — configure fact extraction, sources, vaults, document imports, code maps, and retention. - [Knowledge confidence scoring](knowledge-confidence.md) — interpret confidence badges and score explanations. diff --git a/src/docs/env-vars.md b/src/docs/env-vars.md index 527459f35c..5e4459a679 100644 --- a/src/docs/env-vars.md +++ b/src/docs/env-vars.md @@ -130,6 +130,7 @@ project capabilities, deployment requirements and recovery. | Variable | Required | Default | Purpose | |---|---:|---|---| | `CRUX_LANES_CONFIG` | No | none (durable lanes disabled) | Crux server's lane configuration file, used when `crux serve --lanes-config` is absent. An explicit flag takes precedence. Broker credentials and project tokens are referenced by environment variable name in that file, not embedded as secret values. | +| `CRUX_RUNS_CONFIG` | No | none (no contained-run backend; saved run records are still served) | Crux server's contained-run configuration file, used when `crux serve --runs-config` is absent. An explicit flag takes precedence. | | `HIVE_LANES_ADDRESS` | No | none (participant disabled) | Opts the Hive process into a Crux API endpoint. This is the Crux server address, not the NATS broker URL. | | `HIVE_LANES_LANE` | Yes when `HIVE_LANES_ADDRESS` is set | none | Registered lane ID for the Hive participant. Missing lane, group or token logs an explicit configuration error and leaves participation disabled. | | `HIVE_LANES_GROUP` | Yes when `HIVE_LANES_ADDRESS` is set | none | Registered delivery-group ID for Hive's claim loop; the configured project must have that group's work capability. | @@ -219,7 +220,7 @@ new value at the same time. | `HIVE_OUTPUT_LOG_DIR` | No | `/data/.hive/logs` | Directory (`0700`, files `0600`) where the hive keeps the `proxy`, `hive-output`, `litellm` and `requests` log sources read by the admin MCP `log_read` tool ([#11944](https://github.com/hivecommons/hive/issues/11944)); each keeps at most 5 files of 10 MiB and nothing older than 7 days. The `starts` and `crash` sources ([#11945](https://github.com/hivecommons/hive/issues/11945)) live here too: `starts.log` (newest 200 starts), `start-current.json` and at most 10 `crash-<UTC time>.log` files of 1 MiB. See [design/admin-mcp.md](design/admin-mcp.md#output-and-request-log-sources). | | `HIVE_PROXY_EGRESS_MARK` | No | `0x1112` | Packet mark exempted from the MITM egress redirect. | | `HIVE_PROXY_ADVISORY_OK` | No | `false` | Allows the spoke to start when the forced-proxy egress redirect cannot be installed (no `CAP_NET_ADMIN`/iptables). Enforcement becomes advisory-only — agents can bypass the proxy. Also gates whether the Go proxy trusts a self-asserted `Proxy-Authorization` header as agent identity when its UID map is unavailable (N7, #3841) — off by default, an unidentified caller is treated as `ADVISORY` (writes blocked) rather than whatever name it claims. See [security-model.md](security-model.md#5-network-and-credentials). | -| `HIVE_PROXY_ALLOW_PRIVATE_FORWARD` | No | `false` | Lifts the plain-HTTP forward destination guard ([#14082](https://github.com/hivecommons/hive/issues/14082)). Off by default: a non-CONNECT request through the proxy is dialled only when the resolved address is globally routable, so an agent cannot use the proxy to reach loopback services beside it, the link-local cloud metadata endpoint (`169.254.169.254`), RFC 1918/CGNAT cluster addresses or multicast, and the refusal is a `403` naming the class. Only the exact string `true` turns it on, for deployments that genuinely egress to a private network over plain HTTP (a LAN mirror on a native install). Loopback refusals stay at `DEBUG` and are not counted as violations, because agents are already handed `NO_PROXY` for loopback (#14076). | +| `HIVE_PROXY_ALLOW_PRIVATE_FORWARD` | No | `false` | Lifts the proxy's destination guard ([#14082](https://github.com/hivecommons/hive/issues/14082), [#16785](https://github.com/hivecommons/hive/pull/16785)). Off by default: a plain-HTTP (non-CONNECT) forward, a CONNECT to a host the proxy does not inspect, and a transparent-TLS passthrough are each dialled only when the resolved address is globally routable, so an agent cannot use the proxy to reach loopback services beside it, the link-local cloud metadata endpoint (`169.254.169.254`), RFC 1918/CGNAT cluster addresses or multicast, and the refusal is a `403` naming the class. Only the exact string `true` turns it on, and it lifts the guard for all three legs at once, for deployments that genuinely egress to a private network through the proxy (a LAN mirror on a native install); the proxy logs a boot-time warning when it is set. Loopback refusals stay at `DEBUG` and are not counted as violations, because agents are already handed `NO_PROXY` for loopback (#14076). | | `HIVE_PROXY_INJECT_GH_AUTH` | No | unset (off on every hive, including hosted) | Exact `true` enables proxy-side App-token injection. **Requires GitHub App auth. Refuses startup (exit 19) with `HIVE_PROXY_ADVISORY_OK=true`.** Other spellings do not enable it. Read [behavior and exceptions](#proxy-credential-injection). | | `HIVE_DEPLOYMENT_RUNTIME` | No | none (config `deployment.runtime` fallback; hub-registered Kubernetes hives are auto-detected) | Declares the deployment runtime (`kubernetes`, `podman-quadlet`, or `docker-compose`) so the dashboard can offer standalone upgrades. Unset/unrecognized means `unknown` and the upgrade button stays hidden. See [dashboard-standalone-upgrades.md](dashboard-standalone-upgrades.md). | | `HIVE_DEPLOYMENT_PODMAN_MODE` | Only when runtime is `podman-quadlet` | none (config `deployment.podman_mode` fallback) | `rootless` (`systemctl --user`) or `rootful` (system manager). Without an explicit mode the Podman/Quadlet upgrade path stays disabled. | diff --git a/src/docs/hive-merge.md b/src/docs/hive-merge.md index b787096825..4884447923 100644 --- a/src/docs/hive-merge.md +++ b/src/docs/hive-merge.md @@ -1378,10 +1378,12 @@ when the copy is closed without merging (`adopted_by_state` closed / closed-twice / copy-failed). A clanker PR entering `stage/072-returned-to-contributor` also triggers the -contributor nudge: the sweep posts one `<!-- hive:contributor-nudge head=… --->` comment per head naming the failing checks / review asks (re-nudged -once at the stall threshold, cap 2) and hands the diagnosis to the contribute -hub, which — when the author's relay heartbeat is fresh — pushes a `fix-pr` +contributor nudge: the sweep keeps one `<!-- hive:contributor-nudge +reason=<slug> head=… -->` comment per PR and reason class naming the failing +checks / review asks — a changed reason or new head edits that comment in +place; one re-nudge after `auto_merge.nudge_repeat_after` (default 72h) if +the condition persists, then no more — and hands the diagnosis to the +contribute hub, which — when the author's relay heartbeat is fresh — pushes a `fix-pr` interrupt task into their relay session (parallel sub-session or preempt, per the relay's declared capability) under a per-contributor fix budget; queued fixes are served before new work ("contributors should clean up their diff --git a/src/docs/knowledge-curator.md b/src/docs/knowledge-curator.md index 73da40f1c0..a3577f9a8a 100644 --- a/src/docs/knowledge-curator.md +++ b/src/docs/knowledge-curator.md @@ -625,9 +625,12 @@ overwritten on the next change, so do not edit these pages. Maps an agent name to the `layers`, `repos`, `types`, `tags` and `include_states` that agent's kick primer and agent-identified knowledge reads are restricted to. A missing agent or an empty field is unrestricted (the -default). Unknown layer or lifecycle state names fail config load. See +default). Listing `draft` in `include_states` additionally lets the agent's +kicks carry the drafts it authored (`author:` frontmatter), marked `(draft)`. +Unknown layer or lifecycle state names fail config load. See [Per-agent scopes](knowledge-toc.md#per-agent-scopes) for the intersection -rules. +rules, and [agent-knowledge-and-memory.md](agent-knowledge-and-memory.md) for +how the scope is applied on the kick path end to end. ```yaml knowledge: @@ -637,6 +640,54 @@ knowledge: repos: [hivecommons/hive] ``` +## Mid-task knowledge advisor (`knowledge.advisor`) + +The kick primer above runs once, when the kick is typed. The advisor +(hivecommons/hive#17052) keeps watching after that: every poll tick it +reads the scopes the agent's pane shows it working in — a directory prefix +such as `src/crux/agent` from a `Read(...)`/`Edit ...` line, or a `gh pr` / +`gh issue` / `gh run` command family — and the first time a scope appears +that was not on screen when the kick landed, it asks the same `Primer` +(under the same `knowledge.agent_scopes` restriction) for entries about it. +Each hit is typed into the live session as one line, like a CI-poll nudge: + +``` +📚 Knowledge: Re-pin TRUSTED_SCRIPTS_TREE — Any src/scripts edit must … (full: https://…) +``` + +Rules, all enforced by the runtime (`crux/agent/knowledge_advisor.go`): + +- **Off by default.** `knowledge.advisor: true` turns it on; `knowledge.enabled` + must also be on. Flip it once your own hive has run it for a while. +- **At most `knowledge.advisor_max_per_kick` lines per kick** (default 3), + with a two-minute cooldown between lines. +- **Never an entry the kick already carried.** The primer records which + entries survived the byte cap; those are excluded, and a slug is typed at + most once per kick. +- **Never into a tool call, never after the turn.** A line waits while a + shell command or tool is running; if the agent reaches an empty prompt + first, the pending advice is dropped (the next kick primes afresh). It is + also skipped while a human is attached to the pane and while a kick is + being typed. +- **Per-agent opt-out:** `knowledge.advisor_exclude_agents: [scanner]` + matches an agent name or its replica family base name. +- **Measurable.** Each delivery is recorded in the dashboard prompt history + with trigger `knowledge-advisor` and logged as + `knowledge advisor: delivered` with the agent and slug. + +```yaml +knowledge: + enabled: true + advisor: true + advisor_max_per_kick: 3 + advisor_exclude_agents: [scanner] +``` + +Phase 1 is a pure matcher with no model in the loop; the LLM-ranked variant +(OMP's advisor agent as the model) is hivecommons/hive#17054. The advisor is +wired only when the agent runtime runs in-process; the `crux serve` sidecar +has no adviser in this phase. + ## Open questions - #4944 (the issue behind this section) suggested documenting auth for diff --git a/src/docs/knowledge-entries.md b/src/docs/knowledge-entries.md new file mode 100644 index 0000000000..6ee6a5bdfe --- /dev/null +++ b/src/docs/knowledge-entries.md @@ -0,0 +1,115 @@ +# Repository knowledge entries (`src/docs/knowledge/`) + +`AGENTS.md` carries tone and working style only. Facts about this repository — +module layout, CI guards, the exact changelog exemptions, gotchas — live as +discrete, scoped **knowledge entries** under `src/docs/knowledge/`, one topic +per file, so they are surfaced when a task needs them instead of being paid for +on every kick (proposed by @gregoryhunt at the 2026-11-05 community meeting, +hivecommons/hive#17043). + +How a kick receives knowledge end to end (primer, AGENTS.md block, skills, +memory) is described in `agent-knowledge-and-memory.md`; this page is only the +entry format and how the directory reaches the primer. + +## Entry format + +An entry is an Obsidian-compatible Markdown file with YAML frontmatter — the +same shape `pkg/knowledge`'s `FileStore` already indexes for vaults, git sources +and the bead-synth wiki, plus an additive `scope:` block: + +```markdown +--- +title: Editing src/scripts/ requires re-pinning TRUSTED_SCRIPTS_TREE +type: gotcha +layer: project +state: approved +tags: [repo:hivecommons/hive, ci, governance, scripts] +source: AGENTS.md (moved 2026-11-07, hivecommons/hive#17047) +scope: + paths: [src/scripts/**, .github/scripts/integration-governance.cjs] + labels: [] + lanes: [] +--- + +A PR that edits anything under `src/scripts/` must re-pin … +``` + +| Key | Meaning | +|---|---| +| `title` | One line; this is what the agent sees in bold in `# Relevant Knowledge`. | +| `type` | `gotcha`, `pattern`, `reference`, `decision`, `regression`, … — drives the primer's `knowledge.primer.priority` ordering and the section heading. | +| `layer` | `project` for repository facts. | +| `state` | Lifecycle (`approved`, `draft`, `deprecated`, `superseded`); only `approved` is primed by default. See [knowledge-lifecycle.md](knowledge-lifecycle.md). | +| `tags` | Inline list. Always include `repo:<org>/<name>` — that is how `knowledge.agent_scopes.repos` recognises the entry's repository. | +| `source` | Where the fact came from, so a reader can trace a moved `AGENTS.md` line to exactly one entry. | +| `author` | Who wrote the entry — an agent name (`developer`) or a login (alias `owner`). A `draft` reaches a kick only for the agent that matches this and has opted into drafts; see [knowledge-toc.md](knowledge-toc.md#per-agent-scopes). | +| `scope` | **Where the fact applies.** `paths` are repo-relative globs (`**` supported), `labels` are issue labels, `lanes` are base agent/lane names. An empty list means "no constraint on that dimension". | + +Rules of thumb: + +- One topic per file; the slug is the filename. Keep the body to what an agent + needs to act — the primer drops whole entries that do not fit the kick cap + (`knowledge.primer.max_bytes`, default 4096 bytes). +- Do not put `file.go:NN` citations in an entry; the docs citation guard would + then track them and they would drift. +- Inline lists only (`[a, b]`). The frontmatter parser is line-oriented and + block lists (`- a`) are not supported inside `scope:`. +- Use `state: deprecated` or `superseded_by:` instead of deleting a fact that + stopped being true; the lifecycle filter hides it and the history stays. + +## Scope semantics + +An entry **without** a `scope:` block behaves exactly as every other knowledge +fact: it is selected by keyword relevance (BM25 + Fisher-Rao over the issue +titles and labels in the kick) and by the agent's `knowledge.agent_scopes`. + +An entry **with** a `scope:` block is additionally gated: it is surfaced only +when at least one declared dimension matches the kick — the kick's lane is in +`lanes`, one of the primed issues carries a label in `labels`, or a file the +agent is working on matches a `paths` glob. Dimensions are OR-ed, so an entry +scoped to `paths: [src/scripts/**]` and `labels: [area/ci]` shows up for either +trigger. At kick time Hive knows the lane and the issue labels; file paths are +known only to callers that have them (the mid-task advisor, tracked +separately), so a `paths`-only entry is a lookup target for an agent reading +this directory from its checkout until that lands. The gate is implemented by +hivecommons/hive#17045. + +## How the directory reaches the primer + +The primer reads vaults and git sources, not the repository checkout, so the +directory has to be registered once in `hive.yaml`: + +```yaml +knowledge: + enabled: true + git_sources: + - name: hive-repo-knowledge + url: https://github.com/hivecommons/hive + branch: v5 + subpath: src/docs/knowledge + layer: project +``` + +or, where the hive already has a checkout of the repo, as a vault pointing at +`<checkout>/src/docs/knowledge`. Either way the files are indexed by +`FileStore`, merged with the other layers by precedence, scoped by +`knowledge.agent_scopes`, and rendered into the kick's `# Relevant Knowledge` +block under the usual cap. Nothing in the entries is specific to Hive's +injection path: a CLI agent working from a plain checkout reads the same files +directly, picking the entries whose `scope.paths` match what it is about to +touch. + +## Entries moved out of AGENTS.md + +| Entry | Was | Applies when | +|---|---|---| +| `go-workspace-two-modules.md` | "src/ is a two-module Go workspace …" | editing Go under `src/` | +| `ci-is-the-verdict.md` | rationale behind "CI runs the tests, you do not" | any `src/` change, test-failure issues | +| `agent-pane-test-suite-hazard.md` | tmux / `/proc` / SIGKILL rationale, #9416 | `src/crux/agent/`, `src/pkg/dashboard/` | +| `changelog-fragment-exemptions.md` | the exact exemption set, `no-changelog`, `src/changelog.d/` trap | any `src/` or `changelog.d/` change | +| `docs-citation-guard.md` | `check-docs-citations.py --fix` how-to and what triggers the guard | `src/docs/`, hub/dashboard `server.go` and `static/` | +| `trusted-scripts-tree-repin.md` | `TRUSTED_SCRIPTS_TREE` re-pin | `src/scripts/`, `integration-governance.cjs` | + +The rules themselves (do not run the suite locally, never run it in an agent +pane, fragment required, `--fix` first) stay in `AGENTS.md`; only the facts and +reasons moved. diff --git a/src/docs/knowledge-lifecycle.md b/src/docs/knowledge-lifecycle.md index 11409928f3..db026c7803 100644 --- a/src/docs/knowledge-lifecycle.md +++ b/src/docs/knowledge-lifecycle.md @@ -34,7 +34,9 @@ Remote wiki layers only carry a `status`, which is mapped the same way. - **Kick primers** include approved facts only. Set `knowledge.PrimerConfig.IncludeStates` (`include_states`) to admit other - states. + states. An agent whose `knowledge.agent_scopes` entry lists `draft` is also + primed with the drafts it (or the hive owner) authored, marked `(draft)`; + see [Per-agent scopes](knowledge-toc.md#per-agent-scopes). - **`GET /api/knowledge/search`** returns approved facts only unless the operator passes `include_states`, e.g. `include_states=deprecated,superseded` or `include_states=all`. diff --git a/src/docs/knowledge-toc.md b/src/docs/knowledge-toc.md index 4e50e2b90c..ed07d9536f 100644 --- a/src/docs/knowledge-toc.md +++ b/src/docs/knowledge-toc.md @@ -79,6 +79,15 @@ only when the agent scope lists that state (or leaves `include_states` empty) too. An agent scope therefore never admits a state the operator did not ask for. +The kick primer makes one exception for an agent's own drafts (#17076). When +an agent scope lists `draft` (or `all`) explicitly, a kick for that agent also +carries draft entries whose `author:` (alias `owner:`) frontmatter matches the +agent name, its base agent (for replicas) or an owner login from +`dashboard.authorized_users`; they are rendered with a `(draft)` marker. +Drafts by other authors, and drafts without an author, remain excluded, and an +empty `include_states` does not opt in. TOC and entry reads are unaffected — +they keep the intersection rule above. + Config load rejects unknown layer names (`personal`, `project`, `org`, `community`) and unknown state names (`draft`, `approved`, `deprecated`, `superseded`, `all`). The scopes can also be read and replaced with @@ -108,6 +117,44 @@ only unless `include_states` is set), and returns: The dashboard Knowledge section has an **Effective knowledge** panel with an agent picker that renders both lists and each exclusion reason. +### Entry scope (`scope:` frontmatter) + +`knowledge.agent_scopes` says what an *agent* may see. An entry can also say +where *it* applies, with a `scope:` block in its frontmatter +(hivecommons/hive#17045): + +```yaml +--- +title: Editing src/scripts/ requires re-pinning TRUSTED_SCRIPTS_TREE +type: gotcha +layer: project +scope: + paths: [src/scripts/**, .github/scripts/integration-governance.cjs] + labels: [area/ci] + lanes: [] +--- +``` + +- `paths` are repo-relative globs (`**` matches any number of segments), + `labels` are issue labels and `lanes` are base agent names; `labels` and + `lanes` compare case-insensitively. Inline lists only — the frontmatter + parser is line-oriented and block lists (`- item`) inside `scope:` are + skipped. +- An entry **without** `scope:` behaves as before: keyword relevance plus the + agent's `knowledge.agent_scopes`. +- An entry **with** `scope:` is surfaced in a kick only when at least one + declared dimension matches the kick — its lane, a label on one of the primed + issues, or a file path the caller knows. Dimensions are OR-ed; a dimension the + kick cannot evaluate (file paths are not known on the kick path) simply does + not match. Related facts pulled in by graph expansion are gated the same way. +- The primer reports how many relevant entries the kick context excluded in the + `knowledge primed` log line (`scoped_out`) and in `PrimedKnowledge.ScopedOut`. + +The full read (`GET /api/knowledge/entry/{id}`) returns the entry's `scope` +inside `fact`, so an operator can see why an entry does or does not reach a +kick. The agent-level filter (`agent_scopes`) applies first; the entry's own +scope can only narrow further. + ### Prompt-size caps - `limit` defaults to 50 and is clamped to 200. diff --git a/src/docs/knowledge/agent-pane-test-suite-hazard.md b/src/docs/knowledge/agent-pane-test-suite-hazard.md new file mode 100644 index 0000000000..3ca3510a08 --- /dev/null +++ b/src/docs/knowledge/agent-pane-test-suite-hazard.md @@ -0,0 +1,16 @@ +--- +title: Running the test suite inside an agent pane kills the agent's own session +type: gotcha +layer: project +state: approved +tags: [repo:hivecommons/hive, testing, tmux, crux-agent, dashboard] +source: AGENTS.md (moved 2026-11-07, hivecommons/hive#17047) +scope: + paths: [src/crux/agent/**, src/pkg/dashboard/**] + labels: [] + lanes: [] +--- + +Parts of `crux/agent` and `pkg/dashboard` exercise real process management: tmux servers, `/proc` sweeps, and SIGKILL by uid. Run as an agent user, those tests can kill the agent's own tmux server, CLI and terminal. + +This is how the scanner lost its session repeatedly (hivecommons/hive#9416). It is the reason `AGENTS.md` says never to run this repository's test suite from inside an agent pane — the rule has no safe exception for "just this package". diff --git a/src/docs/knowledge/changelog-fragment-exemptions.md b/src/docs/knowledge/changelog-fragment-exemptions.md new file mode 100644 index 0000000000..0ee32a6335 --- /dev/null +++ b/src/docs/knowledge/changelog-fragment-exemptions.md @@ -0,0 +1,27 @@ +--- +title: Changelog fragment — exact exemption set and the no-changelog label +type: pattern +layer: project +state: approved +tags: [repo:hivecommons/hive, changelog, ci, pr-convention] +source: AGENTS.md (moved 2026-11-07, hivecommons/hive#17047) +scope: + paths: [src/**, changelog.d/**] + labels: [] + lanes: [] +--- + +Every PR with a user-visible `src/` code change needs a `changelog.d/<category>-<slug>.md` fragment (`added|changed|deprecated|fixed|security`) whose body is a single `- ` bullet. + +Exempt automatically — no fragment and no label needed: + +- changes outside `src/` (root-level docs, `changelog.d/`, `.github/`); +- `src/docs/`; +- `*_test.go` files; +- `src/{deploy,scripts}/test[-_]*.sh` scripts. + +`src/scripts/check-changelog-fragment.sh` is the source of truth for the exact set. + +Other test-adjacent changes (`testdata/` fixtures, non-`_test.go` test helpers) and non-user-visible `src/` code changes (refactors, dependency bumps) need the `no-changelog` label instead of a fragment. + +`changelog.d/` is at the repository root, not under `src/` — `src/changelog.d/` is never compiled and the guard rejects it. diff --git a/src/docs/knowledge/ci-is-the-verdict.md b/src/docs/knowledge/ci-is-the-verdict.md new file mode 100644 index 0000000000..945304f15d --- /dev/null +++ b/src/docs/knowledge/ci-is-the-verdict.md @@ -0,0 +1,18 @@ +--- +title: Why agents do not run go test locally — CI is the verdict +type: decision +layer: project +state: approved +tags: [repo:hivecommons/hive, testing, ci, policy] +source: AGENTS.md (moved 2026-11-07, hivecommons/hive#17047) +scope: + paths: [src/**] + labels: [kind/failing-test, kind/flake, kind/test] + lanes: [] +--- + +The rule in `AGENTS.md` is "do not run `go test`, `go build ./...`, `go vet`, `golangci-lint` or the docs/citation guards locally". The reasons: + +- CI runs the full matrix with the right toolchain, caches and coverage gates; a local run duplicates it and burns tokens and pod CPU/disk. +- Inside the hive pod, `go test` and `go vet` are blocked for agents by the Go shim, so the local run cannot succeed anyway. +- The hive opens requested PRs; CI is the sole verdict and records failures for agents to iterate on (`gh pr checks <n>`, then the failing job log). diff --git a/src/docs/knowledge/docs-citation-guard.md b/src/docs/knowledge/docs-citation-guard.md new file mode 100644 index 0000000000..2fea49e1ef --- /dev/null +++ b/src/docs/knowledge/docs-citation-guard.md @@ -0,0 +1,18 @@ +--- +title: Fixing src/docs file:line citation drift +type: pattern +layer: project +state: approved +tags: [repo:hivecommons/hive, docs, citations, ci] +source: AGENTS.md (moved 2026-11-07, hivecommons/hive#17047) +scope: + paths: [src/docs/**, src/pkg/hub/**, src/pkg/dashboard/**, src/scripts/check-docs-citations.py, src/scripts/check-api-reference-citations.sh] + labels: [kind/documentation, documentation] + lanes: [] +--- + +Do not hand-edit `src/docs` file:line citations (including `src/docs/api-reference.md` and `src/docs/api-reference/*.md`). + +When CI's citation guard reports drift, run `python3 src/scripts/check-docs-citations.py --fix` first. It runs `check-api-reference-citations.sh --fix` for `api-reference.md` and re-anchors other `.go` citations by their backticked Go declaration anchor. Fall back to a manual edit only for citations it still reports as `DRIFT` / `UNRESOLVED`, and run it only when CI tells you citations drifted. + +The required `changelog-fragment-guard` check runs the guard (non-fix) when a PR edits a hub or dashboard `server.go` or their `static/` pages, so the PR that causes drift goes red. diff --git a/src/docs/knowledge/go-workspace-two-modules.md b/src/docs/knowledge/go-workspace-two-modules.md new file mode 100644 index 0000000000..586d937528 --- /dev/null +++ b/src/docs/knowledge/go-workspace-two-modules.md @@ -0,0 +1,16 @@ +--- +title: src/ is a two-module Go workspace +type: reference +layer: project +state: approved +tags: [repo:hivecommons/hive, go, crux, workspace] +source: AGENTS.md (moved 2026-11-07, hivecommons/hive#17047) +scope: + paths: [src/**/*.go, src/go.work, src/go.mod, src/crux/go.mod] + labels: [area/core, area/scheduler] + lanes: [] +--- + +`src/` is a two-module Go workspace (`src/go.work`): the root module and the Crux agent runtime at `src/crux/` (`github.com/hivecommons/hive/crux`, packages `crux`, `crux/agent`, `crux/inference`, …). + +From `src/`, `./...` is the root module only; the Crux module is `./crux/...`. CI covers both. Design background: `src/docs/design/crux.md`. diff --git a/src/docs/knowledge/trusted-scripts-tree-repin.md b/src/docs/knowledge/trusted-scripts-tree-repin.md new file mode 100644 index 0000000000..b65e046523 --- /dev/null +++ b/src/docs/knowledge/trusted-scripts-tree-repin.md @@ -0,0 +1,14 @@ +--- +title: Editing src/scripts/ requires re-pinning TRUSTED_SCRIPTS_TREE +type: gotcha +layer: project +state: approved +tags: [repo:hivecommons/hive, ci, governance, scripts] +source: AGENTS.md (moved 2026-11-07, hivecommons/hive#17047) +scope: + paths: [src/scripts/**, .github/scripts/integration-governance.cjs] + labels: [] + lanes: [] +--- + +A PR that edits anything under `src/scripts/` must re-pin `TRUSTED_SCRIPTS_TREE` in `.github/scripts/integration-governance.cjs` to `git rev-parse HEAD:src/scripts` (of the post-merge tree); otherwise `build-and-test` fails. diff --git a/src/docs/labels-and-control-signals/reference.md b/src/docs/labels-and-control-signals/reference.md index bf13833c37..39534ea5a0 100644 --- a/src/docs/labels-and-control-signals/reference.md +++ b/src/docs/labels-and-control-signals/reference.md @@ -834,7 +834,7 @@ Same exempt behavior as `do-not-merge`; wins over required-label admission. Defa **Applies to:** PRs (issues when a step on one is blocked). **Kind:** Human-gated hold. -The hive's GitHub App was refused (`403 Resource not accessible by integration`) on an API call the lane needs to advance, so only a person can take the next step. First wired call site: approving held `action_required` workflow runs for a registry-trusted author needs `actions: write`, which an operator may decline to grant ([#14589](https://github.com/hivecommons/hive/issues/14589)). The lane reports `unauthorized:<step>` (`unauthorized:approve-workflow-runs`), the stage engine parks the PR at 085, one `<!-- hive:unauthorized head=<sha> step=<step> -->` comment names the missing permission, the exact human step (**Approve and run** on the checks banner or Actions tab, with the run ids) and the alternative of granting the permission, and the hive logs `lane unauthorized` once per head at INFO instead of a WARN per tick. +The hive's GitHub App was refused (`403 Resource not accessible by integration`) on an API call the lane needs to advance, so only a person can take the next step. First wired call site: approving held `action_required` workflow runs for a registry-trusted author needs `actions: write`, which an operator may decline to grant ([#14589](https://github.com/hivecommons/hive/issues/14589)). The lane reports `unauthorized:<step>` (`unauthorized:approve-workflow-runs`), the stage engine parks the PR at 085, one `<!-- hive:unauthorized step=<step> -->` comment per PR and step names the missing permission, the exact human step (**Approve and run** on the checks banner or Actions tab, with the run ids) and the alternative of granting the permission — a further head hitting the same block edits that comment with an attempt count and the heads it covers instead of posting again ([#17066](https://github.com/hivecommons/hive/issues/17066)) — and the hive logs `lane unauthorized` once per head at INFO instead of a WARN per tick. The activity monitor draws a muted `unauthorized` pill (counted under Needs attention) whose tooltip repeats the permission and the step, and the 085 cell reads **Awaiting human: approve workflow runs**. diff --git a/src/docs/labels-and-control-signals/stage-labels.md b/src/docs/labels-and-control-signals/stage-labels.md index 4f149992ac..fce622ce22 100644 --- a/src/docs/labels-and-control-signals/stage-labels.md +++ b/src/docs/labels-and-control-signals/stage-labels.md @@ -626,11 +626,14 @@ and name the rule; an open sentinel alert is named as a label a maintainer must clear first (projectbluefin/testsuite#1037). Only a head made solely of App-signed commits the hive never pushed — a person's own commit made with the App's identity — goes back to its author by kind under -`hive-signoff-attribution`: `071` for a human, `072` for a clanker — never +`hive-signoff-attribution`: `071` for a human, `072` for a contributor agent — never `070`, where nothing can act. The human -gets one comment per head (`<!-- hive:signoff-attribution head=… -->`) with +gets one comment per PR (`<!-- hive:signoff-attribution -->`) with the exact fix (`git commit --amend --reset-author -s && git push --force-with-lease`, or the `git rebase --exec` form for several commits); +a new head rewrites that comment in place and appends an `updated …` line +(history capped at five) instead of posting another copy +([#17066](https://github.com/hivecommons/hive/issues/17066)); the contributor agent's regular 072 nudge carries the same ask. An adoption cannot fix it by rewriting (the hive may not touch the contributor's authorship, and a supersede would carry the same head), and the hive's own in-place fix @@ -808,15 +811,19 @@ When a contributor-agent PR goes red the hive does not just relabel it (a human- [hive-merge.md](../hive-merge.md#stage-labels)): 1. `stage/072-returned-to-contributor` and ONE `<!-- hive:contributor-nudge - head=<sha> n=<1|2> mode=<comment|queued|spawn|preempt> -->` comment - @-mentioning the author with the failing checks / review asks and "reply - here or push a new head". When the CI gate names no check (a base branch - with no required checks), the nudge lists the checks that are red on the - head instead of the gate's `check-failure` token. Re-posted only for a new head; re-nudged once - more after `governor.labels.stage.contributor_nudge.renudge_interval` - (default = the stage's 24h dwell, i.e. at `stage/stalled`), then no more - — **cap: 2 nudges per head**. `mode=` records how the relay side was - handled so the comment itself answers "did their agent get interrupted?". + reason=<slug> head=<sha> n=<1|2> mode=<comment|queued|spawn|preempt> -->` + comment per PR and reason class @-mentioning the author with the failing + checks / review asks and "reply here or push a new head". When the CI gate + names no check (a base branch with no required checks), the nudge lists + the checks that are red on the head instead of the gate's `check-failure` + token. A new head or a + changed reason **edits** that comment in place (no notification) rather + than posting another; re-nudged once more after + `governor.labels.stage.contributor_nudge.renudge_interval` (default = + `auto_merge.nudge_repeat_after`, 72h) if the same condition persists, + then no more — **cap: 2 nudges per PR + reason**. `mode=` records how + the relay side was handled so the comment itself answers "did their + agent get interrupted?". `governor.labels.stage.contributor_nudge.enabled: false` turns the comment and the relay task off; the stage label still moves. 2. Relay contributors (the author has a contributor profile and a live relay diff --git a/src/docs/manual-provisioning.md b/src/docs/manual-provisioning.md index fbf2ffb391..0b808a6662 100644 --- a/src/docs/manual-provisioning.md +++ b/src/docs/manual-provisioning.md @@ -1689,6 +1689,22 @@ provision. Two pools, one per method type: - **Hub-reachable-cluster** placeholders serve **public** methods — provisioned via the API (Path A) and left running at **`replicas: 1`**. +**Auto-pick on approve.** When an admin approves a provision request without +choosing a specific placeholder, the hub picks one from the pool matching the +request's `auth_method`: `private` → the heartbeat-only/GPU pool, anything else +→ the default hub-reachable pool (`hive-oke`). The **public preference is +soft**: if the default pool has no `available` placeholder, Auto-pick falls back +to any *other* cluster registered in `clusters.json` that has one — most +available first, ties broken by cluster ID — and logs one line +(`approve: pool hive-oke empty, falling back to lke648397`). Two pins stay +**hard** and never fall back: a `private` request only ever draws from the GPU +pool, and the GPU pool is never used to satisfy a public request. Clusters with +placeholders on disk but no `clusters.json` entry are skipped. The admin's +explicit pick in the approve modal is strict — if that placeholder is not +available the approve returns `409`, regardless of capacity elsewhere. +Only when every eligible pool is empty does Auto-pick return +`409 no available placeholder hive in pool "hive-oke" or any other registered pool`. + > **Gotcha — placeholder IDs are date + random suffix, NOT sequential integers.** > The live pool uses `hosted-available-<cluster>-<YYMMDD>-<suffix>`, where > `<suffix>` is a short unique token (4 lowercase base36 chars) — e.g. diff --git a/src/docs/move-hub-registered-cutover.md b/src/docs/move-hub-registered-cutover.md index 7783b6042f..50c75d9365 100644 --- a/src/docs/move-hub-registered-cutover.md +++ b/src/docs/move-hub-registered-cutover.md @@ -38,7 +38,7 @@ move procedures in the other guides should regenerate: - **`HIVE_HUB_SECRET`** — the hub's master secret, present in the spoke's own pod env. Every per-hive derived key (heartbeat bearer, session key, invite key, terminal key) is `HMAC(HIVE_HUB_SECRET, domain-string, HIVE_ID)` — - see `src/docs/env-vars.md:305-320` and, for the heartbeat bearer + see `src/docs/env-vars.md:306-321` and, for the heartbeat bearer specifically, `src/docs/heartbeat-bearer-cutover.md`: ``` diff --git a/src/docs/native-merge-queue.md b/src/docs/native-merge-queue.md index ebd97271be..11f1a0bdd8 100644 --- a/src/docs/native-merge-queue.md +++ b/src/docs/native-merge-queue.md @@ -220,13 +220,16 @@ metadata, not a fabricated last-member PR event. in-progress); the queued run re-reads mutable PR state after the prior run finishes, preserving fail-closed semantics. Labels the policy never reads (`size/*`, `dco-signoff`, stage labels, ...) skip the wait: the job replays - the latest completed `native-queue-policy` `success` on the same head and - still checks the live PR for holds, draft and head moves. When there is no + the latest completed `native-queue-policy` `success` on the same head, + still checks the live PR for holds, draft and head moves, and re-validates + the five policy checks on that head — a provider re-run red since the + original verdict fails the job instead of being replayed. When there is no prior success to replay (never evaluated, or the last wait failed or timed - out) or GitHub returns a 5xx, the job falls through to the full wait so a - stale red verdict is never pinned onto later cosmetic flips. `hold`, - `needs-human`, `release-in-progress` and `do-not-merge*` flips always get - the full wait. + out), a policy provider is still pending or missing on the head, the DCO + provider reports UNKNOWN, or GitHub returns a 5xx, the job falls through to + the full wait so a stale verdict is never pinned onto later cosmetic flips. + `hold`, `needs-human`, `release-in-progress` and `do-not-merge*` flips + always get the full wait. - On a group it executes the event's trusted `base_sha` validator. It reads the live queue prefix ending at the event's exact synthetic head, verifies contiguous membership and the base/head commit chain, and checks @@ -243,6 +246,18 @@ metadata, not a fabricated last-member PR event. this bridge does not turn its underlying implementation into a strict content validator. Dependabot runs that same trusted PR-target verifier rather than skipping it; skipped policy evidence is never exempted by actor. +- One narrow exception replaces probot `DCO` (#17030): a PR whose head + branch is exactly `sync/v5-to-v6` in this repository, whose base is `v6`, + and which was opened by `github-actions[bot]` (the `v6-topup.yml` + identity). Every PR commit except the head must be reachable from `v5` + (compare API `v5...<sha>` is `behind`/`identical`), the head must be the + top-up's two-parent merge of `v5` history onto `v6` history, and the list + must stay under the REST 250-commit cap. Those commits already passed v5's + DCO gate and probot cannot be repaired PR-side, so the latest prow `dco` + commit status created by `kubestellar-prow[bot]` must be `success` instead; + a `dco` status from any other creator is ignored. Any unmet condition falls + back to requiring probot `DCO`. The check output names the DCO path taken + and, on fallback, why. - Draft/held PRs, changes requested, dismissed approvals and approvals on an old head fail closed. A `pull_request_target` run on an already closed or merged PR (re-fired by a post-merge label or comment edit) passes as a @@ -387,7 +402,8 @@ handles rejected/broken heads; there is no second fixer or merge engine. history, admission reports **DCO provider unavailable / verdict UNKNOWN** and remains blocked. Follow the [provider diagnosis and recovery runbook](operator-reference/dco-provider-unavailable.md); a provider enumeration failure does not request a PR source change or permit - substitution of the lowercase prow `dco` status. + substitution of the lowercase prow `dco` status outside the narrow + `sync/v5-to-v6` forward-merge path above. - Inspect the PR's exact-head checks and the **group SHA** checks separately. A green member head does not establish green integration evidence. `native-queue-policy` logs the failing provider, provenance, membership, diff --git a/src/docs/notifications.md b/src/docs/notifications.md index 15f2829a9e..c44ee86374 100644 --- a/src/docs/notifications.md +++ b/src/docs/notifications.md @@ -697,7 +697,11 @@ issue gets the same card, written through the same single status writer reopened-after-merge (`issue-reopened`), a lapsed claim's stage regression (`stage-regressed`), the covering-PR stage note (`issue-pr-link`), the relay's one-line state notes — awaiting CI, parking, already fixed — - (`agent-note:<state>`), the decision-downgrade note left when a label + (`agent-note:<state>`), an agent's free-text relay comment whose only + marker is the identity footer's `<!-- hive:origin … -->` + (`agent-note:origin`, latest note; outside quiet mode these append to the + one `<!-- hive:origin-notes -->` comment per item instead, last 10 kept — + hivecommons/hive#17067), the decision-downgrade note left when a label change walks back an earlier maintainer decision (`issue-decision-downgrade`) and the blocker-settled note (`unblocked`, whatever `mode` says). Claim notes and the relay state notes already fold diff --git a/src/docs/operator-reference/README.md b/src/docs/operator-reference/README.md index bef691a682..31d34753fe 100644 --- a/src/docs/operator-reference/README.md +++ b/src/docs/operator-reference/README.md @@ -284,7 +284,8 @@ Go callers keep reading `cfg.Agents`, `cfg.Governor.Gateways` and so on through | `review.severity.block_at` | Unset; owner-only. | Lowest finding priority that blocks merge: `P1` (ship fast, P0–P1 block), `P2` (strict, P0–P2 block) or `P3` (everything blocks). Also drives `classification.review_bots.min_priority` when that key is not set in `hive.yaml` or `hive-project.yaml`. Any other value fails load naming the field. Features -> Review gate -> Severity & backlog. See [review-swarm.md](../review-swarm.md#blocking-line-reviewseverity-reviewbacklog). | | `review.severity.comment_below` / `backlog_below` | `true` / `true`; owner-only. | Whether findings below the blocking line are posted as non-blocking comments and filed to `review.backlog`. | | `review.backlog.destination` | `github_issue`; owner-only. | `github_issue`, `github_project`, `linear` or `jira`. The last three need the matching `governor.work_source.type` (`github_projects`, `linear`, `jira`); on a mismatch the hive falls back to `github_issue`. Destination fields: `project_column_id` (required for `github_project`), `linear_state`, `jira_status`. | -| `review.backlog.labels` / `max_per_pr_per_day` | `[agent/reviewer]` / `10`; owner-only. `from-review`, `origin/review`, and `origin/reviewer` are accepted and mapped to `agent/reviewer`. | Labels on every backlog item and the per-PR-per-day cap (negative fails load; 0 = default). Reviewer is an agent lane, so `agent/reviewer` is the routing/ownership/provenance label. Non-lane hive issue filers continue to use `origin/selfreport`, `origin/governor`, `origin/dashboard`, `origin/forge`, or `origin/convergence`; the one-time startup migration (`/data/origin-label-migration-v4.done`) removes redundant lane-origin labels and backfills only non-lane origins. | +| `review.backlog.labels` / `max_per_pr` | `[agent/reviewer]` / `3`; owner-only. `from-review`, `origin/review`, and `origin/reviewer` are accepted and mapped to `agent/reviewer`. | Labels on every backlog item and the per-PR lifetime cap on items filed (negative fails load; 0 = default; `max_per_pr_per_day` is a retired alias for the size). New findings from one pass sharing a perspective collapse into one checklist item. Reviewer is an agent lane, so `agent/reviewer` is the routing/ownership/provenance label. Non-lane hive issue filers continue to use `origin/selfreport`, `origin/governor`, `origin/dashboard`, `origin/forge`, or `origin/convergence`; the one-time startup migration (`/data/origin-label-migration-v4.done`) removes redundant lane-origin labels and backfills only non-lane origins. | +| `review.backlog.min_severity` | `P2`; owner-only. `P0`–`P3`; invalid fails load. | Lowest finding priority that is filed as a backlog item. Findings below it (P3 `low`/`info` by default, every docs-currency nit included) go to one upserted `hive:review-followups` comment on the PR instead. `P3` files every finding, as before [#17065](https://github.com/hivecommons/hive/issues/17065). | | `review.reviewers.autoscale.*` | `enabled: false`; when on: `min: 1`, `max: 4` (≤ the replicas cap 5), `target_backlog_per_reviewer: 2`, `scale_up_cycles: 2`, `scale_down_cycles: 5`, `cooldown: 5m`, `cpu_per_reviewer: 1.0`, `mem_per_reviewer_mb: 2048`, `agent` unset (first `role: reviewer` agent, else `reviewer_agents[0]`); owner-only. | Sizes the reviewer lane to its backlog ([#14685](https://github.com/hivecommons/hive/issues/14685)): adds a `reviewer-N` replica after `scale_up_cycles` cycles with more PRs waiting for a free reviewer than `target_backlog_per_reviewer` per reviewer (or a wait older than the review-pending stage dwell), drains the top replica after `scale_down_cycles` idle cycles and retires it only when its turn ends. Scale-ups are refused by named guards (`at-max`, `cooldown`, `saturated` kicks, `provider-budget`, `provider-headroom`, `max-parallel-reviews`, cgroup `cpu` / `memory`). Decisions log as `reviewer autoscale: 2→3 reason=…`; state is in `/api/status.reviewerAutoscale`. See [review-swarm.md](../review-swarm.md#reviewer-autoscale-reviewreviewersautoscale). | | `review.contributor_prs.base_sync` | Off by default; owner-only. | Lets PR follow-up use GitHub's update-branch API on hive-authored lane PRs whose head is in a contributor fork, whose `mergeable_state` is `behind`/`dirty`, and whose author enabled "allow edits by maintainers". `behind` PRs get a GitHub-authored merge commit; `dirty`/422 falls back to the `hive-base-moved` repair note and kick. This requires an agent/proxy mode with `ISSUES_PRS_MERGE` because `PUT /pulls/{n}/update-branch` is merge-scoped. It does not rewrite history and does not add a human/bot-authored DCO commit; the repository's "Sign-off survives the squash" check examines the PR's own commits, not GitHub's update-branch merge commit. It also gates serialized-lane fork base syncs; when off, a behind fork PR leaves the lane front. | | `governor.advisory.post_retry_backoff_s` | `3600` seconds. `HIVE_ADVISORY_POST_RETRY_BACKOFF_S` overrides the default when the key is unset; a negative value disables the pause. | How long the advisory digest write is paused after GitHub refuses it with `403 Resource not accessible by integration`. That refusal is structural (foreign-authored comment, repo dropped from the installation, or repo transferred to another owner), so per-cycle retries only burn API quota. The failed edit first falls back to creating a fresh App-authored comment; if the create is refused too, the error is recorded for the hub health row — naming the new `owner/repo` when the repository has moved — and attempts pause for this window. See [advisory.md](../advisory.md#when-the-write-is-refused). | @@ -318,9 +319,10 @@ Go callers keep reading `cfg.Agents`, `cfg.Governor.Gateways` and so on through | `knowledge.connectors[].scope` (`notion`) | All pages shared with the integration; `max_pages` `2000`; `full_sync_every` `10`. | Optional `root_page_ids` / `database_ids`; `include_archived` fetches bodies of archived pages. Pages must be shared with the internal integration (••• → Connections). Requests are spaced 350 ms apart. | | `knowledge.publish` | Unset (`connector` empty): publishing off. | One-way mirror of curator-promoted facts into one connector target: `connector` (a `knowledge.connectors` name whose type can publish), `layers` (`project`/`org`/`community`; personal is never published), `root`, optional `include_types`, `dry_run`, `propose_via`. Facts are read from each layer's `knowledge.layers[].path`. Started at boot (a bad connector logs `knowledge publish mirror disabled` and leaves publishing off); state in `/data/knowledge/connector-state/_publish`. Status in the `publish` object of `GET /api/knowledge/connectors`; owner-only `POST /api/knowledge/publish/sync`. See [knowledge-connectors.md](../knowledge-connectors.md#publish-mirror). | | `knowledge.bead_synthesizer.publish` | Off (`enabled: false`). | Publishes synthesized facts into a repository through one PR on `hive/bead-synth-knowledge`: `enabled`, `repo` (empty = `project.primary_repo`), `path` (default `docs/knowledge/`; `.hive/knowledge/` is the alternative; relative, no `..`), `base_branch` (empty = repo default branch), `mode` (`pr` default or `commit`), `cadence` (`per_run` default or `daily`). ACMM L<=4 hives publish via PR only; `commit` is warned about and still opens a PR. See [knowledge-curator.md](../knowledge-curator.md#repository-publish-knowledgebead_synthesizerpublish). | +| `knowledge.advisor` | Off (`false`). | Mid-task knowledge advisor (#17052): on each poll tick, when a running agent's pane shows work in a scope (directory prefix or `gh pr`/`issue`/`run` family) that was not on screen at kick time, matching knowledge entries the kick did not already carry are typed into the session as one `📚 Knowledge:` line each. `advisor_max_per_kick` (default `3`) caps lines per kick; `advisor_exclude_agents` lists agent or replica-family names to skip. Never typed during a tool call, after the turn ends, while a human is attached, or in the `crux serve` sidecar. Each delivery lands in prompt history with trigger `knowledge-advisor`. See [knowledge-curator.md](../knowledge-curator.md#mid-task-knowledge-advisor-knowledgeadvisor). | | `variables.security.*` | Deny by default. | `allow_exec`, `allow_http`, and GitHub prompt-source allowlists are honored only from the trusted seed, not dashboard overlays. | | `agents.<name>.prompt_source` (size cap) | 96 KiB (`promptsrc.DefaultMaxPromptBytes`); `HIVE_PROMPT_SOURCE_MAX_BYTES` overrides it. | A fetched kick template over the cap is **rejected whole, not truncated** ([#12130](https://github.com/hivecommons/hive/issues/12130)): the kick uses the last successfully fetched copy if there is one, otherwise the ordinary `kick_template` → pack → convention → embedded-default chain, and the scheduler logs `prompt from GitHub exceeds size cap; REJECTED whole (not truncated), falling back` with `repo`, `path`, `size_bytes` and `cap_bytes`. Saving an agent whose source is over the cap fails in the dashboard with the same sizes rather than baking a cut-off policy. A half-policy is a policy with its closing rules missing; no remote policy is the safer failure. Every shipped template fits with >2× headroom (`TestShippedTemplatesFitUnderCap`). | -| `data.claude_sessions_dir` | `/data/home/.claude/projects` | Where the dashboard reads Claude Code session JSONL for per-agent token/cost accounting. Point it at the agents' real session directory if you relocate `HOME`. | +| `data.claude_sessions_dir` | `/data/home/.claude/projects` | Where the dashboard reads Claude Code session JSONL for per-agent token/cost accounting. When it has the canonical `<home>/.claude/projects` shape the scan also covers every per-agent `<home>/agents/*/.claude/projects` ([#17031](https://github.com/hivecommons/hive/issues/17031)); `data.bob_sessions_dir` and `data.copilot_sessions_dir` behave the same way. Point it at the agents' real session directory if you relocate `HOME`. The `.claude` tree is also where Claude Code keeps its persistent auto-memory; see [agent-knowledge-and-memory.md](../agent-knowledge-and-memory.md) for which per-agent home paths are fleet-shared and what `clear_on_kick` does and does not clear. | | `data.copilot_sessions_dir` | `/data/home/.copilot/session-state` | Same, for the Copilot CLI backend's session state. | ### Label-driven approval @@ -507,6 +509,7 @@ advanced into the merge path. | `auto_merge.self_authored` | **on** when unset | The only off switch. `false` disables the sweep and App-authored PRs fall back to fully manual merges. | | `auto_merge.max_merges` | `3` (`DefaultAutoMergeSweepMaxMerges`) when 0/unset | Caps merges per sweep pass. | | `auto_merge.min_head_age` | `3m` | Minimum PR head age before automerge trusts an unknown required-check set. A fresh head pushed more recently than this waits with `pending: head pushed ... ago (< min_head_age)` unless `auto_merge.required_checks` is declared and every required check is complete and successful. Head age is measured from the head commit's committer date (never earlier than the PR's creation), not the PR's `updated_at`, so label and comment activity — including the hive's own — does not restart it. When GitHub's head time is ahead of the host clock (clock skew), age is measured from when the hive first observed the head instead, so the hold lasts one window and then clears (`pending: head time ahead of host clock; head first seen ... ago (< min_head_age)`). | +| `auto_merge.nudge_repeat_after` | `72h` | How long a contributor nudge's condition must persist before the hive nudges once more. Nudges are one comment per PR and reason class, edited in place for a new head or changed reason; after this interval with the same condition the comment is re-posted once (cap 2 per reason), then never again. `governor.labels.stage.contributor_nudge.renudge_interval`, when set, overrides it. | | `auto_merge.required_checks` | unset | Default operator-declared status-check contexts / check-run names (e.g. `["build-gate"]`) that the sweep's green gate requires on repos without a per-repo override. See below. | | `auto_merge.repos.<repo>.required_checks` | inherits default | Per-repo override for heterogeneous hives. `<repo>` may be the bare name from `project.repos` or `owner/repo`; an explicit empty list declares that GitHub has no required contexts, while Hive still requires positive CI evidence from at least one real successful check-run before merge. | | `auto_merge.allow_unprotected_base` | deprecated no-op | Accepted for compatibility only. [`hive-merge`](../hive-merge.md) no longer refuses solely because a base branch has no GitHub branch protection; it may merge into any branch the App can write after positive CI evidence. | diff --git a/src/docs/operator-reference/dco-provider-unavailable.md b/src/docs/operator-reference/dco-provider-unavailable.md index 7c4d51e086..008b69d89b 100644 --- a/src/docs/operator-reference/dco-provider-unavailable.md +++ b/src/docs/operator-reference/dco-provider-unavailable.md @@ -101,3 +101,7 @@ Preserve the true merge ancestry of #16378. Splitting/rebasing the forward merge, adding empty commits, accepting the lowercase prow `dco` status, or weakening protection does not repair this provider failure. Until authoritative current-head DCO success exists, the correct admission outcome remains blocked. +The only exception is the narrow `sync/v5-to-v6` forward-merge path in +[native-merge-queue.md](../native-merge-queue.md#required-checks-and-provider-boundaries) +(#17030), where every carried commit is already on `v5`; any other PR, or a +top-up carrying a commit not reachable from `v5`, still needs App-1861 DCO. diff --git a/src/docs/operator-reference/sweeps-and-operations.md b/src/docs/operator-reference/sweeps-and-operations.md index 571c88a2d8..2e6ca7b707 100644 --- a/src/docs/operator-reference/sweeps-and-operations.md +++ b/src/docs/operator-reference/sweeps-and-operations.md @@ -95,9 +95,10 @@ on; `governor.labels.stage.enabled: false` stops the reconciler, `governor.labels.stage.stalled.require_quiet: false` measures the dwell from stage entry instead of last activity (Settings → Labels). When a clanker PR enters -`stage/072-returned-to-contributor` the hive posts one nudge comment per head -(re-nudged once after `governor.labels.stage.contributor_nudge.renudge_interval`, -default = the 24h dwell; cap 2) and, for a contributor whose relay heartbeat is +`stage/072-returned-to-contributor` the hive keeps one nudge comment per PR +and reason class, edited in place for a new head or changed reason (re-nudged +once after `governor.labels.stage.contributor_nudge.renudge_interval`, +default = `auto_merge.nudge_repeat_after`, 72h; cap 2 per reason) and, for a contributor whose relay heartbeat is within `governor.labels.stage.presence_window` (default 15m), pushes a `fix-pr` interrupt to their relay session, bounded by the per-contributor fix budget (`contribute.max_parallel_fixes` / `contribute.min_focus_window`). @@ -886,6 +887,14 @@ level=INFO msg="kick rendered" agent=scanner repo="" kick_bytes=58123 issues_tot `kick_bytes` is the prompt as typed (canary preamble included). When `issues_listed` / `prs_listed` sit well below the caps on every kick, lowering them changes nothing; when `*_total` is persistently far above `*_listed`, the backlog — not the cap — is the problem, and the overflow marker in the prompt already tells the agent the list is partial. Per-agent kicks share the same global caps; set them under **Settings → Repos → Kick prompt list caps** or in `governor.kick_limits`, with `0` meaning unlimited. +**The knowledge share of a kick.** Next to `kick rendered`, each kick that was primed logs one knowledge line ([#17049](https://github.com/hivecommons/hive/issues/17049)): + +``` +level=INFO msg="knowledge: injected 3900 bytes from 7 entries (skipped 3 for cap)" agent=developer injected_bytes=3900 entries=7 skipped_for_cap=3 cap_bytes=4096 primed=true agents_md_bytes=1980 skills_bytes=0 +``` + +`injected_bytes` / `entries` are the rendered `# Relevant Knowledge` block; `skipped_for_cap` counts relevant facts dropped whole because they did not fit `knowledge.primer.max_bytes` (`cap_bytes`); `agents_md_bytes` and `skills_bytes` are the repository `AGENTS.md` block and the requested-skills block that share the kick. A zero line (`primed=true`, 0 entries) means priming ran and found nothing relevant — the signal that the store lacks entries for that lane's work. The line is not emitted when knowledge is disabled or there was nothing to prime, so a hive without a knowledge store does not log a zero on every kick. Read it against `src/docs/knowledge-entries.md` when deciding whether a fact belongs in `AGENTS.md` (paid on every kick) or in a scoped entry (paid only when it matches). + ### What consumes tokens while agents are paused Pausing agents (including the navbar fleet breaker) does not take the Hive instance down: the dashboard, governor scans, GitHub polling, token scanners, repo-cost collectors, telemetry/heartbeats, and provider-headroom probes can keep running. Those components should not make model calls by themselves. Model usage is expected from agent sessions reached through governor/manual/CEL/resume kicks; those kick paths share the same pause and budget gates. Knowledge priming reads configured knowledge stores and attaches facts to kicks; it does not independently call the model while every agent is paused. Provider-budget probes are the exception by design: after a provider spend-limit rebuff, Hive may release one kick after `governor.provider_budget.probe_interval_s` to test recovery. diff --git a/src/docs/release-channels.md b/src/docs/release-channels.md index 2ceb26801d..ca7535593b 100644 --- a/src/docs/release-channels.md +++ b/src/docs/release-channels.md @@ -10,7 +10,7 @@ Registry (**GHCR**). |---|---| | `stable` | Newest build promoted as generally safe to run. | | `candidate` | A v5 build awaiting the observation/waiting period (“soak”) before stable promotion. | -| `edge` | An active-development v6 build, with no soak period; not the newest v5 stable build. | +| `edge` | The newest v6 build, with no soak period; not the newest v5 stable build. Since 2026-11-07 v6 is a release line, so the same digest also carries an immutable `v6.x.y` tag once cut. | > **Promotion policy:** the channels diverge by release line and maturity. Every green merge to **`v5`** retags **`candidate`** (and `:latest`); **`stable`** advances later by digest through the scheduled/manual stable-promotion workflow after the [stable soak and promotion policy](stable-soak-policy.md) passes. Merges to **`v6`** retag **`edge`**, so `edge` is an active-development v6 build, not a synonym for `stable`. **`v4`** is a maintenance line: its builds publish only `v4-latest` and short-SHA tags, no channel (#7721 Phase 1). diff --git a/src/docs/release-line-guard.md b/src/docs/release-line-guard.md index efa693f789..ddcc5068aa 100644 --- a/src/docs/release-line-guard.md +++ b/src/docs/release-line-guard.md @@ -62,30 +62,10 @@ and turns cutting `v5` into one edit that CI enforces. ## Cutting a new release line 1. Add the branch name to `release_lines` in `.github/release-lines.yml`. -2. Add it to the trigger block of every workflow listed under `pinned`. +2. Add it to the trigger block of every workflow listed under `pinned`, or + write down a `-name` exclusion with the reason. 3. Add it to every list under `env_lists` — today that is `docker.yml`'s `LONG_LIVED`, without which the new line builds but never publishes. - -Doing only step 1 fails the guard, naming each workflow that would not run on -the new branch and each list that would not publish it. That is the -demonstration -`src/scripts/test-release-lines-guard.sh` performs in CI, against the real -workflow files: - -``` -FAIL: v2-ci.yml:5 branches: has [v2,v4], expected [v2,v4,v5] — missing: v5. - A release line named here but absent from the workflow means that - workflow does not run on it at all. -FAIL: docker.yml:56 env LONG_LIVED: has [dd,mk,v2,v4], expected - [dd,mk,v2,v4,v5] — missing: v5. This list is not a trigger, so a release - line missing from it fails GREEN: the image still builds on that branch - and simply never publishes its <branch>-latest tag, leaving no image for - a hive to be assigned to. -``` - -The check is an equality in both directions, so *retiring* a line is proven -complete the same way: every list still naming it is reported as `unexpected`. - Those three steps are what the guard enforces. They are not the whole cut: a release line also cuts `vN.x.y` tags and, when it becomes the stable line, owns the `candidate`/`latest`/`stable` channels. The v4→v5 cut @@ -103,28 +83,47 @@ the new line's branch unless noted: branch fails at its first step instead of releasing or promoting another line. The check reads the script and manifest from the workflow's own ref, before the commit being released is checked out, and - `tagged-release.yml` accepts a `docker.yml` run only when it was a `push`, - so a fork PR whose branch is named after a release line cannot approve - itself. `derive-release-version.sh` mints `vN.0.0` as the first tag of a - line on its own. Do **not** reintroduce a literal branch name in either - workflow. -5. **Channels — `docker.yml` on both branches, landed together.** Each + `tagged-release.yml` accepts a `docker.yml` run only when it was a `push` + or `workflow_dispatch`, so a fork PR whose branch is named after a release + line cannot approve itself. `derive-release-version.sh` mints `vN.0.0` as + the first tag of a line on its own. Do **not** reintroduce a literal + branch name in either workflow. +5. **Carry the cut to the new line's branch.** `workflow_dispatch` runs read + the workflow, the manifest and the scripts from the dispatched ref, so the + new line's own copies of `.github/release-lines.yml`, + `tagged-release.yml`, `promote-stable.yml` and `check-release-lines.sh` + must have the change too — forward-merge (top-up) it, or land it there + directly. Until then the new line's copy still refuses. +6. **Non-default lines release through the relay.** `schedule` and + `workflow_run` triggers only fire from the repository's default branch, so + the hourly backstop and the hourly `stable` promotion follow it. The + default copy of `tagged-release.yml` carries a `relay` job: when + `docker.yml` completes a `push`/`workflow_dispatch` build on another + declared release line, it dispatches `tagged-release.yml --ref <line>`, + and that line's own copy takes the backstop path (resolve the tip, require + published images, compile fragments, derive, release). That is how `v6` + releases on every merge without being the default branch. A build that + was cancelled on a non-default line is picked up by its next completed + build or by a manual dispatch from that branch; the schedule does not + relay. +7. **Channels — `docker.yml` on both branches, landed together.** Each branch's copy names its own channels in the three `publish-image-tags.sh` calls (`<branch> <include-latest> <channels>`) and the matching `INCLUDE_LATEST` / `RELEASE_BRANCH` / `CHANNELS` env on the three - cross-org mirror steps. The new stable line takes `true candidate` - (candidate plus `:latest`); the outgoing line gives them up. Flipping one - branch without the other leaves two lines retagging `candidate` and - `:latest` on every merge. What the outgoing line keeps (`edge`, or no - channel as `v4` has today) is a maintainer decision to record on the cut - issue. -6. **Default branch.** `schedule` and `workflow_run` triggers only fire from - the repository's default branch, so the hourly tagged-release backstop, - the per-merge release, and the hourly `stable` promotion all follow it. - Switch the default branch to the new line when it should cut tags on - every merge; until then it releases only by manual `workflow_dispatch` - from that branch. The outgoing line keeps the same manual path. -7. **Docs.** Update [releases.md](releases.md#release-lines-and-the-v5-semver-policy) + cross-org mirror steps. The stable line takes `true candidate` (candidate + plus `:latest`); flipping one branch without the other leaves two lines + retagging `candidate` and `:latest` on every merge. `stable` is promoted + from the default branch only, and `candidate` is one repository-wide tag, + so `promote-stable.yml` must not be dispatched from a line that does not + own it. Cutting a line as a *release* line and moving the *channels* to it + are separate decisions: `v6` was cut on 2026-11-07 keeping `edge` + + `v6-latest`, while `v5` kept `candidate`, `:latest` and `stable`. +8. **The first release consumes the whole `changelog.d/` backlog.** A new + line's `## Unreleased` has never been emptied, so its first release + compiles every fragment it has accumulated. Every one must pass + `check-changelog-fragment.sh`: a single malformed fragment fails + `compile-changelog.sh` and therefore the decide job, and no tag is cut. +9. **Docs.** Update [releases.md](releases.md#release-lines-and-the-per-line-semver-policy) §Release lines, [release-channels.md](release-channels.md) (which branch publishes which channel), the branch table in `CONTRIBUTING.md`, and the line policy in `ROADMAP.md`. @@ -150,11 +149,12 @@ the new line's branch unless noted: `<workflow.yml> <ENV_NAME>`, are held to the same set as the pinned triggers. The value takes the same `[extra]` / `[-excluded]` grammar; `mk` and `dd` are declared extras on `LONG_LIVED` — standing experimental branches that are not - release lines, but that a hive can be assigned to, so they legitimately publish - a tag — and so is `v6`, the development line the `edge` channel is re-based on - ([#7721](https://github.com/hivecommons/hive/issues/7721)): published, but not - yet cut as a release line (step 1 above), so it is an extra here rather than a - `release_lines` entry. The value is read in any of the spellings a workflow env can take + release lines but that a hive can be assigned to, so they legitimately publish + a tag. `v6` was an extra here too while it was the development line the + `edge` channel is re-based on + ([#7721](https://github.com/hivecommons/hive/issues/7721)) — published, but + not yet a release line; since its cut it is a `release_lines` entry + instead. The value is read in any of the spellings a workflow env can take (`"v2 v4"`, unquoted, or `[v2, v4]`), with trailing comments ignored. - **That the env list is still there to check.** The variable must appear exactly once in the workflow. Zero occurrences means it was renamed or diff --git a/src/docs/release-rollback.md b/src/docs/release-rollback.md index 6d799c53d0..18a1cafff7 100644 --- a/src/docs/release-rollback.md +++ b/src/docs/release-rollback.md @@ -25,7 +25,7 @@ immutable vs. moving" in [releases.md](releases.md)): | Reference | Written by | Notes | |---|---|---| | `ghcr.io/hivecommons/<image>:<7-hex-sha>` | `docker.yml`, every successful build of a release line | Retained for a bounded window: the scheduled GHCR prune deletes package versions whose only tags are short-SHA tags after **90 days** (`RETENTION_DAYS` in `.github/workflows/prune-ghcr*.yml`). Versions still carrying any moving tag are never pruned. | -| `ghcr.io/hivecommons/<image>:v<X.Y.Z>` | `tagged-release.yml`, only when a release is cut | A retag of the short-SHA digest, byte-identical to it, not subject to the 90-day prune. `v4` line only today; see the [v5 semver policy](releases.md#release-lines-and-the-v5-semver-policy). | +| `ghcr.io/hivecommons/<image>:v<X.Y.Z>` | `tagged-release.yml`, only when a release is cut | A retag of the short-SHA digest, byte-identical to it, not subject to the 90-day prune. `v5.x.y` and `v6.x.y` (and `v4.x.y` under the freeze); see the [per-line semver policy](releases.md#release-lines-and-the-per-line-semver-policy). | | `ghcr.io/hivecommons/<image>@sha256:<digest>` | You, in the deployment manifest | The digest form is what this runbook actually writes. A tag is how you *find* the digest; the digest is what you *pin*. | The three images are **separate build jobs** tagged with the same short SHA, diff --git a/src/docs/releases.md b/src/docs/releases.md index 975d707f12..c305aee16c 100644 --- a/src/docs/releases.md +++ b/src/docs/releases.md @@ -1,53 +1,60 @@ # Tagged releases -Hive ships continuously — every merge to a release line (`v5` today) publishes moving image tags +Hive ships continuously — every merge to a release line (`v5` and `v6` today) publishes moving image tags (`<branch>-latest`, the three channels, an immutable short-SHA tag; see [release channels](release-channels.md)) with no human step. This page covers the second, **additive** layer on top of that: immutable, semver-tagged releases (`v1.2.3`) with a git tag and a GitHub Release, cut automatically — no human ever pushes a tag or clicks "Draft a release" in the normal path. -## Release lines and the v5 semver policy - -Hive has two active release lines, `v4` and `v5`, plus the `v6` development -line. Since 2026-09-21 (#7721) **`v5` is the stable line** and **`v4` is the -feature-frozen maintenance line**; each cuts its own semver tags: - -- **`v5` cuts `v5.x.y` tags.** `tagged-release.yml` serves the release line - it was started from — `github.ref_name`, which is the default branch (`v5`) - for its `workflow_run` and `schedule` triggers — in its concurrency group - (`tagged-release-v5`), release PR base, and `docker.yml` dispatch, and - refuses at its first `decide` step unless that branch is under - `release_lines` in `.github/release-lines.yml` (#9154). - `derive-release-version.sh` bases the next - number on the line's own latest `v5.*` tag only, and the **first** tag on a - line is always `vN.0.0` regardless of the inferred bump — the human chose - the major when they cut the line. A `v4.*` tag never seeds a `v5` number, - and vice versa. The workflow names the line explicitly (`RELEASE_LINE`, set - from `github.ref_name`) because its checkout is a detached SHA; without that - variable on a detached checkout the script **refuses** to run rather than - falling back to the global latest tag — the fall-through that minted a - stray `v4.73.3` from `v5` on 2026-09-21 (deleted; see #7721). +## Release lines and the per-line semver policy + +Hive has three release lines, `v4`, `v5` and `v6` — the `release_lines` list +in `.github/release-lines.yml` is the single source of truth, and is also the +run-time allow-list `tagged-release.yml` consults before serving a branch +(#9154). Since 2026-09-21 (#7721) **`v5` is the stable line** and **`v4` is +the feature-frozen maintenance line**; since 2026-11-07 **`v6` is a release +line too** (it was the #7563 development line before that). Each cuts its own +semver tags: + +- **Every line cuts `vN.x.y` tags from its own branch.** `tagged-release.yml` + serves the branch it was started from (`RELEASE_LINE: ${{ github.ref_name }}` + — the default branch for `workflow_run`/`schedule`, the chosen ref for + `workflow_dispatch`) and refuses unless that branch is under + `release_lines`. `derive-release-version.sh` bases the next number on the + line's own latest `vN.*` tag only, and the **first** tag on a line is + always `vN.0.0` regardless of the inferred bump — the human chose the major + when they cut the line, so `v6`'s first release is `v6.0.0`. A `v4.*` tag + never seeds a `v5` number, and vice versa. The line is passed explicitly + because the checkout is a detached SHA; without that variable on a detached + checkout the script **refuses** to run rather than falling back to the + global latest tag — the fall-through that minted a stray `v4.73.3` from + `v5` on 2026-09-21 (deleted; see #7721). +- **`v5` cuts `v5.x.y` tags** and, as the default branch, is the only line + that receives `workflow_run` and `schedule` events directly. +- **`v6` cuts `v6.x.y` tags.** GitHub delivers `workflow_run` only to the + default branch's copy of the workflow, so the `v5` copy carries a `relay` + job: when `docker.yml` completes a push build on another declared release + line, it dispatches `tagged-release.yml --ref <line>`, and that line's own + copy takes the backstop path (resolve the tip, require published images, + derive, release) under its own `tagged-release-<line>` concurrency group. + The hourly schedule backstop stays default-branch only; a `v6` build that + was cancelled is picked up by its next completed build or by a manual + `gh workflow run tagged-release.yml --ref v6`. - **`v4` cuts `v4.x.y` tags** for the security and critical fixes it still - accepts under the freeze (#6346). Its copy of `tagged-release.yml` stays + accepts under the freeze (#6346). Its copy of `tagged-release.yml` is pinned to `v4` and labels its release PR `v4-freeze-exempt` so the required `freeze-gate` check lets the automated release commit land. -- **`v6` publishes continuous images only** (`v6-latest`, short-SHA, `edge`); - no `v6.x` tag exists until that line is cut as a release line. It is not - under `release_lines` yet, so a `tagged-release.yml` or `promote-stable.yml` - dispatch from `v6` fails its release-line check instead of releasing or - promoting `v5`. The GA cut — `release_lines`, `docker.yml` channel rows on - `v5` and `v6` together, the default branch, and these docs — is the - checklist in [release-line-guard.md](release-line-guard.md#cutting-a-new-release-line); - after it, the same workflow files mint `v6.0.0` with no edit. -- Channels are independent of tags: `stable`/`candidate`/`latest` follow v5 - (`stable` by digest via `promote-stable.yml`), `edge` follows v6. See - [release-channels.md](release-channels.md) and the - [digest-verifiable rollback](release-rollback.md) runbook. - -The rest of this page describes the path as it runs on `v5`, the line it -serves today; the `v4` copy differs only in the branch name and the exempt -label. +- Channels are independent of tags and did **not** move with the `v6` cut: + `stable`/`candidate`/`latest` follow v5 (`stable` by digest via + `promote-stable.yml`, which only ever runs from the default branch), `edge` + and `v6-latest` follow v6, and a `v6.x.y` tag is an additional immutable + retag of the same digest. See [release-channels.md](release-channels.md) + and the [digest-verifiable rollback](release-rollback.md) runbook. + +The rest of this page describes the path as it runs on `v5`; the `v6` copy is +the same file reached through the relay, and the `v4` copy differs only in +the branch name and the exempt label. ## What triggers a release @@ -59,18 +66,36 @@ to create one. It never runs for `v2`, `mk`, `dd`, or a manual It also runs **hourly on a schedule**, as a backstop (#5318). The `workflow_run` trigger alone can silently lose a release opportunity: a -`docker.yml` run that is *cancelled* never fires `workflow_run` at all, and a -run that fires but finds `v5` already advanced stands down in favour of a -successor that may itself stand down. Standing down is correct — the run's -images were built from the older tree, so tagging would name content those -images do not contain — but nothing used to come back for the abandoned work. -The scheduled pass evaluates `v5`'s **current** tip, whose images have long -since been published, so it retags an existing digest exactly as the normal -path does. It refuses to act unless `docker.yml` has a *successful, completed* -push run for that tip, so a cancelled or in-flight build never produces a tag -with no digest behind it, and it is a no-op whenever `## Unreleased` is empty -— which on a healthy repository is almost always. Deferrals are logged as -warnings so a skipped opportunity is visible rather than silent. +`docker.yml` run that is *cancelled* never fires `workflow_run` at all, and +GitHub's concurrency queue holds at most one pending run per group, so on a +busy branch most commits never complete a build. The scheduled pass walks +`v5`'s recent history from the tip and considers the **newest commit that has +a successful, completed publishing `docker.yml` run** — not necessarily the +tip itself, which on a busy branch is rarely built yet. It retags that +commit's existing digests exactly as the normal path does, so a cancelled or +in-flight build never produces a tag with no digest behind it; if nothing +recent is built it stands down green and dispatches `docker.yml` for the tip. +It is a no-op whenever `## Unreleased` is empty — which on a healthy +repository is almost always. + +**The tag names the commit the images were built from, not `v5`'s tip.** The +release commit (compiled `CHANGELOG.md` plus the fragment deletions) is +parented on the exact SHA `docker.yml` built, the `v<version>` tag points at +that release commit, and the immutable image tags are retags of that SHA's +digests. The release commit reaches `v5` through a merge-commit PR that is +allowed to land on a tip that has moved on — the merge commit is not tagged, +so commits that arrived after the built SHA are "after `v<version>`" in git +exactly as they are in image terms. Until 2026-11 the workflow instead +*deferred* whenever `v5` had advanced past the built SHA, expecting the +successor run to release; with merges arriving faster than a multi-arch build +no run ever saw an unmoved tip, every successor deferred again, and `v5` went +from `v5.186.4` (2026-10-18) to ~1,700 untagged commits before the rule was +changed. The two remaining deferrals — logged as warnings so a skipped +opportunity is visible — are the cases where tagging the built SHA really +would be wrong: the built SHA is no longer an ancestor of `v5`'s tip, or a +release already landed *after* it (the newest `v5.*` tag is not an ancestor +of the built SHA, so its fragments are already released and the derived +version would collide). Before anything is decided, `src/scripts/compile-changelog.sh` folds any [`changelog.d/`](../../changelog.d/README.md) fragment files — the per-PR @@ -179,7 +204,7 @@ errors loudly) rather than a silent pick — remove all but one. | `stable` | `promote-stable.yml`, digest promotion of the newest `v5` build that crossed the 24-hour line after the [stable soak gate](stable-soak-policy.md), while the hub stable auto-promotion toggle is playing | Yes — moving pointer | | `<branch>-latest` (`v4-latest`, `v5-latest`, `v6-latest`) | `docker.yml`, every merge to that branch | Yes — moving pointers | | `<7-hex-sha>` | `docker.yml`, every successful build | No — immutable, but not a *release* | -| `v1.2.3` | `tagged-release.yml`, only when a release is cut | No — immutable, and **is** the release | +| `v5.x.y`, `v6.x.y` | `tagged-release.yml` on that line, only when a release is cut | No — immutable, and **is** the release | `tagged-release.yml` never writes `stable`/`candidate`/`edge`. Channel promotion is a separate, deliberate policy described in @@ -256,9 +281,14 @@ Concretely, per release: on that exact SHA. It then mirrors the verified result as a SHA-scoped `gate: success` commit status so a release PR can see it. 6. The workflow opens a PR from the scratch branch into `v5` and merges it - through the SHA-keyed merge API, leaving branch protection fully enforced. - It deletes the scratch branch, then creates and pushes the `v<version>` tag - on the commit that landed on `v5`. + through the SHA-keyed merge API as a merge commit, leaving branch + protection fully enforced (a direct fast-forward push is tried first when + `v5` is still at the built SHA). If `v5` has moved on meanwhile the merge + is simply retried — the base having moved is not a reason to defer. It + deletes the scratch branch, then creates and pushes the `v<version>` tag + on the **release commit itself** (the built SHA plus the changelog), never + on the merge commit, so the tag's tree is exactly what the retagged images + were built from. 7. A GitHub Release is created from the tag, with GitHub's auto-generated notes plus an SBOM callout, and the three SBOM files from step 4a attached as release assets. @@ -510,7 +540,7 @@ three SBOM files, using the same `gh release create` asset-upload call. released tip (the hourly #5318 backstop), **step 5 emptied `Unreleased`**, so `derive-release-version.sh` returns `release=false`. It never chases its own tail — belt and suspenders. -- `concurrency: { group: tagged-release-<line>, cancel-in-progress: false }` +- `concurrency: { group: tagged-release-v5, cancel-in-progress: false }` serializes overlapping runs so two merges landing close together queue rather than race two tags for two different commits. - A re-run after a partial failure (for example, the images got retagged but @@ -539,12 +569,15 @@ semver. `docker.yml`'s image-build jobs check out with `fetch-depth: 0` and with no ldflag at all (a bare local `go build`) still falls back to `0.0.0-dev`, never an empty string. -For semver releases, `tagged-release.yml` dispatches `docker.yml` with both the -exact merged release SHA and the exact tag (`VERSION=v5.x.y`). That keeps the -retag model — the release job still tags and publishes the digest built for the -merge commit — while making the binary self-report the release it is published -as instead of the previous nearest tag. Branch and manual non-release builds -leave `VERSION` empty and keep using `git describe`. +For semver releases, `tagged-release.yml` dispatches `docker.yml` with the +exact merged release SHA, and — only when `v5` was still at the built SHA, so +the merge adds nothing but the changelog — the exact tag (`VERSION=v5.x.y`). +That keeps the retag model while making the binary self-report the release it +is published as instead of the previous nearest tag. When the release landed +as a merge commit onto a tip that had moved on, the merge commit also carries +newer work, so `VERSION` is left empty and `git describe` reports +`v5.x.y-N-gSHA`, which is accurate. Branch and manual non-release builds leave +`VERSION` empty likewise. ## What still blocks cutting a real release diff --git a/src/docs/review-swarm.md b/src/docs/review-swarm.md index d55c0da862..7b256296b2 100644 --- a/src/docs/review-swarm.md +++ b/src/docs/review-swarm.md @@ -208,7 +208,8 @@ review: backlog: destination: github_issue # github_issue | github_project | linear | jira labels: [agent/reviewer] # default [agent/reviewer]; from-review, origin/review, and origin/reviewer are mapped to it - max_per_pr_per_day: 10 # default 10 + min_severity: P2 # default P2; P0 | P1 | P2 | P3 — findings below it go to the PR's Follow-ups comment, not the tracker + max_per_pr: 3 # default 3; items per PR over the PR's lifetime (max_per_pr_per_day is a retired alias) ``` ### Blocking line (`review.severity`, `review.backlog`) @@ -264,7 +265,8 @@ Semantics: | `linear_state` | team default | Linear workflow state for new items. | | `jira_status` | project initial status | Jira status for new tickets. | | `labels` | `[agent/reviewer]` | Applied to every item. The retired `from-review`, `origin/review`, and `origin/reviewer` are accepted and mapped to `agent/reviewer`. | -| `max_per_pr_per_day` | `10` | Cap per PR per day. | +| `min_severity` | `P2` | Lowest finding priority that still becomes a backlog item. Findings below it (P3 `low`/`info` by default — every docs-currency nit, for example) are appended to one upserted `hive:review-followups` comment on the PR instead, so nothing is lost and nothing is filed. `P3` restores filing every finding ([#17065](https://github.com/hivecommons/hive/issues/17065)). | +| `max_per_pr` | `3` | Items filed per PR over the PR's lifetime, not per day. `max_per_pr_per_day` is accepted as a retired alias for the size when `max_per_pr` is unset. | **Precedence with `classification.review_bots.min_priority`.** One blocking line governs both the hive reviewer and external review bots. The bot threshold resolves in this order, first non-empty wins: `hive.yaml` `classification.review_bots.min_priority` (including an explicit `all`), then `hive-project.yaml` `classification.review_bots.min_priority`, then `review.severity.block_at`. With none set, every bot finding is routed. `block_at` is never copied into `min_priority`; clearing the explicit override hands control back to `block_at`. Invalid values fail config load with an error naming the field (for example `review.severity.block_at`, `review.backlog.project_column_id`). @@ -277,7 +279,9 @@ When `block_at` is set and `backlog_below` is on, every cited in-scope finding ( - **Fingerprint dedup.** Each finding is fingerprinted as `sha256(rule | path | snippet)`: the title, the cleaned file path and the summary, lower-cased with whitespace collapsed. Line numbers are left out, so the same nit at a shifted line still matches. `/data/review-backlog-issues.json` keeps a per-repo map of fingerprint → item. When another PR raises a known fingerprint, the hive comments on the existing item with the new PR link and permalink instead of filing a second one. The same PR raising it again changes nothing. When the destination folds a new finding into an existing open item instead, the item receives the full finding — title, `file:line`, summary, severity, PR link and fingerprint — under an "Additional finding (folded in — same finding area and category)" heading with an unchecked task-list line, still tagged with the `hive:review-backlog-link` marker; the PR summary lists it as `#T (folded into an existing issue) — <finding title>` ([#13604](https://github.com/hivecommons/hive/issues/13604)). The `github_issue` sink folds into an open hive-filed issue that cites the same files only when that issue is in the same category (its `Review backlog (<perspective>)` title or `Perspective:` line matches the finding's perspective) and it either cites the same file within 10 lines of the finding or names a symbol the finding's title names. The same check applies to an open issue whose title differs from the finding's only after its `Review backlog (<perspective>):` prefix; only an exact title match is reused unconditionally. Sharing a file alone is not enough: the finding is filed as its own issue, which gets a `hive:review-backlog-same-file` comment reading "Same file as #N" ([#13906](https://github.com/hivecommons/hive/issues/13906)). - **One item per finding per PR.** Each item filed from a PR is also remembered under that PR with its evidence file, line and title (`pr_findings` in the ledger). A later report from any perspective or at any head that names the same finding — same file and the same line, a shared code symbol, or the same title once its wrapping is stripped — is tracked against the existing item, never filed again. A report whose title is only a carry-over wrapper ("Previous style finding still present (non-blocking)", "Prior correctness note still present: …", "Previous security finding (…) unchanged at new head") or that carries the `<!-- hive-refers-to: #N -->` marker is a *reference*, not a finding: it is matched against the PR's tracked items and otherwise dropped with a log line, so one finding on one PR can no longer become three issues from three perspectives (hivecommons/hive#15627, #15628, #15629). The hive notes a tracked finding's persistence at most once per head, with one `Still present at <head> (<perspectives>).` comment on the item (counted against the daily cap). Title matching ignores a leading `[reviewer]` role tag, so an existing issue dedupes whichever filing path titled it. - **Split on host close.** A folded finding lives only in its `hive:review-backlog-link` comment, so closing the host used to close it too. Every ten minutes, alongside the closed-issue stage sweep, the hive reads the hive-authored link comments on recently closed backlog hosts (the issues the ledger points findings at) and re-files each still-unchecked `- [ ]` finding as its own `github_issue` backlog item headed `hive:review-backlog-split` and "Split from #N (host closed)", comments the new link on the host under the same marker, and moves the finding's ledger item and fingerprint records to the new issue (or to the open twin the sink folded it into, which then carries the folded comment so its own close splits it again). A checked `- [x]` finding stays with the host. A host closed as not planned or duplicate keeps the findings that match it by the fold rule above and only splits out unrelated ones; the host itself is exempt from the issue filer's rejected-twin gate for that filing (a fold cites the host's own files, so the just-rejected host would otherwise always count as the rejection), while a rejection elsewhere still suppresses the finding and is logged and counted as `skipped`. `/data/review-backlog-issues.json` also keeps `split_keys`, link-marker key → the closed hosts it was split out of, so re-runs are idempotent. One pass files at most 20 findings across all repos; hosts the pass did not reach once that cap was hit are counted and logged as `deferred`. A host that received at least one split is bumped by its cross-link comment and re-surfaces in the next pass, but a deferred host keeps its old `updated_at` and is only revisited while it stays inside the pass window (the last ten-minute interval plus ten minutes of slack), so a backlog of more than 20 unchecked findings closing within one window may leave the trailing hosts unsplit; the `deferred` count in the sweep log is the signal to look for ([#13914](https://github.com/hivecommons/hive/issues/13914)). Hosts closed before the windowed sweep reached them are covered by a backfill pass that runs after each split sweep: it walks the ledger's host index, fetches each host directly and splits every closed one through the same idempotent path. A backfill pass that split, skipped or deferred anything logs `review backlog split backfill pass complete` with those counts. Once a pass visits every host without hitting the per-pass cap (including a host left part-split when the cap ran out) or a transient error, `/data/review-backlog-issues.json` records `split_backfilled` and later passes are no-ops; an incomplete pass logs `review backlog split backfill incomplete, retrying next pass` and the next pass retries. Clearing `split_backfilled` re-runs the walk ([#13947](https://github.com/hivecommons/hive/issues/13947)). -- **Cap.** At most `max_per_pr_per_day` items are filed or updated per PR per UTC day. Findings over the cap are retried on the next review. Out-of-scope findings also stay within `review.max_out_of_scope_backlog_issues` per PR. +- **Severity floor.** Findings below `review.backlog.min_severity` (default `P2`, so `low`/`info`) are never filed. They are listed as `- [ ]` task lines in one `<!-- hive:review-followups-comment v1 -->` comment on the PR, edited in place on every pass: ticked lines stay ticked, a re-reported nit is not listed twice, and new nits are appended. Operators who want every finding filed set `min_severity: P3` ([#17065](https://github.com/hivecommons/hive/issues/17065)). +- **Same-family collapse.** New findings from one pass that share a perspective and scope (for example three docs-currency nits from one PR) become one item titled `[reviewer] Review backlog (<perspective>): <repo>#<pr> — N follow-ups` whose body is a checklist, one `- [ ]` per finding with `file:line`, severity and summary. Each finding's fingerprint is recorded against that one item, so another PR raising any of them comments on it instead of filing again. A single new finding keeps the per-finding title. +- **Cap.** At most `max_per_pr` items (default 3) are filed per PR over the PR's lifetime; the count is persisted in `/data/review-backlog-issues.json` (`pr_item_count`) and never resets. A collapsed item counts once. Findings over the cap are retried on the next review and may land after a human closes an item. Out-of-scope findings also stay within `review.max_out_of_scope_backlog_issues` per PR. - **Audit.** Each filing pass that wrote anything records one `review_backlog_batch_routed` entry on the PR (`destination`, `filed`, `updated`, `capped`). Each new GitHub issue also gets its own `review_backlog_issue_filed` entry; an issue split out of a closed host carries `split_from=<host>` and `reused`, and the dashboard audit log records one `review-backlog-split` entry per split. The PR receives one summary comment that lists the items filed. - **Blocked on the PR.** Every item the backlog creates is parked on the reviewed PR with the `blocked` label and the `<!-- hive:blocked-on pr=owner/repo#N -->` marker, in every destination ([#13833](https://github.com/hivecommons/hive/issues/13833)). A below-line or out-of-scope finding is almost always about lines the PR changes, so working it on the base branch first is wrong or conflicts. When the cited file only exists in the PR the note says so ([#13093](https://github.com/hivecommons/hive/issues/13093)); otherwise it says the finding is about code the PR is changing, and tells whoever picks it up to check it still applies after the merge and to close it without a PR if it is already fixed. The ledger records the PR each item waits on, and `ReconcileReviewBacklogBlocks` (every governor cycle) resolves it: when the PR **merged** the hive itself checks whether the finding still applies on the PR's base branch — the evidence file gone, or none of the code symbols the finding's title names left in it, closes the item as completed with a one-line note (`review_backlog_issue_closed` audit entry; GitHub-issue destination only); otherwise, or when the check cannot tell, the block is lifted with a one-line note and the item becomes actionable; the PR **closed unmerged** also lifts the block, with a `<!-- hive:review-backlog-retriage -->` note ("source PR #N closed unmerged — re-triage against current base"), and leaves the item open for normal triage and dedupe. The hive never closes or cancels a backlog item because its PR closed: a closed PR is often superseded by one that lands the same lines, so the finding may still apply. Closing it as not planned stays a human (or `/fixed`) action. Destinations without a resolver (Jira, GitHub Projects) get the note only. A finding folded into an existing open twin keeps the twin's own state ([#13364](https://github.com/hivecommons/hive/issues/13364)). - **Heads mode.** With [review heads](#review-heads-several-models-per-perspective), only the decision step's decided reports file backlog items; raw head reports never do, so two heads' wordings of one finding cannot become two items. Instead of the once-per-PR summary comment, the relay appends a **Follow-ups filed** section to the decided review itself (edited in place, the App's own COMMENTED review only), listing every item that head's findings map to — filed, re-raised onto an existing item, or already tracked — so each head commit's review says where its nits went. diff --git a/src/docs/scale-envelope.md b/src/docs/scale-envelope.md index 04625e5cba..7aed26e3e0 100644 --- a/src/docs/scale-envelope.md +++ b/src/docs/scale-envelope.md @@ -34,7 +34,7 @@ ones to: 2. **Truncation must preserve the prioritization signal, not cut an arbitrary slice.** This holds today and is easy to assume backwards: - Issues are sorted by actionable rank tier, then **oldest first** within each tier before any cap is applied - (`RankActionableIssues`, `src/pkg/github/client.go:5401-5411`, descending `AgeMinutes` within each tier). + (`RankActionableIssues`, `src/pkg/github/client.go:5460-5470`, descending `AgeMinutes` within each tier). - PRs are sorted by **review class then oldest-first within class** (`SortPullRequestsForReview`, `src/pkg/github/review_priority.go:334`; fixes → refactors/docs → tests). diff --git a/src/docs/security-model.md b/src/docs/security-model.md index 1d9a87d97d..9e9673f3ca 100644 --- a/src/docs/security-model.md +++ b/src/docs/security-model.md @@ -196,17 +196,23 @@ process cannot forge. Only `api.github.com` is inspected; other hosts are tunnelled without inspection. See [net-admin-requirement.md](net-admin-requirement.md). -**Plain-HTTP forwards.** The redirect covers port 443 only, so plain HTTP -reaches the proxy through its explicit proxy port. Those forwards are -identified like any other request and dialled only when the resolved address -is globally routable: loopback services beside the proxy, the link-local -metadata endpoint, RFC 1918/CGNAT cluster addresses and multicast are refused -with `403` and counted as violations (loopback excepted — agents are handed -`NO_PROXY` for it, so it is logged as the client misconfiguration it is). The -check runs at dial time on the resolved address, so a hostname pointed inward -is refused on the same evidence as a literal IP. Set -`HIVE_PROXY_ALLOW_PRIVATE_FORWARD=true` only where a private-network plain-HTTP -destination is intended. +**Plain-HTTP forwards and uninspected tunnels.** The redirect covers port 443 +only, so plain HTTP reaches the proxy through its explicit proxy port. Those +forwards are identified like any other request and dialled only when the +resolved address is globally routable: loopback services beside the proxy, the +link-local metadata endpoint, RFC 1918/CGNAT cluster addresses and multicast +are refused with `403` and counted as violations (loopback excepted — agents +are handed `NO_PROXY` for it, so it is logged as the client misconfiguration it +is). The same policy applies to the tunnels the proxy does not inspect: a +CONNECT to a host other than the inspected API and the transparent-TLS +passthrough for such a host are dialled through the same guarded dialer, so +`CONNECT 169.254.169.254:80` or an SNI naming a cluster address is refused on +the same terms rather than tunnelled from the proxy's own uid. The check runs +at dial time on the resolved address, so a hostname pointed inward is refused +on the same evidence as a literal IP. Set +`HIVE_PROXY_ALLOW_PRIVATE_FORWARD=true` only where a private-network +destination is intended; it lifts the guard for all three legs at once, and the +proxy warns at boot when it is set. **Hub-to-spoke channel.** Heartbeats carry a per-hive bearer key derived from the hub master secret and are compared in constant time. The payload is diff --git a/src/docs/token-tracking.md b/src/docs/token-tracking.md index b1da909811..01a9dc3b62 100644 --- a/src/docs/token-tracking.md +++ b/src/docs/token-tracking.md @@ -7,9 +7,9 @@ Hive tracks token usage for local budgeting, dashboard cost estimates, and hub-l The collector starts from `data.metrics_dir` and rescans every 30 seconds. It merges: - Hive JSONL session files in `data.metrics_dir` (`*.jsonl`) using the flat `SessionEntry` schema. -- Claude Code session JSONL under `data.claude_sessions_dir` when configured. It reads assistant `message.usage` blocks from recent files (30-day mtime window). +- Claude Code session JSONL under `data.claude_sessions_dir` when configured, plus every per-agent `/data/home/agents/<name>/.claude/projects` beside it (each per-UID agent's `~/.claude` is a real directory since [#17031](https://github.com/hivecommons/hive/issues/17031)); sessions in a per-agent tree are attributed to that agent when the project directory name carries no work-dir hint. It reads assistant `message.usage` blocks from recent files (30-day mtime window). - Copilot CLI `events.jsonl` under `data.copilot_sessions_dir` when configured. It reads `session.shutdown.modelMetrics` and avoids double-counting sessions already captured live by the proxy. -- Bob CLI chat recordings under `data.bob_sessions_dir` (default `/data/home/.bob`) when configured. It reads `tmp/*/chats/*.json`, maps Bob project hashes back to trusted agent folders, and records explicit `tokens` fields (falling back to content-size estimates only when a recording has no token data). +- Bob CLI chat recordings under `data.bob_sessions_dir` (default `/data/home/.bob`) and every per-agent `/data/home/agents/<name>/.bob` beside it, when configured. It reads `tmp/*/chats/*.json`, maps Bob project hashes back to trusted agent folders (falling back to the owning agent of a per-agent tree), and records explicit `tokens` fields (falling back to content-size estimates only when a recording has no token data). - In the optional Claude Managed Agents hosted path, `pkg/tokens/managed_agents_ledger.go` writes `managed-agents-*.jsonl` after deduplicating vendor `span.model_request_end` IDs. Its `managed-agents-ledger.json` sidecar keeps diff --git a/src/docs/v5-ga.md b/src/docs/v5-ga.md index 7972a7c5ed..229e593ca3 100644 --- a/src/docs/v5-ga.md +++ b/src/docs/v5-ga.md @@ -19,7 +19,7 @@ cannot be counted as complete. | Required build/test gate | **Accepted 2026-09-09 ([#6171](https://github.com/hivecommons/hive/issues/6171) closed as decided):** the protected release-line gate for `v5` has been green for 7 consecutive days, with no ignored required checks. A red required check on the protected branch restarts the window; a concurrency-cancelled run does not count as red ([#6293](https://github.com/hivecommons/hive/issues/6293)). | GitHub branch protection/check history for `v5`. Branch protection currently requires the `gate` context from `docker.yml` / **Build and Push Docker Image**; re-check with `unset GITHUB_TOKEN && gh api repos/hivecommons/hive/branches/v5/protection --jq '.required_status_checks.contexts'`. Check run evidence can come from `gh api repos/hivecommons/hive/commits/v5/check-runs` or `gh run list --branch v5 --workflow docker.yml --limit N --json conclusion,createdAt,url,headSha`. | **Evidence-ready:** the 7-day window elapsed 2026-09-10T11:25Z on the `gate` context. Window start is 2026-09-03T11:25:39Z (`f80698e2`) — the first green run after the last red, 2026-09-03T10:02:31Z (`cbd39972`, [run 33742150760](https://github.com/hivecommons/hive/actions/runs/33742150760)), which restarted the window per the accepted rule. Re-measured 2026-09-14: **zero** `failure` runs since that restart across 190 sampled `docker.yml` runs on `v5` spanning 2026-08-18 to 2026-09-14T09:44Z, so the streak now stands at ~11 days; cancelled-by-concurrency runs ignored per [#6293](https://github.com/hivecommons/hive/issues/6293); evidence recorded in [#6808](https://github.com/hivecommons/hive/issues/6808). Row closes when a maintainer records the evidence bullet on [#6016](https://github.com/hivecommons/hive/issues/6016) — note this arms the v4 feature-freeze trigger once all Release-train rows are green. | | v5 channel publication | Every successful `v5` Docker build publishes immutable short-SHA image tags and moves only the `edge` channel; `stable`/`candidate` remain v4 until a promotion policy lands. | `docker.yml` run summary and GHCR manifests for `ghcr.io/hivecommons/hive`, `hive-contributor`, and `hive-hub`; compare `edge` digest to the `v5-latest`/short-SHA digest. | **Evidence-ready pending candidate designation:** on 2026-09-14 the `edge` digest equalled the `v5-latest` digest for all three images, and `candidate` remained pinned to `v4-latest` ([#6887](https://github.com/hivecommons/hive/issues/6887)). The remaining check — `edge` vs the GA candidate's short-SHA tag — cannot run until a maintainer designates the GA candidate SHA on [#6016](https://github.com/hivecommons/hive/issues/6016). | | Digest-verifiable rollback | Operators can resolve the GA candidate and rollback targets to immutable digests for all three images. | GHCR manifest inspection for the GA candidate's short-SHA tag and the documented rollback/channel-switch procedure. | **Procedure documented:** the digest-verifiable rollback/channel-switch runbook landed as [`release-rollback.md`](release-rollback.md) via [#6266](https://github.com/hivecommons/hive/pull/6266) (merged 2026-09-08), covering all three images and digest pinning/verification. Row closes when GHCR manifest inspection is run for the GA candidate's short-SHA tag and recorded on [#6016](https://github.com/hivecommons/hive/issues/6016). | -| Tagged release docs | The tagged-release path documents whether semver tags are cut from `v5`, still cut only from `v4`, or deliberately deferred for the v5 GA candidate. | `src/docs/releases.md` and the tagged-release workflow triggers. | **Policy documented:** [`releases.md`](releases.md#release-lines-and-the-v5-semver-policy) now states the v5 semver policy — semver tags are cut from `v4` only, `v5` publishes continuous images, and a `v5` semver line is deliberately deferred until this GA bar closes ([#6266](https://github.com/hivecommons/hive/pull/6266), merged 2026-09-08). Row closes when a maintainer records this on [#6016](https://github.com/hivecommons/hive/issues/6016). | +| Tagged release docs | The tagged-release path documents whether semver tags are cut from `v5`, still cut only from `v4`, or deliberately deferred for the v5 GA candidate. | `src/docs/releases.md` and the tagged-release workflow triggers. | **Policy documented:** [`releases.md`](releases.md#release-lines-and-the-per-line-semver-policy) now states the v5 semver policy — semver tags are cut from `v4` only, `v5` publishes continuous images, and a `v5` semver line is deliberately deferred until this GA bar closes ([#6266](https://github.com/hivecommons/hive/pull/6266), merged 2026-09-08). Row closes when a maintainer records this on [#6016](https://github.com/hivecommons/hive/issues/6016). | | Migration guide | A v4-to-v5 migration guide exists and names supported prerequisites, data/config compatibility, downgrade/rollback limits, and the channel choice operators should use during migration. | The merged migration guide (for example `UPGRADE.md` or a docs page linked from `src/docs/documentation-map.md`). | Guide exists: [`UPGRADE.md`](../../UPGRADE.md) landed via #5559 and is linked from `src/docs/documentation-map.md`; row closes when maintainers confirm it covers the GA candidate's prerequisites and rollback limits. | | Dual-version validation | **Bound — maintainer-recorded decision, see [#6112](https://github.com/hivecommons/hive/issues/6112):** at least one documented validation run covers v4 and v5 hub/spoke operation during transition, including heartbeat, branch/channel switching, and rollback expectations. No automated dual-version test exists today — `podman-contract.yml` runs only `v2`; `v2-ci.yml`/`v2-tests.yml` cover a single line at a time — so the row is evidenced by a dated manual run record until CI grows one. | Owner: maintainers (**@clubanderson**), with the ci-maintainer lane collecting the evidence comment on [#6016](https://github.com/hivecommons/hive/issues/6016). Evidence bullet format: `Evidence (YYYY-MM-DD, recorder): hub image tag: <ghcr short-SHA>; spoke image tag: <ghcr short-SHA>; scenario: <branch/channel switch + rollback steps performed>; hive status/heartbeat output: <pasted or linked>; conclusion: pass/fail.` Gap: no CI artifact backs this row; see the [Dual-version validation exercise](#dual-version-validation-exercise-bound) subsection below. | Bound; not yet run. Closes when the first evidence bullet is posted on #6016. | | Reviewer lane production exercise | **Bound — maintainer-recorded decision, see [#6130](https://github.com/hivecommons/hive/issues/6130):** one reviewer-lane (review swarm, [`src/docs/review-swarm.md`](review-swarm.md)) PR on `hivecommons/hive` is processed end-to-end in production — review posted by the lane and merged by a human — scheduled during the GA candidate week. | The PR URL, the lane's review-verdict comment URL, and the governor dispatch/`review-verdicts.json` artifact, linked from [#6016](https://github.com/hivecommons/hive/issues/6016); plus the #5617 tracker closure state (closed 2026-09-03). A maintainer triggers the exercise by kicking the reviewer-capable agent from the dashboard (`POST /api/kick/<agent>`) against the candidate PR. | Bound; not yet scheduled. Closes when the PR/comment/artifact links are posted on #6016. | diff --git a/src/docs/work-sources.md b/src/docs/work-sources.md index 76e7cbbcaa..28cc1bac05 100644 --- a/src/docs/work-sources.md +++ b/src/docs/work-sources.md @@ -606,7 +606,7 @@ Review findings below the blocking line (`review.severity.block_at`), and cited | `linear` | `linear` | An issue on the team mapped to the PR's repo (`teams[].repo`), in `linear_state` when set. Labels that already exist on the team are applied. | | `jira` | `jira` | A Task in the first `project_keys` project, moved to `jira_status` when set. Labels have their whitespace replaced with `-`. | -If the destination's work source is not active, or cannot be built (for example a missing `api_key`), the hive files a GitHub issue with the `agent/reviewer` label and logs why. Items are de-duplicated per repo by finding fingerprint. When another PR raises the same finding, the hive comments on the existing item instead of filing a new one. At most `max_per_pr_per_day` items are filed or updated per PR per day. See [review-swarm.md](review-swarm.md#backlog-routing) for the fingerprint, item body and audit entries. +If the destination's work source is not active, or cannot be built (for example a missing `api_key`), the hive files a GitHub issue with the `agent/reviewer` label and logs why. Items are de-duplicated per repo by finding fingerprint. When another PR raises the same finding, the hive comments on the existing item instead of filing a new one. Findings below `review.backlog.min_severity` (default `P2`) are held in one Follow-ups comment on the PR instead of filed; new findings sharing a perspective are filed as one checklist item; and at most `max_per_pr` items (default 3) are filed per PR over its lifetime. See [review-swarm.md](review-swarm.md#backlog-routing) for the fingerprint, item body and audit entries. ## Open questions diff --git a/src/internal/settingsparity/settingsparity.go b/src/internal/settingsparity/settingsparity.go index 32d2aa8af1..b148e2361b 100644 --- a/src/internal/settingsparity/settingsparity.go +++ b/src/internal/settingsparity/settingsparity.go @@ -149,6 +149,8 @@ func ConfigLeaves(repoRoot string) ([]Leaf, error) { Leaf{Path: "agents.session_recycle.max_rss_mb", Type: "int"}, Leaf{Path: "agents.session_recycle.max_age", Type: "time.Duration"}, Leaf{Path: "agents.session_recycle.min_idle", Type: "time.Duration"}, + Leaf{Path: "agents.cli_memory.auto_memory", Type: "*bool"}, + Leaf{Path: "agents.cli_memory.clear_on_kick", Type: "bool"}, ) byPath := map[string]Leaf{} for _, leaf := range leaves { diff --git a/src/internal/settingsparity/settingsparity_test.go b/src/internal/settingsparity/settingsparity_test.go index 8ad7b7d102..d496470b85 100644 --- a/src/internal/settingsparity/settingsparity_test.go +++ b/src/internal/settingsparity/settingsparity_test.go @@ -97,6 +97,8 @@ func TestConfigLeaves(t *testing.T) { } want := []Leaf{ {Path: "agents.<key>.model", Type: "string"}, + {Path: "agents.cli_memory.auto_memory", Type: "*bool"}, + {Path: "agents.cli_memory.clear_on_kick", Type: "bool"}, {Path: "agents.github_api_hourly_cap", Type: "int"}, {Path: "agents.session_recycle.enabled", Type: "*bool"}, {Path: "agents.session_recycle.max_age", Type: "time.Duration"}, diff --git a/src/internal/testutil/comment_marker_ratchet_test.go b/src/internal/testutil/comment_marker_ratchet_test.go new file mode 100644 index 0000000000..d7dad67082 --- /dev/null +++ b/src/internal/testutil/comment_marker_ratchet_test.go @@ -0,0 +1,253 @@ +package testutil + +import ( + "fmt" + "io/fs" + "os" + "path/filepath" + "regexp" + "sort" + "strings" + "testing" +) + +// commentMarkerBaseline is the number of functions under src/pkg/github +// (including automerge) that post an issue/PR comment through a raw create +// call without any idempotence marker in sight, at the commit that +// introduced this ratchet (hivecommons/hive#17067), measured with the same +// rules TestCommentMarkerRatchet uses. +// +// It is a ratchet, not a target: lower this constant when you convert an +// emitter — to a `<!-- hive:… -->` marker with EditIssueMarkerComment / +// findOwnEntryComment, or to a prstatus section — but it must never go UP. +// Every unmarked emitter is a comment the hive can post again on the next +// sweep; the 2026-11-07 spam audit traced 30–46 such comments a day to them. +// +// v6 carries one more than v5's 45: its own emitters (ApproveIssueRelease, +// inheritDeferredDecisions, noteSignoffAttributionDecision, +// postAdoptionEscalationNote) outnumber the v5-only ones it lacks. +const commentMarkerBaseline = 46 + +// commentEmitterCalls are the raw comment-create calls the ratchet looks +// for. Marker-aware helpers (EditIssueMarkerComment, UpsertPRStatusSection, +// PostNoteOrFold) are built on these and are what new code should call. +var commentEmitterCalls = []string{ + ".Issues.CreateComment(", + ".CreateIssueComment(", + ".CreateIssueCommentBudgeted(", +} + +// commentMarkerEvidence: a function containing any of these is treated as +// marker-aware — it carries a `<!-- hive…` marker literal, names a +// marker (`Marker`, `marker`), writes a prstatus section, or upserts. +var commentMarkerEvidence = []string{ + "<!-- hive", + "arker", + "prstatus.", + "Upsert", +} + +// commentMarkerAllowList names the transport primitives: the functions +// that ARE the raw create call every marked helper is built on, and so +// cannot carry a marker themselves. Keyed by `path:Recv.Func` relative +// to commentMarkerRoot. Add here only for a new primitive, never for a +// feature emitter. +var commentMarkerAllowList = map[string]bool{ + "client.go:Client.CreateIssueComment": true, + "issue_comment_budget.go:Client.CreateIssueCommentBudgeted": true, + "pr_status_comment.go:clientStatusForge.CreateComment": true, + "automerge/automerge_stage_labels.go:engineStatusForge.CreateComment": true, +} + +// commentMarkerRoot is the tree the ratchet walks, relative to this package +// (src/internal/testutil): the GitHub client and the auto-merge engine, +// which between them own every bot comment the hive posts. +var commentMarkerRoot = filepath.Join("..", "..", "pkg", "github") + +var ( + funcDeclRE = regexp.MustCompile(`^func\s+(?:\([^)]*\)\s*)?([A-Za-z0-9_]+)`) + funcRecvDeclRE = regexp.MustCompile(`^func\s+\(\s*\w*\s*\*?([A-Za-z0-9_]+)\s*\)\s*([A-Za-z0-9_]+)`) +) + +// commentEmitters scans one Go source file and returns the identities +// (`relpath:Recv.Func`) of functions that call a raw comment create, +// split into those with marker evidence and those without. Top-level +// `func ` lines delimit functions; `//` comment lines are not calls. +func commentEmitters(relPath string, src string) (marked, unmarked []string) { + lines := strings.Split(src, "\n") + var starts []int + for i, l := range lines { + if strings.HasPrefix(l, "func ") { + starts = append(starts, i) + } + } + for k, s := range starts { + e := len(lines) + if k+1 < len(starts) { + e = starts[k+1] + } + body := lines[s:e] + hit := false + for _, l := range body[1:] { + if strings.HasPrefix(strings.TrimSpace(l), "//") { + continue + } + for _, call := range commentEmitterCalls { + if strings.Contains(l, call) { + hit = true + break + } + } + if hit { + break + } + } + if !hit { + continue + } + name := "" + if m := funcRecvDeclRE.FindStringSubmatch(lines[s]); m != nil { + name = m[1] + "." + m[2] + } else if m := funcDeclRE.FindStringSubmatch(lines[s]); m != nil { + name = m[1] + } + ident := relPath + ":" + name + text := strings.Join(body, "\n") + evidence := false + for _, mk := range commentMarkerEvidence { + if strings.Contains(text, mk) { + evidence = true + break + } + } + if evidence { + marked = append(marked, ident) + } else { + unmarked = append(unmarked, ident) + } + } + return marked, unmarked +} + +// TestCommentMarkerRatchet fails when the number of unmarked raw comment +// emitters under pkg/github exceeds commentMarkerBaseline, and when an +// allow-listed primitive no longer exists (so the list cannot rot). Runs +// in well under a second: a file walk and substring scans. +func TestCommentMarkerRatchet(t *testing.T) { + var marked, unmarked []string + files := 0 + err := filepath.WalkDir(commentMarkerRoot, func(path string, d fs.DirEntry, err error) error { + if err != nil { + return err + } + if d.IsDir() || !strings.HasSuffix(d.Name(), ".go") || strings.HasSuffix(d.Name(), "_test.go") { + return nil + } + files++ + data, err := os.ReadFile(path) + if err != nil { + return err + } + rel, err := filepath.Rel(commentMarkerRoot, path) + if err != nil { + return err + } + m, u := commentEmitters(filepath.ToSlash(rel), string(data)) + marked = append(marked, m...) + unmarked = append(unmarked, u...) + return nil + }) + if err != nil { + t.Fatalf("walking %s: %v", commentMarkerRoot, err) + } + // Fail closed: no files means the wrong working directory. + if files == 0 { + t.Fatalf("no .go files found under %s — is the test running from src/internal/testutil?", commentMarkerRoot) + } + + seen := map[string]bool{} + var counted []string + for _, id := range unmarked { + seen[id] = true + if !commentMarkerAllowList[id] { + counted = append(counted, id) + } + } + for id := range commentMarkerAllowList { + if !seen[id] { + t.Errorf("allow-listed %q is no longer an unmarked emitter; remove it from commentMarkerAllowList", id) + } + } + sort.Strings(counted) + total := len(counted) + switch { + case total > commentMarkerBaseline: + t.Fatalf("%d functions under pkg/github post comments without a marker (%d marker-aware), above the baseline of %d.\n"+ + "Every bot comment must be idempotent across sweeps: carry a `<!-- hive:… -->` marker and edit in place "+ + "(EditIssueMarkerComment / findOwnEntryComment) or write a prstatus section (UpsertPRStatusSection). "+ + "If this is a deliberate one-shot, convert another emitter so the total does not grow.\n%s", + total, len(marked), commentMarkerBaseline, listEmitters(counted)) + case total < commentMarkerBaseline: + t.Logf("%d unmarked emitters, below the baseline of %d — lower commentMarkerBaseline in "+ + "internal/testutil/comment_marker_ratchet_test.go to %d so the ratchet keeps biting", + total, commentMarkerBaseline, total) + } +} + +func listEmitters(ids []string) string { + var b strings.Builder + b.WriteString("unmarked emitters:\n") + for _, id := range ids { + fmt.Fprintf(&b, " %s\n", id) + } + return b.String() +} + +// The scanner's rules on synthetic sources: a raw create with no marker +// counts, marker evidence in the same function clears it, a commented-out +// call is not a call, and a receiver method is named Recv.Func. +func TestCommentEmittersRules(t *testing.T) { + tests := []struct { + name string + src string + wantMarked []string + wantUnmarked []string + }{ + { + name: "raw create without marker", + src: "package x\n\nfunc (c *Client) note() {\n\tc.CreateIssueComment(ctx, repo, n, body)\n}\n", + wantUnmarked: []string{"f.go:Client.note"}, + }, + { + name: "marker literal in function", + src: "package x\n\nfunc (c *Client) note() {\n\tbody := \"<!-- hive:x -->\" + s\n\tc.CreateIssueCommentBudgeted(ctx, repo, n, body)\n}\n", + wantMarked: []string{"f.go:Client.note"}, + }, + { + name: "prstatus writer", + src: "package x\n\nfunc post() {\n\tprstatus.Write(ctx, f, k, key, text)\n\tf.c.client.Issues.CreateComment(ctx, o, r, n, cm)\n}\n", + wantMarked: []string{"f.go:post"}, + }, + { + name: "commented-out call is not an emitter", + src: "package x\n\nfunc (c *Client) note() {\n\t// c.CreateIssueComment(ctx, repo, n, body)\n}\n", + }, + { + name: "two functions, one marked", + src: "package x\n\nfunc a() {\n\tc.CreateIssueComment(ctx, repo, n, body)\n}\n\nfunc b() {\n\tif marker != \"\" {\n\t\tc.CreateIssueComment(ctx, repo, n, body)\n\t}\n}\n", + wantMarked: []string{"f.go:b"}, + wantUnmarked: []string{"f.go:a"}, + }, + } + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + marked, unmarked := commentEmitters("f.go", tc.src) + if strings.Join(marked, ",") != strings.Join(tc.wantMarked, ",") { + t.Errorf("marked = %v, want %v", marked, tc.wantMarked) + } + if strings.Join(unmarked, ",") != strings.Join(tc.wantUnmarked, ",") { + t.Errorf("unmarked = %v, want %v", unmarked, tc.wantUnmarked) + } + }) + } +} diff --git a/src/internal/tools/settingsparity/main_test.go b/src/internal/tools/settingsparity/main_test.go index febd8eced7..56a41ed805 100644 --- a/src/internal/tools/settingsparity/main_test.go +++ b/src/internal/tools/settingsparity/main_test.go @@ -67,6 +67,8 @@ func TestRunMarkdown(t *testing.T) { want := strings.Join([]string{ "| key | type | default | exposed-in-UI | where | notes |", "| --- | --- | --- | --- | --- | --- |", + "| `agents.cli_memory.auto_memory` | `*bool` | | none | | |", + "| `agents.cli_memory.clear_on_kick` | `bool` | | none | | |", "| `agents.github_api_hourly_cap` | `int` | | none | | may require restart or reconnect |", "| `agents.session_recycle.enabled` | `*bool` | | none | | |", "| `agents.session_recycle.max_age` | `time.Duration` | | none | | |", @@ -93,12 +95,12 @@ func TestRunJSON(t *testing.T) { if err := json.Unmarshal(stdout.Bytes(), &rows); err != nil { t.Fatalf("decode JSON output: %v\n%s", err, stdout.String()) } - if len(rows) != 9 { - t.Fatalf("got %d rows, want 9: %+v", len(rows), rows) + if len(rows) != 11 { + t.Fatalf("got %d rows, want 11: %+v", len(rows), rows) } want := row{Key: "hub.url", Type: "string", Default: "https://hub.example", UI: "read/write", Where: "Settings dialog reference", Notes: "may require restart or reconnect"} - if rows[6] != want { - t.Fatalf("rows[6] = %+v, want %+v", rows[6], want) + if rows[8] != want { + t.Fatalf("rows[8] = %+v, want %+v", rows[8], want) } } diff --git a/src/pkg/config/cli_memory_test.go b/src/pkg/config/cli_memory_test.go new file mode 100644 index 0000000000..6b6b777dac --- /dev/null +++ b/src/pkg/config/cli_memory_test.go @@ -0,0 +1,95 @@ +package config + +import ( + "strings" + "testing" + + "gopkg.in/yaml.v3" +) + +func TestCLIMemoryFleetBlockDecodesAndStampsAgents(t *testing.T) { + raw := ` +agents: + cli_memory: + clear_on_kick: true + scanner: + enabled: true + archivist: + enabled: true + cli_memory: + auto_memory: true + disabled: + enabled: false +` + var cfg Config + if err := yaml.NewDecoder(strings.NewReader(raw)).Decode(&cfg); err != nil { + t.Fatalf("Decode: %v", err) + } + if !cfg.AgentsCLIMemory.ClearOnKick || cfg.AgentsCLIMemory.AutoMemory != nil { + t.Fatalf("fleet block = %+v", cfg.AgentsCLIMemory) + } + if _, leaked := cfg.Agents["cli_memory"]; leaked { + t.Fatal("cli_memory leaked into the agents map as an agent") + } + enabled := cfg.EnabledAgents() + scanner := enabled["scanner"].CLIMemory + if scanner == nil || !scanner.ClearMemoryOnKick() || scanner.AutoMemoryEnabled() { + t.Fatalf("scanner did not inherit the fleet block: %+v", scanner) + } + archivist := enabled["archivist"].CLIMemory + if archivist == nil || !archivist.AutoMemoryEnabled() || archivist.ClearMemoryOnKick() { + t.Fatalf("archivist override lost: %+v", archivist) + } + scanner.ClearOnKick = false + if !cfg.AgentsCLIMemory.ClearOnKick { + t.Fatal("stamped pointer aliases the fleet value") + } +} + +func TestCLIMemoryDefaultsOffWhenAbsent(t *testing.T) { + var cfg Config + if err := yaml.NewDecoder(strings.NewReader("agents:\n scanner:\n enabled: true\n")).Decode(&cfg); err != nil { + t.Fatalf("Decode: %v", err) + } + got := cfg.EnabledAgents()["scanner"].CLIMemory + if got != nil { + t.Fatalf("absent fleet block stamped %+v", got) + } + if got.AutoMemoryEnabled() || got.ClearMemoryOnKick() { + t.Fatal("nil policy must read as auto-memory off, no wipe") + } +} + +func TestCLIMemoryRoundTripsThroughMarshal(t *testing.T) { + on := true + cfg := Config{AgentRuntimeConfig: AgentRuntimeConfig{ + Agents: map[string]AgentConfig{"scanner": {Enabled: true}}, + AgentsCLIMemory: CLIMemoryConfig{AutoMemory: &on, ClearOnKick: true}, + }} + cfg.Project.Org = "org" + out, err := yaml.Marshal(cfg) + if err != nil { + t.Fatalf("Marshal: %v", err) + } + if !strings.Contains(string(out), "cli_memory:") || !strings.Contains(string(out), "auto_memory: true") || !strings.Contains(string(out), "clear_on_kick: true") { + t.Fatalf("fleet block not encoded:\n%s", out) + } + var back Config + if err := yaml.Unmarshal(out, &back); err != nil { + t.Fatalf("Unmarshal: %v", err) + } + if !back.AgentsCLIMemory.AutoMemoryEnabled() || !back.AgentsCLIMemory.ClearOnKick { + t.Fatalf("round trip = %+v", back.AgentsCLIMemory) + } + if _, leaked := back.Agents["cli_memory"]; leaked { + t.Fatal("cli_memory decoded as an agent after round trip") + } + cfg.AgentsCLIMemory = CLIMemoryConfig{} + out, err = yaml.Marshal(cfg) + if err != nil { + t.Fatalf("Marshal: %v", err) + } + if strings.Contains(string(out), "cli_memory") { + t.Fatalf("zero fleet block encoded:\n%s", out) + } +} diff --git a/src/pkg/config/config.go b/src/pkg/config/config.go index 9cef0a07cd..b96232b21b 100644 --- a/src/pkg/config/config.go +++ b/src/pkg/config/config.go @@ -419,6 +419,10 @@ func (c *Config) EnabledAgents() map[string]AgentConfig { fleet := c.AgentsSessionRecycle agent.SessionRecycle = &fleet } + if agent.CLIMemory == nil && !c.AgentsCLIMemory.IsZero() { + fleet := c.AgentsCLIMemory + agent.CLIMemory = &fleet + } result[name] = agent } } diff --git a/src/pkg/config/crux_aliases.go b/src/pkg/config/crux_aliases.go index 9c37190d24..548f274a0f 100644 --- a/src/pkg/config/crux_aliases.go +++ b/src/pkg/config/crux_aliases.go @@ -7,6 +7,7 @@ type ( AgentConfig = cruxconfig.AgentConfig AgentRuntimeConfig = cruxconfig.AgentRuntimeConfig SessionRecycleConfig = cruxconfig.SessionRecycleConfig + CLIMemoryConfig = cruxconfig.CLIMemoryConfig AgentRuntimeGovernorConfig = cruxconfig.AgentRuntimeGovernorConfig AgentSandboxConfig = cruxconfig.AgentSandboxConfig AgentSandboxOverride = cruxconfig.AgentSandboxOverride diff --git a/src/pkg/config/defaults.go b/src/pkg/config/defaults.go index 7e0bd3a9ab..1e58815697 100644 --- a/src/pkg/config/defaults.go +++ b/src/pkg/config/defaults.go @@ -493,6 +493,9 @@ func (c *Config) applyDefaults() { if c.Knowledge.Primer.MaxBytes == 0 { c.Knowledge.Primer.MaxBytes = defaultKnowledgeMaxBytes } + if c.Knowledge.AdvisorMaxPerKick == 0 { + c.Knowledge.AdvisorMaxPerKick = DefaultKnowledgeAdvisorMaxPerKick + } if c.Knowledge.Primer.MergeStrategy == "" { c.Knowledge.Primer.MergeStrategy = DefaultKnowledgePrimerMergeStrategy } diff --git a/src/pkg/config/github_api_budget.go b/src/pkg/config/github_api_budget.go index a81e69ad79..48551cb149 100644 --- a/src/pkg/config/github_api_budget.go +++ b/src/pkg/config/github_api_budget.go @@ -13,6 +13,7 @@ func (c *Config) UnmarshalYAML(value *yaml.Node) error { type plain Config node := cloneYAMLNode(value) var recycle SessionRecycleConfig + var cliMemory CLIMemoryConfig if agents := mappingValueNode(&node, "agents"); agents != nil && agents.Kind == yaml.MappingNode { for i := 0; i < len(agents.Content)-1; { switch agents.Content[i].Value { @@ -29,6 +30,11 @@ func (c *Config) UnmarshalYAML(value *yaml.Node) error { return fmt.Errorf("agents.session_recycle: %w", err) } agents.Content = append(agents.Content[:i], agents.Content[i+2:]...) + case "cli_memory": + if err := agents.Content[i+1].Decode(&cliMemory); err != nil { + return fmt.Errorf("agents.cli_memory: %w", err) + } + agents.Content = append(agents.Content[:i], agents.Content[i+2:]...) default: i += 2 } @@ -43,6 +49,7 @@ func (c *Config) UnmarshalYAML(value *yaml.Node) error { c.AgentsGitHubAPIHourlyCap = cap c.AgentsGitHubAPIHourlyCapSet = capSet c.AgentsSessionRecycle = recycle + c.AgentsCLIMemory = cliMemory if governor := mappingValueNode(&node, "governor"); governor != nil { if stall := mappingValueNode(governor, "merge_train_stall_warn_s"); stall != nil && stall.Tag != "!!null" { c.Governor.mergeTrainStallWarnSet = true @@ -53,7 +60,7 @@ func (c *Config) UnmarshalYAML(value *yaml.Node) error { func marshalConfigYAMLWithAgentCap(c Config, out any) (any, error) { explicitStallZero := c.Governor.mergeTrainStallWarnSet && c.Governor.MergeTrainStallWarnS == 0 - if !c.AgentsGitHubAPIHourlyCapSet && c.AgentsSessionRecycle.IsZero() && !explicitStallZero { + if !c.AgentsGitHubAPIHourlyCapSet && c.AgentsSessionRecycle.IsZero() && c.AgentsCLIMemory.IsZero() && !explicitStallZero { return out, nil } var node yaml.Node @@ -93,6 +100,15 @@ func marshalConfigYAMLWithAgentCap(c Config, out any) (any, error) { &yaml.Node{Kind: yaml.ScalarNode, Value: "session_recycle"}, &recycleNode) } + if !c.AgentsCLIMemory.IsZero() && agents.Kind == yaml.MappingNode { + var memNode yaml.Node + if err := memNode.Encode(c.AgentsCLIMemory); err != nil { + return nil, err + } + agents.Content = append(agents.Content, + &yaml.Node{Kind: yaml.ScalarNode, Value: "cli_memory"}, + &memNode) + } return &node, nil } diff --git a/src/pkg/config/governor_config.go b/src/pkg/config/governor_config.go index 2143c775c6..907124bc4f 100644 --- a/src/pkg/config/governor_config.go +++ b/src/pkg/config/governor_config.go @@ -672,8 +672,8 @@ type ContributorNudgeConfig struct { // Enabled turns the nudge on. nil = true. Enabled *bool `yaml:"enabled"` // RenudgeInterval is how long after the first nudge the hive nudges once - // more (the documented cap is 2 nudges per head). Default: the stage's - // dwell (24h), i.e. the re-nudge coincides with stage/stalled. + // more (the documented cap is 2 nudges per PR and reason class). Unset + // defers to auto_merge.nudge_repeat_after (default 72h). RenudgeInterval string `yaml:"renudge_interval,omitempty"` } @@ -684,7 +684,7 @@ func (c ContributorNudgeConfig) IsEnabled() bool { return c.Enabled == nil || *c const DefaultPresenceWindow = 15 * time.Minute // EffectiveRenudgeInterval parses RenudgeInterval; unset/invalid returns 0 -// (the caller falls back to the stage dwell). +// (the caller falls back to auto_merge.nudge_repeat_after). func (c ContributorNudgeConfig) EffectiveRenudgeInterval() time.Duration { return parseDurationOr(c.RenudgeInterval, 0) } diff --git a/src/pkg/config/knowledge_advisor_test.go b/src/pkg/config/knowledge_advisor_test.go new file mode 100644 index 0000000000..a5e06bf2f9 --- /dev/null +++ b/src/pkg/config/knowledge_advisor_test.go @@ -0,0 +1,75 @@ +package config + +import ( + "testing" + + "gopkg.in/yaml.v3" +) + +// Mid-task knowledge advisor keys (hivecommons/hive#17052): off unless +// knowledge.advisor is set, with per-agent and per-family opt-out. + +func TestKnowledgeAdvisorEnabledFor(t *testing.T) { + base := func() *Config { + return &Config{ + AgentRuntimeConfig: AgentRuntimeConfig{Agents: map[string]AgentConfig{ + "developer": {Backend: "claude"}, + "developer-2": {Backend: "claude", ReplicaOf: "developer"}, + "scanner": {Backend: "claude"}, + }}, + Knowledge: KnowledgeConfig{Enabled: true, Advisor: true}, + } + } + tests := []struct { + name string + mut func(*Config) + agent string + want bool + }{ + {"on", func(*Config) {}, "developer", true}, + {"default off", func(c *Config) { c.Knowledge.Advisor = false }, "developer", false}, + {"knowledge off", func(c *Config) { c.Knowledge.Enabled = false }, "developer", false}, + {"excluded by name", func(c *Config) { c.Knowledge.AdvisorExcludeAgents = []string{" scanner "} }, "scanner", false}, + {"excluded by family", func(c *Config) { c.Knowledge.AdvisorExcludeAgents = []string{"developer"} }, "developer-2", false}, + {"other agent unaffected", func(c *Config) { c.Knowledge.AdvisorExcludeAgents = []string{"scanner"} }, "developer", true}, + {"empty agent", func(*Config) {}, "", false}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + c := base() + tt.mut(c) + if got := c.KnowledgeAdvisorEnabledFor(tt.agent); got != tt.want { + t.Errorf("KnowledgeAdvisorEnabledFor(%q) = %v, want %v", tt.agent, got, tt.want) + } + }) + } + var nilCfg *Config + if nilCfg.KnowledgeAdvisorEnabledFor("developer") { + t.Error("nil config enabled the advisor") + } +} + +func TestKnowledgeAdvisor_ParseAndDefault(t *testing.T) { + var k KnowledgeConfig + err := yaml.Unmarshal([]byte("advisor: true\nadvisor_max_per_kick: 5\nadvisor_exclude_agents: [scanner]\n"), &k) + if err != nil { + t.Fatal(err) + } + if !k.Advisor || k.AdvisorMaxPerKick != 5 || len(k.AdvisorExcludeAgents) != 1 { + t.Fatalf("parsed %+v", k) + } + + cfg := &Config{ + Project: ProjectConfig{Org: "o", Repos: []string{"r"}}, + GitHub: GitHubConfig{Token: "t"}, + AgentRuntimeConfig: AgentRuntimeConfig{Agents: map[string]AgentConfig{"a": {Backend: "claude"}}}, + Knowledge: KnowledgeConfig{Enabled: true}, + } + cfg.applyDefaults() + if cfg.Knowledge.Advisor { + t.Error("advisor must default off") + } + if cfg.Knowledge.AdvisorMaxPerKick != DefaultKnowledgeAdvisorMaxPerKick { + t.Errorf("advisor_max_per_kick = %d, want %d", cfg.Knowledge.AdvisorMaxPerKick, DefaultKnowledgeAdvisorMaxPerKick) + } +} diff --git a/src/pkg/config/knowledge_config.go b/src/pkg/config/knowledge_config.go index 63ab56386e..34597e07c5 100644 --- a/src/pkg/config/knowledge_config.go +++ b/src/pkg/config/knowledge_config.go @@ -44,6 +44,18 @@ type KnowledgeConfig struct { // kick primer and through agent-identified TOC/entry reads. A missing // entry or an empty field is unrestricted. AgentScopes map[string]KnowledgeAgentScope `yaml:"agent_scopes,omitempty"` + // Advisor turns on the mid-task knowledge advisor (hivecommons/hive#17052): + // when a running agent's pane first shows a source directory or `gh` + // command family its kick did not know about, matching entries are typed + // into the live session as one-line hints. Off by default while hive's + // own hive dogfoods it. + Advisor bool `yaml:"advisor,omitempty"` + // AdvisorMaxPerKick caps advisor deliveries per kick; zero takes + // DefaultKnowledgeAdvisorMaxPerKick. + AdvisorMaxPerKick int `yaml:"advisor_max_per_kick,omitempty"` + // AdvisorExcludeAgents lists agents (by name or family base name) the + // advisor never types at, e.g. lanes whose work is reading, not editing. + AdvisorExcludeAgents []string `yaml:"advisor_exclude_agents,omitempty"` } // PublicKnowledgeConfig is the dashboard-persisted owner override for the @@ -118,6 +130,7 @@ const ( DefaultKnowledgePrimerMaxFacts = 25 DefaultKnowledgePrimerMaxBytes = 4096 DefaultKnowledgePrimerMergeStrategy = "precedence" + DefaultKnowledgeAdvisorMaxPerKick = 3 ) // KnowledgeSchedules are the schedule values the bead synthesizer, curator @@ -353,6 +366,23 @@ func ValidateKnowledgeAgentScopes(scopes map[string]KnowledgeAgentScope) error { // KnowledgeAgentScope returns the knowledge scope bound to agent. A replica // without its own entry inherits its base agent's scope. ok is false when the // agent is unrestricted. +// KnowledgeAdvisorEnabledFor reports whether the mid-task knowledge advisor +// may type at agent: knowledge and the advisor are on, and neither the agent +// nor its family base name is in knowledge.advisor_exclude_agents. +func (c *Config) KnowledgeAdvisorEnabledFor(agent string) bool { + if c == nil || !c.Knowledge.Enabled || !c.Knowledge.Advisor || agent == "" { + return false + } + base := c.BaseAgentName(agent) + for _, name := range c.Knowledge.AdvisorExcludeAgents { + name = strings.TrimSpace(name) + if name != "" && (name == agent || name == base) { + return false + } + } + return true +} + func (c *Config) KnowledgeAgentScope(agent string) (KnowledgeAgentScope, bool) { if c == nil || len(c.Knowledge.AgentScopes) == 0 || agent == "" { return KnowledgeAgentScope{}, false diff --git a/src/pkg/config/review_config.go b/src/pkg/config/review_config.go index 4cea1d7979..6ed2a2bf05 100644 --- a/src/pkg/config/review_config.go +++ b/src/pkg/config/review_config.go @@ -479,6 +479,13 @@ type AutoMergeConfig struct { // GitHub Actions check-runs have not registered yet. Non-positive values // use DefaultAutoMergeMinHeadAge. MinHeadAge time.Duration `yaml:"min_head_age,omitempty" json:"min_head_age,omitempty"` + // NudgeRepeatAfter is how long a contributor PR must stay red for the + // same reason class before the hive rewrites its one + // `hive:contributor-nudge` comment a second (and last) time + // (hivecommons/hive#17067). Default DefaultNudgeRepeatAfter (72h); + // governor.labels.stage.contributor_nudge.renudge_interval, when set, + // takes precedence for backwards compatibility. + NudgeRepeatAfter string `yaml:"nudge_repeat_after,omitempty" json:"nudge_repeat_after,omitempty"` // RequiredChecks is the operator-declared list of status-check // contexts/check-run names that the self-merge sweep's commitGreen must // gate on, e.g. ["build-gate"]. This is the scope-free alternative to @@ -644,6 +651,15 @@ func (m MergeTrainAutoMergeConfig) EffectiveMaxRebaseAttempts() int { return m.MaxRebaseAttempts } +// DefaultNudgeRepeatAfter is auto_merge.nudge_repeat_after's default: a +// contributor PR red for the same reason class is re-nudged once after 72h. +const DefaultNudgeRepeatAfter = 72 * time.Hour + +// EffectiveNudgeRepeatAfter parses NudgeRepeatAfter (default 72h). +func (a AutoMergeConfig) EffectiveNudgeRepeatAfter() time.Duration { + return parseDurationOr(a.NudgeRepeatAfter, DefaultNudgeRepeatAfter) +} + // CreditIssueAuthorsEnabled reports the auto_merge.credit_issue_authors // switch; unset is on. func (a AutoMergeConfig) CreditIssueAuthorsEnabled() bool { diff --git a/src/pkg/config/review_severity.go b/src/pkg/config/review_severity.go index c2ae07ef06..2e92efdd68 100644 --- a/src/pkg/config/review_severity.go +++ b/src/pkg/config/review_severity.go @@ -75,10 +75,41 @@ const ( // ValidReviewBacklogDestinations lists the accepted destinations in UI order. var ValidReviewBacklogDestinations = []string{ReviewBacklogGitHubIssue, ReviewBacklogGitHubProject, ReviewBacklogLinear, ReviewBacklogJira} -// DefaultReviewBacklogMaxPerPRPerDay caps backlog items filed per PR per day -// when review.backlog.max_per_pr_per_day is unset. +// DefaultReviewBacklogMaxPerPRPerDay is the retired per-day cap default, +// kept so a config that still sets max_per_pr_per_day keeps loading; the +// live cap is EffectiveMaxPerPR. const DefaultReviewBacklogMaxPerPRPerDay = 10 +// DefaultReviewBacklogMaxPerPR caps backlog items filed or re-raised from one +// PR over its whole lifetime when review.backlog.max_per_pr is unset. +const DefaultReviewBacklogMaxPerPR = 3 + +// DefaultReviewBacklogMinSeverity is the lowest priority still filed as a +// backlog item when review.backlog.min_severity is unset: P0–P2 become +// items, P3 (low/info, e.g. docs-currency) is listed in the PR's Follow-ups +// comment instead. +const DefaultReviewBacklogMinSeverity = "P2" + +// ValidReviewBacklogMinSeverity lists the accepted review.backlog.min_severity +// values; P3 files every finding (the pre-hivecommons/hive#17065 behaviour). +var ValidReviewBacklogMinSeverity = []string{"P0", "P1", "P2", "P3"} + +// NormalizeReviewBacklogMinSeverity canonicalises min_severity ("" means the +// default, case and surrounding whitespace ignored). ok is false for +// anything else. +func NormalizeReviewBacklogMinSeverity(v string) (string, bool) { + v = strings.ToUpper(strings.TrimSpace(v)) + if v == "" { + return DefaultReviewBacklogMinSeverity, true + } + for _, p := range ValidReviewBacklogMinSeverity { + if v == p { + return v, true + } + } + return "", false +} + // ReviewBacklogConfig is `review.backlog` (hivecommons/hive#11088): where // below-the-line findings are filed. The review backlog filer in pkg/github // routes them there (hivecommons/hive#11089). @@ -101,9 +132,17 @@ type ReviewBacklogConfig struct { // the retired from-review, origin/review and origin/reviewer names are // accepted and mapped to agent/reviewer. Labels []string `yaml:"labels,omitempty" json:"labels,omitempty"` - // MaxPerPRPerDay caps backlog items filed per PR per day. 0 means - // DefaultReviewBacklogMaxPerPRPerDay. + // MaxPerPRPerDay is the retired per-day cap. Still read as MaxPerPR when + // that is unset, so an existing config keeps a cap of the same size. MaxPerPRPerDay int `yaml:"max_per_pr_per_day,omitempty" json:"max_per_pr_per_day,omitempty"` + // MaxPerPR caps backlog items filed or re-raised from one PR over its + // lifetime. 0 means MaxPerPRPerDay if set, else + // DefaultReviewBacklogMaxPerPR. + MaxPerPR int `yaml:"max_per_pr,omitempty" json:"max_per_pr,omitempty"` + // MinSeverity is the lowest priority (P0–P3) still filed as a backlog + // item; findings below it are listed in the PR's Follow-ups comment + // instead. Empty means DefaultReviewBacklogMinSeverity. + MinSeverity string `yaml:"min_severity,omitempty" json:"min_severity,omitempty"` } // NormalizeReviewBacklogDestination canonicalises a destination ("" means @@ -181,6 +220,29 @@ func (b ReviewBacklogConfig) EffectiveMaxPerPRPerDay() int { return b.MaxPerPRPerDay } +// EffectiveMaxPerPR returns the per-PR lifetime cap: max_per_pr, else the +// retired max_per_pr_per_day when set, else DefaultReviewBacklogMaxPerPR. +func (b ReviewBacklogConfig) EffectiveMaxPerPR() int { + if b.MaxPerPR > 0 { + return b.MaxPerPR + } + if b.MaxPerPRPerDay > 0 { + return b.MaxPerPRPerDay + } + return DefaultReviewBacklogMaxPerPR +} + +// EffectiveMinSeverity returns min_severity with the default applied; an +// invalid value also yields the default so a bad live edit never files +// every finding. +func (b ReviewBacklogConfig) EffectiveMinSeverity() string { + v, ok := NormalizeReviewBacklogMinSeverity(b.MinSeverity) + if !ok { + return DefaultReviewBacklogMinSeverity + } + return v +} + // Validate checks the backlog block, naming the offending field. A mismatch // between destination and the active work source is deliberately not an // error here: switching work source must never stop the hive from loading, @@ -201,5 +263,11 @@ func (b ReviewBacklogConfig) Validate() error { if b.MaxPerPRPerDay < 0 { return fmt.Errorf("review.backlog.max_per_pr_per_day: must not be negative, got %d", b.MaxPerPRPerDay) } + if b.MaxPerPR < 0 { + return fmt.Errorf("review.backlog.max_per_pr: must not be negative, got %d", b.MaxPerPR) + } + if _, ok := NormalizeReviewBacklogMinSeverity(b.MinSeverity); !ok { + return fmt.Errorf("review.backlog.min_severity: %q is not valid (must be %s, or empty)", b.MinSeverity, strings.Join(ValidReviewBacklogMinSeverity, ", ")) + } return nil } diff --git a/src/pkg/config/review_severity_test.go b/src/pkg/config/review_severity_test.go index d9fb0a34b6..d0718bc632 100644 --- a/src/pkg/config/review_severity_test.go +++ b/src/pkg/config/review_severity_test.go @@ -24,6 +24,12 @@ func TestReviewSeverityBacklogDefaults(t *testing.T) { if got := rc.Backlog.EffectiveMaxPerPRPerDay(); got != 10 { t.Fatalf("max_per_pr_per_day default = %d", got) } + if got := rc.Backlog.EffectiveMaxPerPR(); got != DefaultReviewBacklogMaxPerPR { + t.Fatalf("max_per_pr default = %d, want %d", got, DefaultReviewBacklogMaxPerPR) + } + if got := rc.Backlog.EffectiveMinSeverity(); got != "P2" { + t.Fatalf("min_severity default = %q, want P2", got) + } if err := rc.Severity.Validate(); err != nil { t.Fatalf("zero severity must validate: %v", err) } @@ -58,6 +64,11 @@ func TestReviewSeverityBacklogValidate(t *testing.T) { {name: "unknown destination", backlog: ReviewBacklogConfig{Destination: "trello"}, wantErr: "review.backlog.destination"}, {name: "blank label", backlog: ReviewBacklogConfig{Labels: []string{"from-review", " "}}, wantErr: "review.backlog.labels[1]"}, {name: "negative cap", backlog: ReviewBacklogConfig{MaxPerPRPerDay: -1}, wantErr: "review.backlog.max_per_pr_per_day"}, + {name: "negative lifetime cap", backlog: ReviewBacklogConfig{MaxPerPR: -1}, wantErr: "review.backlog.max_per_pr"}, + {name: "min severity lower-case", backlog: ReviewBacklogConfig{MinSeverity: " p3 "}}, + {name: "min severity P0", backlog: ReviewBacklogConfig{MinSeverity: "P0"}}, + {name: "min severity P4", backlog: ReviewBacklogConfig{MinSeverity: "P4"}, wantErr: "review.backlog.min_severity"}, + {name: "min severity word", backlog: ReviewBacklogConfig{MinSeverity: "low"}, wantErr: "review.backlog.min_severity"}, } for _, tc := range cases { t.Run(tc.name, func(t *testing.T) { @@ -78,6 +89,31 @@ func TestReviewSeverityBacklogValidate(t *testing.T) { } } +func TestReviewBacklogEffectiveMaxPerPRAndMinSeverity(t *testing.T) { + for _, tc := range []struct { + name string + backlog ReviewBacklogConfig + wantCap int + wantMin string + }{ + {name: "defaults", wantCap: DefaultReviewBacklogMaxPerPR, wantMin: DefaultReviewBacklogMinSeverity}, + {name: "max_per_pr", backlog: ReviewBacklogConfig{MaxPerPR: 5}, wantCap: 5, wantMin: "P2"}, + {name: "retired per-day alias keeps its size", backlog: ReviewBacklogConfig{MaxPerPRPerDay: 8}, wantCap: 8, wantMin: "P2"}, + {name: "max_per_pr over alias", backlog: ReviewBacklogConfig{MaxPerPR: 2, MaxPerPRPerDay: 8}, wantCap: 2, wantMin: "P2"}, + {name: "file everything", backlog: ReviewBacklogConfig{MinSeverity: "p3"}, wantCap: 3, wantMin: "P3"}, + {name: "invalid falls back to default", backlog: ReviewBacklogConfig{MinSeverity: "P9"}, wantCap: 3, wantMin: "P2"}, + } { + t.Run(tc.name, func(t *testing.T) { + if got := tc.backlog.EffectiveMaxPerPR(); got != tc.wantCap { + t.Fatalf("EffectiveMaxPerPR = %d, want %d", got, tc.wantCap) + } + if got := tc.backlog.EffectiveMinSeverity(); got != tc.wantMin { + t.Fatalf("EffectiveMinSeverity = %q, want %q", got, tc.wantMin) + } + }) + } +} + func TestReviewBacklogEffectiveDestinationFollowsWorkSource(t *testing.T) { cases := []struct { dest, ws, want string diff --git a/src/pkg/config/testdata/agent_runtime_golden.json b/src/pkg/config/testdata/agent_runtime_golden.json index 92e642aa0e..f333b819ee 100644 --- a/src/pkg/config/testdata/agent_runtime_golden.json +++ b/src/pkg/config/testdata/agent_runtime_golden.json @@ -558,7 +558,10 @@ "MaxBytes": 0, "Repos": null }, - "AgentScopes": null + "AgentScopes": null, + "Advisor": false, + "AdvisorMaxPerKick": 0, + "AdvisorExcludeAgents": null }, "Hub": { "Enabled": false, diff --git a/src/pkg/dashboard/api_config_review.go b/src/pkg/dashboard/api_config_review.go index d5dfc625c8..fb129ebb6e 100644 --- a/src/pkg/dashboard/api_config_review.go +++ b/src/pkg/dashboard/api_config_review.go @@ -181,6 +181,8 @@ func (s *Server) handleReviewConfigPut(w http.ResponseWriter, r *http.Request) { JiraStatus *string `json:"jira_status"` Labels *[]string `json:"labels"` MaxPerPRPerDay *int `json:"max_per_pr_per_day"` + MaxPerPR *int `json:"max_per_pr"` + MinSeverity *string `json:"min_severity"` } `json:"backlog"` // ReviewerAutoscale is review.reviewers.autoscale // (hivecommons/hive#14685). Pointer fields keep "absent means @@ -359,6 +361,17 @@ func (s *Server) handleReviewConfigPut(w http.ResponseWriter, r *http.Request) { if bl.MaxPerPRPerDay != nil { backlog.MaxPerPRPerDay = *bl.MaxPerPRPerDay } + if bl.MaxPerPR != nil { + backlog.MaxPerPR = *bl.MaxPerPR + } + if bl.MinSeverity != nil { + // Empty keeps "use the default" rather than pinning P2 into the file. + if v := strings.TrimSpace(*bl.MinSeverity); v == "" { + backlog.MinSeverity = "" + } else { + backlog.MinSeverity = strings.ToUpper(v) + } + } } if err := severity.Validate(); err != nil { jsonError(w, err.Error(), http.StatusBadRequest) diff --git a/src/pkg/dashboard/api_governor.go b/src/pkg/dashboard/api_governor.go index 9be4d0f551..712aa9383a 100644 --- a/src/pkg/dashboard/api_governor.go +++ b/src/pkg/dashboard/api_governor.go @@ -164,8 +164,11 @@ func (s *Server) handleGovernorConfigGet(w http.ResponseWriter, r *http.Request) "stageLabelsDwell": formatStageDwell(cfg.Governor.Labels.Stage.Dwell), // governor.labels.stage.contributor_nudge.* and presence_window // (hivecommons/hive#12436): the stage-072 contributor nudge. - "stageNudgeEnabled": cfg.Governor.Labels.Stage.ContributorNudge.IsEnabled(), - "stageNudgeRenudge": cfg.Governor.Labels.Stage.ContributorNudge.RenudgeInterval, + "stageNudgeEnabled": cfg.Governor.Labels.Stage.ContributorNudge.IsEnabled(), + "stageNudgeRenudge": cfg.Governor.Labels.Stage.ContributorNudge.RenudgeInterval, + // auto_merge.nudge_repeat_after (hivecommons/hive#17067): the + // same-reason re-nudge window the legacy renudge_interval defers to. + "nudgeRepeatAfter": cfg.AutoMerge.NudgeRepeatAfter, "stagePresenceWindow": cfg.Governor.Labels.Stage.PresenceWindow, // governor.labels.stage.adoption.enabled / contributor_grace_*: the // stage-074 adoption of red contributor PRs. @@ -809,6 +812,9 @@ func (s *Server) handleGovernorLabels(w http.ResponseWriter, r *http.Request) { StageNudgeEnabled *bool `json:"stage_nudge_enabled"` StageNudgeRenudge *string `json:"stage_nudge_renudge_interval"` StagePresenceWindow *string `json:"stage_presence_window"` + // NudgeRepeatAfter is auto_merge.nudge_repeat_after + // (hivecommons/hive#17067); a Go duration, empty restores 72h. + NudgeRepeatAfter *string `json:"nudge_repeat_after"` // Stage-074 adoption: governor.labels.stage.adoption.enabled and // governor.labels.stage.contributor_grace_online / _offline. StageAdoptionEnabled *bool `json:"stage_adoption_enabled"` @@ -917,6 +923,7 @@ func (s *Server) handleGovernorLabels(w http.ResponseWriter, r *http.Request) { } for name, v := range map[string]*string{ "stage_nudge_renudge_interval": body.StageNudgeRenudge, + "nudge_repeat_after": body.NudgeRepeatAfter, "stage_presence_window": body.StagePresenceWindow, "stage_grace_online": body.StageGraceOnline, "stage_grace_offline": body.StageGraceOffline, @@ -1027,6 +1034,9 @@ func (s *Server) handleGovernorLabels(w http.ResponseWriter, r *http.Request) { if body.StageNudgeRenudge != nil { s.deps.Config.Governor.Labels.Stage.ContributorNudge.RenudgeInterval = strings.TrimSpace(*body.StageNudgeRenudge) } + if body.NudgeRepeatAfter != nil { + s.deps.Config.AutoMerge.NudgeRepeatAfter = strings.TrimSpace(*body.NudgeRepeatAfter) + } if body.StagePresenceWindow != nil { s.deps.Config.Governor.Labels.Stage.PresenceWindow = strings.TrimSpace(*body.StagePresenceWindow) } diff --git a/src/pkg/dashboard/api_repo_hold.go b/src/pkg/dashboard/api_repo_hold.go index 93fec25654..6915ffa081 100644 --- a/src/pkg/dashboard/api_repo_hold.go +++ b/src/pkg/dashboard/api_repo_hold.go @@ -631,6 +631,25 @@ func (s *Server) handleRepoHoldPermission(w http.ResponseWriter, r *http.Request jsonResponse(w, map[string]any{"ok": true, "allowed": allowed}) } +// repoHoldDependencyStatus is the status a hold toggle answers when GitHub +// (or the missing GitHub client) is what failed. It is deliberately not 502 +// or 503: the Ingress in front of a hosted hive intercepts both +// (custom-http-errors "502,503", saas_provision.go) and replaces the body +// with the generic "hive unavailable" page, which is how a GitHub 422 on +// the hold label read as "the hive is down" (hivecommons/hive#17037). 424 +// passes through with the GitHub error the operator can act on. +const repoHoldDependencyStatus = http.StatusFailedDependency + +// repoHoldGitHubError answers a hold toggle whose GitHub step failed with +// the step and GitHub's reason, and logs the same so the spoke's log names +// the failure the dashboard shows. +func (s *Server) repoHoldGitHubError(w http.ResponseWriter, step, repoFull string, number int, label string, err error) { + if s.logger != nil { + s.logger.Warn("repo item hold: GitHub "+step+" failed", "repo", repoFull, "number", number, "label", label, "error", err) + } + jsonError(w, "GitHub "+step+" failed: "+err.Error(), repoHoldDependencyStatus) +} + func (s *Server) handleRepoItemHold(w http.ResponseWriter, r *http.Request) { owner, repoName, number, ok := s.parseRepoItemPath(w, r) if !ok { @@ -642,7 +661,7 @@ func (s *Server) handleRepoItemHold(w http.ResponseWriter, r *http.Request) { return } if s.deps == nil || s.deps.GHClient == nil { - jsonError(w, "GitHub client not configured", http.StatusServiceUnavailable) + jsonError(w, "GitHub client not configured", repoHoldDependencyStatus) return } var body repoHoldRequest @@ -659,24 +678,24 @@ func (s *Server) handleRepoItemHold(w http.ResponseWriter, r *http.Request) { var removed []string if body.Held { if err := s.deps.GHClient.EnsureIssueLabel(ctx, repoFull, canonical, "8250df", "Hive dashboard hold: agents will not act on this item until an operator removes this label."); err != nil { - jsonError(w, err.Error(), http.StatusBadGateway) + s.repoHoldGitHubError(w, "ensure hold label", repoFull, number, canonical, err) return } if err := s.deps.GHClient.AddLabels(ctx, repoFull, number, []string{canonical}); err != nil { - jsonError(w, err.Error(), http.StatusBadGateway) + s.repoHoldGitHubError(w, "add hold label", repoFull, number, canonical, err) return } s.auditFromRequest(r, "repo_item_hold_add", auditDetail("repo", repoFull, "number", strconv.Itoa(number), "label", canonical), "") } else { labels, err := s.currentItemLabels(ctx, owner, repoName, number) if err != nil { - jsonError(w, err.Error(), http.StatusBadGateway) + s.repoHoldGitHubError(w, "read labels", repoFull, number, canonical, err) return } removed = holdCausingLabels(labels, canonical) for _, label := range removed { if err := s.deps.GHClient.RemoveLabel(ctx, repoFull, number, label); err != nil { - jsonError(w, err.Error(), http.StatusBadGateway) + s.repoHoldGitHubError(w, "remove hold label", repoFull, number, label, err) return } } diff --git a/src/pkg/dashboard/api_repo_hold_test.go b/src/pkg/dashboard/api_repo_hold_test.go index def6990110..f76240c2df 100644 --- a/src/pkg/dashboard/api_repo_hold_test.go +++ b/src/pkg/dashboard/api_repo_hold_test.go @@ -19,6 +19,10 @@ type repoHoldMock struct { added []string created []string removed []string + // addLabelsStatus, when non-zero, is the status POST …/issues/7/labels + // answers (with addLabelsBody) instead of accepting the labels. + addLabelsStatus int + addLabelsBody string } func newRepoHoldMockServer(t *testing.T, m *repoHoldMock) *httptest.Server { @@ -39,6 +43,11 @@ func newRepoHoldMockServer(t *testing.T, m *repoHoldMock) *httptest.Server { case r.Method == http.MethodGet && strings.Contains(r.URL.Path, "/labels/"): http.NotFound(w, r) case r.Method == http.MethodPost && strings.HasSuffix(r.URL.Path, "/issues/7/labels"): + if m.addLabelsStatus != 0 { + w.WriteHeader(m.addLabelsStatus) + _, _ = io.WriteString(w, m.addLabelsBody) + return + } var labels []string _ = json.NewDecoder(r.Body).Decode(&labels) m.added = append(m.added, labels...) @@ -143,6 +152,56 @@ func TestRepoItemHoldToggleAuthorizationAndLabels(t *testing.T) { } } +// TestRepoItemHoldGitHubFailureIsNotAGatewayStatus: a hold on an issue whose +// GitHub label write fails answers 424 with GitHub's reason — never 502/503, +// which the hosted Ingress replaces with its generic "hive unavailable" page +// (hivecommons/hive#17037) — and the hive id's hold label fits GitHub's cap +// even for a long hosted id. +func TestRepoItemHoldGitHubFailureIsNotAGatewayStatus(t *testing.T) { + mock := &repoHoldMock{ + permission: map[string]string{"writer": "maintain"}, + addLabelsStatus: http.StatusUnprocessableEntity, + addLabelsBody: `{"message":"Validation Failed","errors":[{"resource":"Label","field":"name","code":"invalid"}]}`, + } + srv := newRepoHoldServer(t, mock) + srv.deps.Config.HiveID = "hosted-available-oke-11-placeholder-r05x" + + body := `{"held":true,"type":"issue"}` + req := httptest.NewRequest(http.MethodPost, "/api/repos/testorg/testrepo/items/7/hold", strings.NewReader(body)) + req.Header.Set("Content-Type", "application/json") + req.Header.Set("X-Hive-User", "writer") + w := httptest.NewRecorder() + srv.mux.ServeHTTP(w, req) + + if w.Code != http.StatusFailedDependency { + t.Fatalf("code = %d, want 424 (never 502/503: the Ingress swallows those) body=%s", w.Code, w.Body.String()) + } + var resp struct { + OK bool `json:"ok"` + Error string `json:"error"` + } + if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil { + t.Fatalf("body not JSON: %v %s", err, w.Body.String()) + } + if resp.OK || !strings.Contains(resp.Error, "add hold label") || !strings.Contains(resp.Error, "422") { + t.Fatalf("error = %q, want the step and GitHub's 422", resp.Error) + } + if len(mock.created) != 1 || len(mock.created[0]) > 50 || !strings.HasPrefix(mock.created[0], "hive-pause/hosted-available-oke-11-") { + t.Fatalf("created labels = %v, want one hive-pause label within GitHub's 50-char cap", mock.created) + } + + // The same failure when the label itself cannot be created: still 424. + srv.deps.GHClient = nil + w = httptest.NewRecorder() + req = httptest.NewRequest(http.MethodPost, "/api/repos/testorg/testrepo/items/7/hold", strings.NewReader(body)) + req.Header.Set("Content-Type", "application/json") + markOwnerRequest(req) + srv.mux.ServeHTTP(w, req) + if w.Code != http.StatusFailedDependency { + t.Fatalf("no GitHub client: code = %d, want 424 body=%s", w.Code, w.Body.String()) + } +} + func TestRepoItemHoldToggleUpdatesStatusSnapshotAndReturnsFloor(t *testing.T) { mock := &repoHoldMock{permission: map[string]string{"writer": "maintain"}} srv := newRepoHoldServer(t, mock) diff --git a/src/pkg/dashboard/bands.go b/src/pkg/dashboard/bands.go index 9cbe0a66ed..2a5d9aac36 100644 --- a/src/pkg/dashboard/bands.go +++ b/src/pkg/dashboard/bands.go @@ -721,11 +721,7 @@ func issueStale(createdAt, updatedAt time.Time, staleDays int, now time.Time) bo } func holdLabels(labels []string, hiveID string) []string { - canonical := "hold" - if trimmed := strings.TrimSpace(hiveID); trimmed != "" { - canonical = "hive-pause/" + trimmed - } - canonical = strings.ToLower(canonical) + canonical := strings.ToLower(github.CanonicalHiveHoldLabel(hiveID)) out := make([]string, 0) for _, label := range labels { lower := strings.ToLower(label) diff --git a/src/pkg/dashboard/nudge_repeat_after_settings_test.go b/src/pkg/dashboard/nudge_repeat_after_settings_test.go new file mode 100644 index 0000000000..6479cce7ac --- /dev/null +++ b/src/pkg/dashboard/nudge_repeat_after_settings_test.go @@ -0,0 +1,42 @@ +package dashboard + +import ( + "net/http" + "net/http/httptest" + "testing" +) + +// auto_merge.nudge_repeat_after (hivecommons/hive#17067) is edited from the +// Labels tab alongside the legacy renudge_interval it supersedes. +func TestHandleGovernorLabels_NudgeRepeatAfterRoundTrip(t *testing.T) { + srv := newFullServer(t) + w := httptest.NewRecorder() + srv.handleGovernorLabels(w, ownerPUT(t, "/api/config/governor/labels", `{"nudge_repeat_after":" 48h "}`)) + if w.Code != http.StatusOK { + t.Fatalf("code = %d, body = %s", w.Code, w.Body.String()) + } + if got := srv.deps.Config.AutoMerge.NudgeRepeatAfter; got != "48h" { + t.Fatalf("nudge_repeat_after = %q, want trimmed 48h", got) + } + if got := decodeGovernorConfigGet(t, srv)["nudgeRepeatAfter"]; got != "48h" { + t.Fatalf("GET nudgeRepeatAfter = %v, want 48h", got) + } + + w = httptest.NewRecorder() + srv.handleGovernorLabels(w, ownerPUT(t, "/api/config/governor/labels", `{"nudge_repeat_after":"soon"}`)) + if w.Code != http.StatusBadRequest { + t.Fatalf("invalid duration: code = %d, want 400; body = %s", w.Code, w.Body.String()) + } + if got := srv.deps.Config.AutoMerge.NudgeRepeatAfter; got != "48h" { + t.Fatalf("rejected save mutated nudge_repeat_after to %q", got) + } + + w = httptest.NewRecorder() + srv.handleGovernorLabels(w, ownerPUT(t, "/api/config/governor/labels", `{"nudge_repeat_after":""}`)) + if w.Code != http.StatusOK { + t.Fatalf("clear: code = %d, body = %s", w.Code, w.Body.String()) + } + if got := srv.deps.Config.AutoMerge.NudgeRepeatAfter; got != "" { + t.Fatalf("empty must clear the override, got %q", got) + } +} diff --git a/src/pkg/dashboard/review_severity_settings_11088_test.go b/src/pkg/dashboard/review_severity_settings_11088_test.go index f87a0ec0e5..259ebeda74 100644 --- a/src/pkg/dashboard/review_severity_settings_11088_test.go +++ b/src/pkg/dashboard/review_severity_settings_11088_test.go @@ -30,6 +30,8 @@ func TestReviewConfigPut_SeverityBacklog(t *testing.T) { {map[string]any{"backlog": map[string]any{"destination": "trello"}}, "review.backlog.destination"}, {map[string]any{"backlog": map[string]any{"destination": "linear"}}, "review.backlog.destination"}, {map[string]any{"backlog": map[string]any{"max_per_pr_per_day": -1}}, "review.backlog.max_per_pr_per_day"}, + {map[string]any{"backlog": map[string]any{"max_per_pr": -1}}, "review.backlog.max_per_pr"}, + {map[string]any{"backlog": map[string]any{"min_severity": "P9"}}, "review.backlog.min_severity"}, } for _, tc := range bad { rec := doPut(s, "/api/config/review", tc.body) @@ -56,13 +58,19 @@ func TestReviewConfigPut_SeverityBacklog(t *testing.T) { } s.deps.Config.Governor.WorkSource.Type = "linear" - if rec := doPut(s, "/api/config/review", map[string]any{"backlog": map[string]any{"destination": "linear", "linear_state": " Triage ", "labels": []string{"origin/reviewer", " ", "nit"}, "max_per_pr_per_day": 4}}); rec.Code != http.StatusOK { + if rec := doPut(s, "/api/config/review", map[string]any{"backlog": map[string]any{"destination": "linear", "linear_state": " Triage ", "labels": []string{"origin/reviewer", " ", "nit"}, "max_per_pr_per_day": 4, "max_per_pr": 5, "min_severity": " p1 "}}); rec.Code != http.StatusOK { t.Fatalf("PUT backlog: %d: %s", rec.Code, rec.Body.String()) } bl := s.deps.Config.Review.Backlog - if bl.Destination != "linear" || bl.LinearState != "Triage" || !reflect.DeepEqual(bl.Labels, []string{"origin/reviewer", "nit"}) || bl.MaxPerPRPerDay != 4 { + if bl.Destination != "linear" || bl.LinearState != "Triage" || !reflect.DeepEqual(bl.Labels, []string{"origin/reviewer", "nit"}) || bl.MaxPerPRPerDay != 4 || bl.MaxPerPR != 5 || bl.MinSeverity != "P1" { t.Fatalf("backlog not stored: %+v", bl) } + if rec := doPut(s, "/api/config/review", map[string]any{"backlog": map[string]any{"min_severity": ""}}); rec.Code != http.StatusOK { + t.Fatalf("PUT backlog clear min_severity: %d: %s", rec.Code, rec.Body.String()) + } + if s.deps.Config.Review.Backlog.MinSeverity != "" { + t.Fatalf("empty min_severity must clear the override, got %q", s.deps.Config.Review.Backlog.MinSeverity) + } if rec := doPut(s, "/api/config/review", map[string]any{"all_authors": true, "severity": map[string]any{}}); rec.Code != http.StatusOK { t.Fatalf("PUT without severity keys: %d", rec.Code) @@ -112,6 +120,8 @@ func TestReviewSeverityBacklogSettingsStaticWiring(t *testing.T) { "linear_state", "jira_status", "max_per_pr_per_day", + "max_per_pr", + "min_severity", } { if !strings.Contains(render, want) { t.Errorf("renderReviewSeverityBacklog missing %q", want) diff --git a/src/pkg/dashboard/settings_parity_allowlist.txt b/src/pkg/dashboard/settings_parity_allowlist.txt index ceed2b407c..9b4b81f83e 100644 --- a/src/pkg/dashboard/settings_parity_allowlist.txt +++ b/src/pkg/dashboard/settings_parity_allowlist.txt @@ -119,6 +119,8 @@ agents.<key>.sandbox.runtime # TODO #11854 agents.<key>.sandbox.timeout_s # TODO #11854 agents.<key>.sandbox.publish.verify[] # TODO #14999 (policy-file knob; Settings control pending) agents.<key>.sandbox.publish.verify_timeout_s # TODO #14999 (policy-file knob; Settings control pending) +agents.<key>.cli_memory.auto_memory # TODO #11854 +agents.<key>.cli_memory.clear_on_kick # TODO #11854 agents.<key>.session_recycle.enabled # TODO #11854 agents.<key>.session_recycle.max_age # TODO #11854 agents.<key>.session_recycle.max_rss_mb # TODO #11854 @@ -147,6 +149,8 @@ agents.<key>.variables.<key>.scope # TODO #11854 agents.<key>.variables.<key>.type # TODO #11854 agents.<key>.variables.<key>.url # TODO #11854 agents.<key>.variables.<key>.value # TODO #11854 +agents.cli_memory.auto_memory # TODO #11854 +agents.cli_memory.clear_on_kick # TODO #11854 agents.github_api_hourly_cap # TODO #11854 agents.session_recycle.enabled # TODO #11854 agents.session_recycle.max_age # TODO #11854 @@ -342,6 +346,9 @@ issues.rfc_existing_check.max_age # triage existing-coverage check; yaml-only (# issues.rfc_existing_check.max_matches # triage existing-coverage check; yaml-only (#13575) issues.rfc_existing_check.post_when_nothing_found # triage existing-coverage check; yaml-only (#13575) issues.sha_hold_trusted_label # TODO #11854 +knowledge.advisor # mid-task knowledge advisor, yaml-only while it soaks (#17052) +knowledge.advisor_exclude_agents[] # mid-task knowledge advisor, yaml-only while it soaks (#17052) +knowledge.advisor_max_per_kick # mid-task knowledge advisor, yaml-only while it soaks (#17052) knowledge.agent_scopes.<key>.include_states[] # TODO #11854 knowledge.agent_scopes.<key>.layers[] # TODO #11854 knowledge.agent_scopes.<key>.repos[] # TODO #11854 diff --git a/src/pkg/dashboard/stage_tracker_row_actions_test.go b/src/pkg/dashboard/stage_tracker_row_actions_test.go index b6264f0901..fd18c1840b 100644 --- a/src/pkg/dashboard/stage_tracker_row_actions_test.go +++ b/src/pkg/dashboard/stage_tracker_row_actions_test.go @@ -124,6 +124,8 @@ func stageTrackerRowActionsPreamble(t *testing.T, html string) string { jsFunc(t, html, "stageTrackerDelegatedDone"), jsFunc(t, html, "stageTrackerAwaitDelegated"), jsFunc(t, html, "stageTrackerPatchItem"), + jsConstLine(t, html, "STAGE_TRACKER_PLAN_GATEWAY_ERROR"), + jsFunc(t, html, "stageTrackerActionError"), jsFunc(t, html, "stageTrackerRunActions"), // runRowAction: result toasts + acting rows (owner request). jsConstLine(t, html, "STAGE_TRACKER_ACTION_NOOP"), @@ -575,6 +577,40 @@ let refreshed = 0; function stageTrackerAfterActions() { refreshed++; } `) } +// TestStageTrackerRowActionErrorNamesTheGateway: a failed row action reports +// the hive's own error when the hive answered (the 424 the hold toggle +// returns for a GitHub failure, hivecommons/hive#17037) and names the +// gateway — status included — when a 502–504 carries the hosted Ingress's +// placeholder body or no JSON at all, instead of the bare "hive unavailable" +// that read as an outage while the hive was up. +func TestStageTrackerRowActionErrorNamesTheGateway(t *testing.T) { + html := indexHTML(t) + runStageTrackerRowActionsScript(t, stageTrackerRowActionsPreamble(t, html)+` +assert.strictEqual(stageTrackerActionError(424, { ok: false, error: 'GitHub add hold label failed: 422 Validation Failed' }), 'GitHub add hold label failed: 422 Validation Failed', 'the hive answered: its reason verbatim'); +assert.strictEqual(stageTrackerActionError(403, { error: 'write permission required' }), 'write permission required'); +assert.strictEqual(stageTrackerActionError(500, {}), 'HTTP 500', 'no body: the status'); +const gw = stageTrackerActionError(502, { ok: false, error: 'hive unavailable' }); +assert.ok(gw.startsWith('HTTP 502 from the gateway'), gw); +assert.ok(!gw.includes('hive unavailable'), 'the placeholder is not repeated as if the hive said it'); +assert.ok(gw.includes('retry'), gw); +assert.ok(stageTrackerActionError(503, {}).startsWith('HTTP 503 from the gateway'), 'a 503 with no JSON body is the gateway too'); +assert.strictEqual(stageTrackerActionError(502, { error: 'spoke said so' }), 'spoke said so', 'a 502 with a real body passes through'); + +const i1 = { repo: 'o/r', kind: 'issue', number: 17004, url: 'u1' }; +const progress = []; +global.fetch = async () => ({ ok: false, status: 502, json: async () => ({ ok: false, error: 'hive unavailable' }) }); +global.showToast = () => null; global.dismissToast = () => {}; +function stageTrackerProgressToast(label, n) { return { update() {}, done(msg, type) { progress.push('done:' + type + ':' + msg); } }; } +function stageTrackerAfterActions() {} +(async () => { + const res = await stageTrackerRunActions([i1], 'hold', {}); + assert.strictEqual(res[0].ok, false); + assert.ok(res[0].error.startsWith('HTTP 502 from the gateway'), res[0].error); + assert.ok(progress[0].startsWith('done:error:Hold: 0/1 done. Failed: o/r#17004 — HTTP 502 from the gateway'), progress[0]); +})().catch(e => { console.error(e); process.exit(1); }); +`) +} + // TestStageTrackerLetHiveDecide: "Let hive decide" is the first Decide… // entry on rows and in the selection bar, posts to the delegated-decision // endpoint with the row's park words, polls the job until it ends, reports @@ -889,7 +925,6 @@ func stageTrackerConfirmOptOutJS(t *testing.T, html string) string { jsFunc(t, html, "stageTrackerPlanRequestKey"), jsFunc(t, html, "stageTrackerDelegatePlanErrorText"), jsFunc(t, html, "stageTrackerPostDelegatePlan"), - jsConstLine(t, html, "STAGE_TRACKER_PLAN_GATEWAY_ERROR"), jsFunc(t, html, "stageTrackerDelegatePlanFailure"), jsFunc(t, html, "stageTrackerPrefetchDelegatePlan"), jsFunc(t, html, "stageTrackerFetchDelegatePlan"), diff --git a/src/pkg/dashboard/static-src/js/config-governor.js b/src/pkg/dashboard/static-src/js/config-governor.js index 3e0d568e5a..656d01e405 100644 --- a/src/pkg/dashboard/static-src/js/config-governor.js +++ b/src/pkg/dashboard/static-src/js/config-governor.js @@ -704,6 +704,9 @@ const stageNudgeRenudge = (_configState.dirty.labels && _configState.dirty.labels.stage_nudge_renudge_interval !== undefined) ? _configState.dirty.labels.stage_nudge_renudge_interval : (_configState.data.stageNudgeRenudge || ''); + const nudgeRepeatAfter = (_configState.dirty.labels && _configState.dirty.labels.nudge_repeat_after !== undefined) + ? _configState.dirty.labels.nudge_repeat_after + : (_configState.data.nudgeRepeatAfter || ''); const stagePresenceWindow = (_configState.dirty.labels && _configState.dirty.labels.stage_presence_window !== undefined) ? _configState.dirty.labels.stage_presence_window : (_configState.data.stagePresenceWindow || ''); @@ -777,8 +780,13 @@ <div class="config-toggle"><div class="config-toggle-switch ${stageNudgeOn ? 'on' : ''}" data-action="toggleConfigSwitch" data-section="labels" data-key="stage_nudge_enabled"></div><span class="config-toggle-label">Contributor nudge on returned-to-contributor ${yamlHint('governor.labels.stage.contributor_nudge.enabled')} ${settingHelpMark('settings', 'labels', 'Contributor nudge', `When a contributor's PR enters stage/072-returned-to-contributor (red CI, changes requested, conflicts) the hive posts ONE @-mention comment per head with the failing checks / review asks and, for relay contributors, pushes a fix-pr task to their relay session (parallel sub-session when the relay advertises parallel_sessions, otherwise preempting the current task). Re-nudged once at the stall threshold; cap 2 per head. See docs/labels-and-control-signals.md.`)}</span></div> <div class="config-field"> <label for="cfg-stage-nudge-renudge">Re-nudge interval ${yamlHint('governor.labels.stage.contributor_nudge.renudge_interval')}</label> - <input type="text" id="cfg-stage-nudge-renudge" value="${esc(stageNudgeRenudge)}" placeholder="24h (stage dwell)" data-change-action="markDirty" data-arg0="labels" data-arg1="stage_nudge_renudge_interval" data-arg-types="s,s,w"> - <div class="config-help">Go duration before the single re-nudge; empty = the returned-to-contributor dwell.</div> + <input type="text" id="cfg-stage-nudge-renudge" value="${esc(stageNudgeRenudge)}" placeholder="unset (uses re-nudge after)" data-change-action="markDirty" data-arg0="labels" data-arg1="stage_nudge_renudge_interval" data-arg-types="s,s,w"> + <div class="config-help">Legacy override: Go duration before the single re-nudge; empty defers to the re-nudge-after setting below.</div> + </div> + <div class="config-field"> + <label for="cfg-nudge-repeat-after">Re-nudge after ${yamlHint('auto_merge.nudge_repeat_after')}</label> + <input type="text" id="cfg-nudge-repeat-after" value="${esc(nudgeRepeatAfter)}" placeholder="72h" data-change-action="markDirty" data-arg0="labels" data-arg1="nudge_repeat_after" data-arg-types="s,s,w"> + <div class="config-help">How long a contributor PR must stay red for the same reason before its one <code>hive:contributor-nudge</code> comment is rewritten a second (and last) time; empty = 72h.</div> </div> <div class="config-field"> <label for="cfg-stage-presence-window">Contributor presence window ${yamlHint('governor.labels.stage.presence_window')}</label> diff --git a/src/pkg/dashboard/static-src/js/config-helpers.js b/src/pkg/dashboard/static-src/js/config-helpers.js index 93d8163d49..d0a6d98b98 100644 --- a/src/pkg/dashboard/static-src/js/config-helpers.js +++ b/src/pkg/dashboard/static-src/js/config-helpers.js @@ -219,6 +219,7 @@ const dests = reviewBacklogDestinationsFor(ws); const dest = dests.some(o => o.value === bl.destination) ? bl.destination : 'github_issue'; const labels = Array.isArray(bl.labels) ? bl.labels : ['origin/reviewer']; + const minSeverity = ['P0', 'P1', 'P2', 'P3'].includes(String(bl.min_severity || '').toUpperCase()) ? String(bl.min_severity).toUpperCase() : ''; const presetBtns = REVIEW_SEVERITY_PRESETS.map(p => `<button type="button" class="hv-btn ${blockAt === p.blockAt ? 'btn-primary' : 'btn-secondary'} btn-sm btn-small" data-action="applyReviewSeverityPreset" data-arg0="${p.blockAt}" aria-pressed="${blockAt === p.blockAt ? 'true' : 'false'}"${dis}>${esc(p.label)}</button>`).join(' '); const toggle = (key, on, label, tip) => `<div class="config-toggle mt-3"> <div class="config-toggle-switch ${on ? 'on' : ''}${canEdit ? '' : ' disabled'}" data-action="toggleReviewSeverityFlag" data-arg0="${key}" data-arg-types="s" role="switch" aria-checked="${on ? 'true' : 'false'}"></div> @@ -258,8 +259,18 @@ <input type="text" id="review-backlog-labels" value="${esc(labels.join(', '))}" placeholder="origin/reviewer" data-change-action="markDirtyReviewBacklogLabels" data-arg-types="v"${dis}> </div> <div class="config-field mt-3"> - <label>Max backlog items per PR per day ${settingHelpMark('review-swarm', 'blocking-line-reviewseverity-reviewbacklog', 'Max backlog items per PR per day', `review.backlog.max_per_pr_per_day: cap on items filed from one PR in a day. 0 or blank uses the default of 10.`)}</label> - <input type="number" id="review-backlog-max" min="0" value="${esc(String(bl.max_per_pr_per_day || ''))}" placeholder="10" data-change-action="markDirtyReviewBacklog" data-arg0="max_per_pr_per_day" data-arg-types="s,N"${dis}> + <label>Lowest severity filed as a backlog item ${settingHelpMark('review-swarm', 'blocking-line-reviewseverity-reviewbacklog', 'Lowest severity filed as a backlog item', `review.backlog.min_severity: findings at or above this priority become backlog items; anything below is listed in the PR's Follow-ups comment instead. Default P2 (P3 files everything).`)}</label> + <select id="review-backlog-min-severity" data-change-action="markDirtyReviewBacklog" data-arg0="min_severity" data-arg-types="s,v"${dis}> + ${[['', 'Default (P0–P2)'], ['P0', 'P0 only'], ['P1', 'P0–P1'], ['P2', 'P0–P2'], ['P3', 'P0–P3 (everything)']].map(([v, l]) => `<option value="${v}"${minSeverity === v ? ' selected' : ''}>${l}</option>`).join('')} + </select> + </div> + <div class="config-field mt-3"> + <label>Max backlog items per PR ${settingHelpMark('review-swarm', 'blocking-line-reviewseverity-reviewbacklog', 'Max backlog items per PR', `review.backlog.max_per_pr: cap on items filed or re-raised from one PR over its lifetime. 0 or blank uses the default of 3 (or the retired review.backlog.max_per_pr_per_day if still set).`)}</label> + <input type="number" id="review-backlog-max" min="0" value="${esc(String(bl.max_per_pr || ''))}" placeholder="3" data-change-action="markDirtyReviewBacklog" data-arg0="max_per_pr" data-arg-types="s,N"${dis}> + </div> + <div class="config-field mt-3"> + <label>Max backlog items per PR per day (retired) ${settingHelpMark('review-swarm', 'blocking-line-reviewseverity-reviewbacklog', 'Max backlog items per PR per day (retired)', `review.backlog.max_per_pr_per_day: the retired per-day cap. Still read as the lifetime cap when max_per_pr is unset. 0 or blank means not set.`)}</label> + <input type="number" id="review-backlog-max-per-day" min="0" value="${esc(String(bl.max_per_pr_per_day || ''))}" placeholder="not set" data-change-action="markDirtyReviewBacklog" data-arg0="max_per_pr_per_day" data-arg-types="s,N"${dis}> </div> </div>`; } @@ -285,7 +296,8 @@ } function markDirtyReviewBacklog(key, value) { const rv = reviewSeverityState(); - if (key === 'max_per_pr_per_day') value = Number.isFinite(value) && value > 0 ? Math.floor(value) : 0; + if (key === 'max_per_pr_per_day' || key === 'max_per_pr') value = Number.isFinite(value) && value > 0 ? Math.floor(value) : 0; + if (key === 'min_severity') value = String(value || '').trim().toUpperCase(); rv.backlog[key] = value; markDirty('review', 'backlog', Object.assign({}, (_configState.dirty.review || {}).backlog, { [key]: value })); } diff --git a/src/pkg/dashboard/static-src/js/config-state.js b/src/pkg/dashboard/static-src/js/config-state.js index 485038b1ec..c369d36cd1 100644 --- a/src/pkg/dashboard/static-src/js/config-state.js +++ b/src/pkg/dashboard/static-src/js/config-state.js @@ -84,7 +84,7 @@ { tab: 'Labels', section: 'Labels', label: 'Central stage engine', key: 'governor.labels.stage.engine.mode', text: 'stage engine mode shadow enforce dry run pause anomaly reconciler ADR-0025 governor.labels.stage.engine.mode' }, { tab: 'Labels', section: 'Labels', label: 'Stage dwell overrides', key: 'governor.labels.stage.dwell', text: 'stage dwell stalled threshold governor.labels.stage.dwell' }, { tab: 'Labels', section: 'Labels', label: 'Adoption of a maintainer\'s PR', key: 'governor.labels.stage.adoption.maintainer_policy', text: 'adoption maintainer policy adopt ask never maintainer own pr clanker disconnected offline adopt action governor.labels.stage.adoption.maintainer_policy' }, - { tab: 'Labels', section: 'Labels', label: 'Contributor nudge', key: 'governor.labels.stage.contributor_nudge.enabled', text: 'contributor nudge returned-to-contributor red ci fix-pr relay interrupt renudge presence window governor.labels.stage.contributor_nudge.enabled governor.labels.stage.contributor_nudge.renudge_interval governor.labels.stage.presence_window' }, + { tab: 'Labels', section: 'Labels', label: 'Contributor nudge', key: 'governor.labels.stage.contributor_nudge.enabled', text: 'contributor nudge returned-to-contributor red ci fix-pr relay interrupt renudge presence window governor.labels.stage.contributor_nudge.enabled governor.labels.stage.contributor_nudge.renudge_interval auto_merge.nudge_repeat_after governor.labels.stage.presence_window' }, { tab: 'Labels', section: 'Labels', label: 'Adopt red contributor PRs', key: 'governor.labels.stage.adoption.enabled', text: 'adoption adopted-by-hive stage 074 red contributor pr grace online offline supersede takeover in place after offline unregistered heartbeat governor.labels.stage.adoption.enabled governor.labels.stage.contributor_grace_online governor.labels.stage.contributor_grace_offline governor.labels.stage.adoption.after_offline governor.labels.stage.adoption.after_unregistered governor.labels.stage.adoption.in_place governor.labels.stage.adoption.strict_attribution strict attribution governor.labels.stage.adoption.auto_merge auto merge adopted head hive authority governor.labels.stage.adoption.supersede.close_first close first superseded reopen copy failed governor.labels.stage.adoption.close_superseded close superseded on adopt on merge clanker authored opt-in label governor.labels.stage.adoption.offline_grace offline grace rebase failed twice fixer resolving conflicts governor.labels.stage.adoption.rebase_attempt_timeout rebase attempt timeout' }, { tab: 'Hub', section: 'Contributor Relay', label: 'Fix budget', key: 'contribute.max_parallel_fixes', text: 'fix budget parallel fixes focus window red pr fix-pr preempt spawn contribute.max_parallel_fixes contribute.min_focus_window' }, { tab: 'Logging', section: 'Logging', label: 'Governor logging', key: 'governor.logging.max_size_mb', text: 'governor logging directory level compression max size age backups governor.logging.compress governor.logging.dir governor.logging.level governor.logging.max_age_days governor.logging.max_backups governor.logging.max_size_mb' }, diff --git a/src/pkg/dashboard/static-src/js/tracker-actions.js b/src/pkg/dashboard/static-src/js/tracker-actions.js index 03fcddc6ad..ba4214224b 100644 --- a/src/pkg/dashboard/static-src/js/tracker-actions.js +++ b/src/pkg/dashboard/static-src/js/tracker-actions.js @@ -1430,6 +1430,22 @@ fetchStageTracker(); fetch('/api/status').then(r => r.json()).then(render).catch(() => {}); } + // The body the hosted gateway substitutes for a 502/503 it intercepted + // (deploy/k8s/error-pages.yaml): it never came from the hive. + const STAGE_TRACKER_PLAN_GATEWAY_ERROR = 'hive unavailable'; + // Pure: the message a failed row action reports. The hive's own error + // when it answered (the body of a 4xx — 403 "write permission + // required", 424 "GitHub add hold label failed: … 422 …"), the bare + // status when the body carried none. A 502–504 whose body is the + // gateway's placeholder (or no JSON at all) is named as such: the hive + // may well be up and its real reply was replaced on the way + // (hivecommons/hive#17037), so "hive unavailable" alone misled. + function stageTrackerActionError(status, data) { + data = data || {}; + const gateway = status >= 502 && status <= 504 && (!data.error || data.error === STAGE_TRACKER_PLAN_GATEWAY_ERROR); + if (gateway) return 'HTTP ' + status + ' from the gateway — the hive\'s reply was replaced (it may be restarting, or the gateway hid an upstream error); retry, and check the hive log if it persists'; + return data.error || ('HTTP ' + status); + } // Run one action over the items in order, one request each (a hive-wide // one once), reporting progress and the per-row outcome. async function stageTrackerRunActions(items, id, payload, rows) { @@ -1454,7 +1470,7 @@ try { const r = await fetch(req.url, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(req.body) }); let data = await r.json().catch(() => ({})); - if (!r.ok) throw new Error(data.error || ('HTTP ' + r.status)); + if (!r.ok) throw new Error(stageTrackerActionError(r.status, data)); if (id === 'accept-triage' && data.ok !== true) throw new Error(data.error || 'The server did not confirm the triage handoff'); if (id === 'decide:close-issue' && data.status !== 'closed' && data.status !== 'refused') throw new Error(data.error || 'The server did not confirm that the issue closed'); if (data.minStatusSeq != null) _statusSeqFloor = Math.max(_statusSeqFloor || 0, Number(data.minStatusSeq) || 0); @@ -1825,8 +1841,8 @@ // hint, retryable, hive, attempts, elapsed_ms; delegatedPlanFailure in // api_repo_item_decide_delegated_plan.go) when it answered, else what // the transport said. A 502/503 whose body is the hosted gateway's - // generic "hive unavailable" page never came from the hive at all. - const STAGE_TRACKER_PLAN_GATEWAY_ERROR = 'hive unavailable'; + // generic "hive unavailable" page (STAGE_TRACKER_PLAN_GATEWAY_ERROR) + // never came from the hive at all. function stageTrackerDelegatePlanFailure(item, status, data) { data = data || {}; const gateway = status >= 502 && status <= 504 && (!data.reason || data.error === STAGE_TRACKER_PLAN_GATEWAY_ERROR); diff --git a/src/pkg/dashboard/static/index.html b/src/pkg/dashboard/static/index.html index ca12d2907d..10e5f7ec3c 100644 --- a/src/pkg/dashboard/static/index.html +++ b/src/pkg/dashboard/static/index.html @@ -24307,6 +24307,22 @@ <h2 class="config-title" id="activity-monitor-labels-title">All labels</h2> fetchStageTracker(); fetch('/api/status').then(r => r.json()).then(render).catch(() => {}); } + // The body the hosted gateway substitutes for a 502/503 it intercepted + // (deploy/k8s/error-pages.yaml): it never came from the hive. + const STAGE_TRACKER_PLAN_GATEWAY_ERROR = 'hive unavailable'; + // Pure: the message a failed row action reports. The hive's own error + // when it answered (the body of a 4xx — 403 "write permission + // required", 424 "GitHub add hold label failed: … 422 …"), the bare + // status when the body carried none. A 502–504 whose body is the + // gateway's placeholder (or no JSON at all) is named as such: the hive + // may well be up and its real reply was replaced on the way + // (hivecommons/hive#17037), so "hive unavailable" alone misled. + function stageTrackerActionError(status, data) { + data = data || {}; + const gateway = status >= 502 && status <= 504 && (!data.error || data.error === STAGE_TRACKER_PLAN_GATEWAY_ERROR); + if (gateway) return 'HTTP ' + status + ' from the gateway — the hive\'s reply was replaced (it may be restarting, or the gateway hid an upstream error); retry, and check the hive log if it persists'; + return data.error || ('HTTP ' + status); + } // Run one action over the items in order, one request each (a hive-wide // one once), reporting progress and the per-row outcome. async function stageTrackerRunActions(items, id, payload, rows) { @@ -24331,7 +24347,7 @@ <h2 class="config-title" id="activity-monitor-labels-title">All labels</h2> try { const r = await fetch(req.url, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(req.body) }); let data = await r.json().catch(() => ({})); - if (!r.ok) throw new Error(data.error || ('HTTP ' + r.status)); + if (!r.ok) throw new Error(stageTrackerActionError(r.status, data)); if (id === 'accept-triage' && data.ok !== true) throw new Error(data.error || 'The server did not confirm the triage handoff'); if (id === 'decide:close-issue' && data.status !== 'closed' && data.status !== 'refused') throw new Error(data.error || 'The server did not confirm that the issue closed'); if (data.minStatusSeq != null) _statusSeqFloor = Math.max(_statusSeqFloor || 0, Number(data.minStatusSeq) || 0); @@ -24702,8 +24718,8 @@ <h2 class="config-title" id="activity-monitor-labels-title">All labels</h2> // hint, retryable, hive, attempts, elapsed_ms; delegatedPlanFailure in // api_repo_item_decide_delegated_plan.go) when it answered, else what // the transport said. A 502/503 whose body is the hosted gateway's - // generic "hive unavailable" page never came from the hive at all. - const STAGE_TRACKER_PLAN_GATEWAY_ERROR = 'hive unavailable'; + // generic "hive unavailable" page (STAGE_TRACKER_PLAN_GATEWAY_ERROR) + // never came from the hive at all. function stageTrackerDelegatePlanFailure(item, status, data) { data = data || {}; const gateway = status >= 502 && status <= 504 && (!data.reason || data.error === STAGE_TRACKER_PLAN_GATEWAY_ERROR); @@ -55514,7 +55530,7 @@ <h3 style="color:var(--amber);text-align:center">Configure LiteLLM</h3> { tab: 'Labels', section: 'Labels', label: 'Central stage engine', key: 'governor.labels.stage.engine.mode', text: 'stage engine mode shadow enforce dry run pause anomaly reconciler ADR-0025 governor.labels.stage.engine.mode' }, { tab: 'Labels', section: 'Labels', label: 'Stage dwell overrides', key: 'governor.labels.stage.dwell', text: 'stage dwell stalled threshold governor.labels.stage.dwell' }, { tab: 'Labels', section: 'Labels', label: 'Adoption of a maintainer\'s PR', key: 'governor.labels.stage.adoption.maintainer_policy', text: 'adoption maintainer policy adopt ask never maintainer own pr clanker disconnected offline adopt action governor.labels.stage.adoption.maintainer_policy' }, - { tab: 'Labels', section: 'Labels', label: 'Contributor nudge', key: 'governor.labels.stage.contributor_nudge.enabled', text: 'contributor nudge returned-to-contributor red ci fix-pr relay interrupt renudge presence window governor.labels.stage.contributor_nudge.enabled governor.labels.stage.contributor_nudge.renudge_interval governor.labels.stage.presence_window' }, + { tab: 'Labels', section: 'Labels', label: 'Contributor nudge', key: 'governor.labels.stage.contributor_nudge.enabled', text: 'contributor nudge returned-to-contributor red ci fix-pr relay interrupt renudge presence window governor.labels.stage.contributor_nudge.enabled governor.labels.stage.contributor_nudge.renudge_interval auto_merge.nudge_repeat_after governor.labels.stage.presence_window' }, { tab: 'Labels', section: 'Labels', label: 'Adopt red contributor PRs', key: 'governor.labels.stage.adoption.enabled', text: 'adoption adopted-by-hive stage 074 red contributor pr grace online offline supersede takeover in place after offline unregistered heartbeat governor.labels.stage.adoption.enabled governor.labels.stage.contributor_grace_online governor.labels.stage.contributor_grace_offline governor.labels.stage.adoption.after_offline governor.labels.stage.adoption.after_unregistered governor.labels.stage.adoption.in_place governor.labels.stage.adoption.strict_attribution strict attribution governor.labels.stage.adoption.auto_merge auto merge adopted head hive authority governor.labels.stage.adoption.supersede.close_first close first superseded reopen copy failed governor.labels.stage.adoption.close_superseded close superseded on adopt on merge clanker authored opt-in label governor.labels.stage.adoption.offline_grace offline grace rebase failed twice fixer resolving conflicts governor.labels.stage.adoption.rebase_attempt_timeout rebase attempt timeout' }, { tab: 'Hub', section: 'Contributor Relay', label: 'Fix budget', key: 'contribute.max_parallel_fixes', text: 'fix budget parallel fixes focus window red pr fix-pr preempt spawn contribute.max_parallel_fixes contribute.min_focus_window' }, { tab: 'Logging', section: 'Logging', label: 'Governor logging', key: 'governor.logging.max_size_mb', text: 'governor logging directory level compression max size age backups governor.logging.compress governor.logging.dir governor.logging.level governor.logging.max_age_days governor.logging.max_backups governor.logging.max_size_mb' }, @@ -62609,6 +62625,9 @@ <h3>Backend placement policy</h3> const stageNudgeRenudge = (_configState.dirty.labels && _configState.dirty.labels.stage_nudge_renudge_interval !== undefined) ? _configState.dirty.labels.stage_nudge_renudge_interval : (_configState.data.stageNudgeRenudge || ''); + const nudgeRepeatAfter = (_configState.dirty.labels && _configState.dirty.labels.nudge_repeat_after !== undefined) + ? _configState.dirty.labels.nudge_repeat_after + : (_configState.data.nudgeRepeatAfter || ''); const stagePresenceWindow = (_configState.dirty.labels && _configState.dirty.labels.stage_presence_window !== undefined) ? _configState.dirty.labels.stage_presence_window : (_configState.data.stagePresenceWindow || ''); @@ -62682,8 +62701,13 @@ <h4 class="mt-6 mb-3">Stage labels</h4> <div class="config-toggle"><div class="config-toggle-switch ${stageNudgeOn ? 'on' : ''}" data-action="toggleConfigSwitch" data-section="labels" data-key="stage_nudge_enabled"></div><span class="config-toggle-label">Contributor nudge on returned-to-contributor ${yamlHint('governor.labels.stage.contributor_nudge.enabled')} ${settingHelpMark('settings', 'labels', 'Contributor nudge', `When a contributor's PR enters stage/072-returned-to-contributor (red CI, changes requested, conflicts) the hive posts ONE @-mention comment per head with the failing checks / review asks and, for relay contributors, pushes a fix-pr task to their relay session (parallel sub-session when the relay advertises parallel_sessions, otherwise preempting the current task). Re-nudged once at the stall threshold; cap 2 per head. See docs/labels-and-control-signals.md.`)}</span></div> <div class="config-field"> <label for="cfg-stage-nudge-renudge">Re-nudge interval ${yamlHint('governor.labels.stage.contributor_nudge.renudge_interval')}</label> - <input type="text" id="cfg-stage-nudge-renudge" value="${esc(stageNudgeRenudge)}" placeholder="24h (stage dwell)" data-change-action="markDirty" data-arg0="labels" data-arg1="stage_nudge_renudge_interval" data-arg-types="s,s,w"> - <div class="config-help">Go duration before the single re-nudge; empty = the returned-to-contributor dwell.</div> + <input type="text" id="cfg-stage-nudge-renudge" value="${esc(stageNudgeRenudge)}" placeholder="unset (uses re-nudge after)" data-change-action="markDirty" data-arg0="labels" data-arg1="stage_nudge_renudge_interval" data-arg-types="s,s,w"> + <div class="config-help">Legacy override: Go duration before the single re-nudge; empty defers to the re-nudge-after setting below.</div> + </div> + <div class="config-field"> + <label for="cfg-nudge-repeat-after">Re-nudge after ${yamlHint('auto_merge.nudge_repeat_after')}</label> + <input type="text" id="cfg-nudge-repeat-after" value="${esc(nudgeRepeatAfter)}" placeholder="72h" data-change-action="markDirty" data-arg0="labels" data-arg1="nudge_repeat_after" data-arg-types="s,s,w"> + <div class="config-help">How long a contributor PR must stay red for the same reason before its one <code>hive:contributor-nudge</code> comment is rewritten a second (and last) time; empty = 72h.</div> </div> <div class="config-field"> <label for="cfg-stage-presence-window">Contributor presence window ${yamlHint('governor.labels.stage.presence_window')}</label> @@ -68907,6 +68931,7 @@ <h4>${model.editIndex === null ? 'Add Event trigger' : 'Edit Event trigger'}</h4 const dests = reviewBacklogDestinationsFor(ws); const dest = dests.some(o => o.value === bl.destination) ? bl.destination : 'github_issue'; const labels = Array.isArray(bl.labels) ? bl.labels : ['origin/reviewer']; + const minSeverity = ['P0', 'P1', 'P2', 'P3'].includes(String(bl.min_severity || '').toUpperCase()) ? String(bl.min_severity).toUpperCase() : ''; const presetBtns = REVIEW_SEVERITY_PRESETS.map(p => `<button type="button" class="hv-btn ${blockAt === p.blockAt ? 'btn-primary' : 'btn-secondary'} btn-sm btn-small" data-action="applyReviewSeverityPreset" data-arg0="${p.blockAt}" aria-pressed="${blockAt === p.blockAt ? 'true' : 'false'}"${dis}>${esc(p.label)}</button>`).join(' '); const toggle = (key, on, label, tip) => `<div class="config-toggle mt-3"> <div class="config-toggle-switch ${on ? 'on' : ''}${canEdit ? '' : ' disabled'}" data-action="toggleReviewSeverityFlag" data-arg0="${key}" data-arg-types="s" role="switch" aria-checked="${on ? 'true' : 'false'}"></div> @@ -68946,8 +68971,18 @@ <h4>${model.editIndex === null ? 'Add Event trigger' : 'Edit Event trigger'}</h4 <input type="text" id="review-backlog-labels" value="${esc(labels.join(', '))}" placeholder="origin/reviewer" data-change-action="markDirtyReviewBacklogLabels" data-arg-types="v"${dis}> </div> <div class="config-field mt-3"> - <label>Max backlog items per PR per day ${settingHelpMark('review-swarm', 'blocking-line-reviewseverity-reviewbacklog', 'Max backlog items per PR per day', `review.backlog.max_per_pr_per_day: cap on items filed from one PR in a day. 0 or blank uses the default of 10.`)}</label> - <input type="number" id="review-backlog-max" min="0" value="${esc(String(bl.max_per_pr_per_day || ''))}" placeholder="10" data-change-action="markDirtyReviewBacklog" data-arg0="max_per_pr_per_day" data-arg-types="s,N"${dis}> + <label>Lowest severity filed as a backlog item ${settingHelpMark('review-swarm', 'blocking-line-reviewseverity-reviewbacklog', 'Lowest severity filed as a backlog item', `review.backlog.min_severity: findings at or above this priority become backlog items; anything below is listed in the PR's Follow-ups comment instead. Default P2 (P3 files everything).`)}</label> + <select id="review-backlog-min-severity" data-change-action="markDirtyReviewBacklog" data-arg0="min_severity" data-arg-types="s,v"${dis}> + ${[['', 'Default (P0–P2)'], ['P0', 'P0 only'], ['P1', 'P0–P1'], ['P2', 'P0–P2'], ['P3', 'P0–P3 (everything)']].map(([v, l]) => `<option value="${v}"${minSeverity === v ? ' selected' : ''}>${l}</option>`).join('')} + </select> + </div> + <div class="config-field mt-3"> + <label>Max backlog items per PR ${settingHelpMark('review-swarm', 'blocking-line-reviewseverity-reviewbacklog', 'Max backlog items per PR', `review.backlog.max_per_pr: cap on items filed or re-raised from one PR over its lifetime. 0 or blank uses the default of 3 (or the retired review.backlog.max_per_pr_per_day if still set).`)}</label> + <input type="number" id="review-backlog-max" min="0" value="${esc(String(bl.max_per_pr || ''))}" placeholder="3" data-change-action="markDirtyReviewBacklog" data-arg0="max_per_pr" data-arg-types="s,N"${dis}> + </div> + <div class="config-field mt-3"> + <label>Max backlog items per PR per day (retired) ${settingHelpMark('review-swarm', 'blocking-line-reviewseverity-reviewbacklog', 'Max backlog items per PR per day (retired)', `review.backlog.max_per_pr_per_day: the retired per-day cap. Still read as the lifetime cap when max_per_pr is unset. 0 or blank means not set.`)}</label> + <input type="number" id="review-backlog-max-per-day" min="0" value="${esc(String(bl.max_per_pr_per_day || ''))}" placeholder="not set" data-change-action="markDirtyReviewBacklog" data-arg0="max_per_pr_per_day" data-arg-types="s,N"${dis}> </div> </div>`; } @@ -68973,7 +69008,8 @@ <h4>${model.editIndex === null ? 'Add Event trigger' : 'Edit Event trigger'}</h4 } function markDirtyReviewBacklog(key, value) { const rv = reviewSeverityState(); - if (key === 'max_per_pr_per_day') value = Number.isFinite(value) && value > 0 ? Math.floor(value) : 0; + if (key === 'max_per_pr_per_day' || key === 'max_per_pr') value = Number.isFinite(value) && value > 0 ? Math.floor(value) : 0; + if (key === 'min_severity') value = String(value || '').trim().toUpperCase(); rv.backlog[key] = value; markDirty('review', 'backlog', Object.assign({}, (_configState.dirty.review || {}).backlog, { [key]: value })); } diff --git a/src/pkg/fleetreport/runtime.go b/src/pkg/fleetreport/runtime.go index e215f863ad..379d766537 100644 --- a/src/pkg/fleetreport/runtime.go +++ b/src/pkg/fleetreport/runtime.go @@ -93,6 +93,7 @@ const ( ClassAgentGitHubCapReached = "agent_github_api_cap_reached" ClassTranscriptScanSlow = "transcript_scan_slow" ClassSharedCIRerunForbidden = "shared_ci_rerun_forbidden" + ClassIssueClaimEffectFailed = "issue_claim_effect_failed" // A restart or normal stop can invalidate a pending bootstrap without // indicating a restart storm; only repeated interruptions are reportable. ClassStartupKickInterrupted = "startup_kick_interrupted" @@ -210,6 +211,7 @@ var Classes = map[string]ClassSpec{ ClassLabelProvisioningFailed: {Component: "github-client", Severity: "low", MinCount: unclassifiedRepeatCount, Window: unclassifiedRepeatWindow, IdleClear: unclassifiedIdleClear, LogFed: true, Keywords: []string{"issue stage labels: provisioning failed"}}, ClassAgentCLIRestartLoop: {Component: "agent-runtime", Severity: "medium", MinCount: unclassifiedRepeatCount, Window: unclassifiedRepeatWindow, IdleClear: unclassifiedIdleClear, LogFed: true, Keywords: []string{"agent cli crashed or stuck on consent screen"}}, ClassSharedCIRerunForbidden: {Component: "github-client", Severity: "low", MinCount: unclassifiedRepeatCount, Window: unclassifiedRepeatWindow, IdleClear: unclassifiedIdleClear, LogFed: true, Keywords: []string{"shared-ci rerun forbidden"}}, + ClassIssueClaimEffectFailed: {Component: "agent-runtime", Severity: "low", MinCount: unclassifiedRepeatCount, Window: unclassifiedRepeatWindow, IdleClear: unclassifiedIdleClear, LogFed: true, Keywords: []string{"issue-claims: github side effect failed"}}, ClassTranscriptScanSlow: {Component: "agent-runtime", Severity: "low", MinCount: unclassifiedRepeatCount, Window: unclassifiedRepeatWindow, IdleClear: unclassifiedIdleClear, LogFed: true, Keywords: []string{"transcript activity scan outlived its interval"}}, } diff --git a/src/pkg/fleetreport/runtime_test.go b/src/pkg/fleetreport/runtime_test.go index fd2eed99e2..0a60e6607e 100644 --- a/src/pkg/fleetreport/runtime_test.go +++ b/src/pkg/fleetreport/runtime_test.go @@ -371,6 +371,7 @@ func TestEveryRuntimeClassTriggerAndNonTriggerThresholds(t *testing.T) { {class: ClassReviewEvidenceWriteFail, message: "review evidence: could not write bundle"}, {class: ClassFeedbackIssueRefreshFailed, message: "feedback: issue refresh failed"}, {class: ClassSharedCIRerunForbidden, message: "shared-ci rerun forbidden: the App installation lacks Actions write permission for rerun-failed-jobs"}, + {class: ClassIssueClaimEffectFailed, message: "issue-claims: GitHub side effect failed"}, {class: ClassTranscriptScanSlow, message: "copilot transcript activity scan outlived its interval; agent liveness reads may lag"}, {class: ClassBeadFactIngestFailed, message: "failed to ingest bead fact"}, {class: ClassSelfReportClearedFailed, message: "fleet report: cleared comment failed"}, @@ -1110,6 +1111,7 @@ func TestRecurringRuntimeMessagesAreClassified(t *testing.T) { "issue stage labels: provisioning failed": ClassLabelProvisioningFailed, "agent CLI crashed or stuck on consent screen, restarting before kick": ClassAgentCLIRestartLoop, "shared-ci rerun forbidden: the App installation lacks Actions write permission": ClassSharedCIRerunForbidden, + "issue-claims: GitHub side effect failed": ClassIssueClaimEffectFailed, "SHA poll: commit message fetch non-200": ClassSHAPollCommitMsgUnavail, "kick withheld: every ref failed the freshness check": ClassKickFreshnessWithheld, "no models found from any endpoint": ClassModelsEndpointEmpty, diff --git a/src/pkg/github/attribution.go b/src/pkg/github/attribution.go index 8ff56f0dcf..5dc8421f00 100644 --- a/src/pkg/github/attribution.go +++ b/src/pkg/github/attribution.go @@ -390,6 +390,34 @@ func HasAttributionTrailer(body string) bool { // footer may end with the origin marker (`<!-- hive:origin … -->`, #12539). var attributionIdentityFooter = regexp.MustCompile("\\n[ \\t]*---[ \\t]*\\n🐝 \\*\\*Hive Agent\\*\\*:(?: `[^`\\n]+`)?(?: \\| \\*\\*Instance:\\*\\* `[^`\\n]+`)? \\| \\*\\*SHA:\\*\\* `[^`\\n]+`[ \\t]*(?:\\n[ \\t]*<!-- " + OriginMarkerName + "[^>]*-->)?[ \\t\\n]*$") +// OriginFooterNote reports whether body is an agent's free-text note whose +// only machine marker is the identity footer's `<!-- hive:origin … -->` +// (hivecommons/hive#17067): the footer is present and carries the origin +// marker, and no other `<!-- hive…` marker (a verification, blocker or +// status marker) claims the comment for a dedicated path. note is the body +// with the footer removed and trimmed; a body that is nothing but the +// footer is not a note. +func OriginFooterNote(body string) (note string, ok bool) { + body = strings.ReplaceAll(body, "\r\n", "\n") + loc := attributionIdentityFooter.FindStringIndex(body) + if loc == nil { + return "", false + } + footer := body[loc[0]:loc[1]] + if !strings.Contains(footer, "<!-- "+OriginMarkerName) { + return "", false + } + rest := body[:loc[0]] + if strings.Count(body, "<!-- hive") != 1 { + return "", false + } + note = strings.TrimSpace(rest) + if note == "" { + return "", false + } + return note, true +} + // ParseAttributionTrailer extracts the launch metadata from the final visible // `— hive:` line in a PR body, optionally followed by Hive's identity footer. // Mentions of the template earlier in the body are deliberately ignored so diff --git a/src/pkg/github/automerge/automerge_contributor_held_runs_test.go b/src/pkg/github/automerge/automerge_contributor_held_runs_test.go index ac88b4fef9..a8726af404 100644 --- a/src/pkg/github/automerge/automerge_contributor_held_runs_test.go +++ b/src/pkg/github/automerge/automerge_contributor_held_runs_test.go @@ -11,6 +11,7 @@ import ( "fmt" "net/http" "net/url" + "reflect" "slices" "strings" "testing" @@ -265,7 +266,7 @@ func TestContributorLaneHeadRepoFallsBackToBase(t *testing.T) { // reports. func TestContributorLaneUnauthorizedWhenApproveForbidden(t *testing.T) { wantReason := unauthorizedReasonPrefix + unauthorizedStepApproveWorkflowRuns - wantMarker := unauthorizedMarker("sha7", unauthorizedStepApproveWorkflowRuns) + wantMarker := unauthorizedMarker(unauthorizedStepApproveWorkflowRuns) for _, tc := range []struct { name string // labelled pre-seeds hive:unauthorized and the marker comment on @@ -288,7 +289,7 @@ func TestContributorLaneUnauthorizedWhenApproveForbidden(t *testing.T) { fx.prComments = []map[string]any{{ "id": 5, "user": map[string]string{"login": testHiveAppBotLogin}, - "body": unauthorizedComment("sha7", unauthorizedStepApproveWorkflowRuns, unauthorizedPermissionActionsWrite, "do it"), + "body": unauthorizedComment("sha7", unauthorizedStepApproveWorkflowRuns, unauthorizedPermissionActionsWrite, "do it", unauthorizedAttempts{Count: 1, Heads: []string{"sha7"}}), }} } api := newContributorLaneAPI(t, &fx) @@ -432,13 +433,14 @@ func TestIsResourceNotAccessible(t *testing.T) { } func TestUnauthorizedCommentAndMarker(t *testing.T) { - marker := unauthorizedMarker("E3E9F5CABCDEF1234567", unauthorizedStepApproveWorkflowRuns) - if marker != "<!-- hive:unauthorized head=e3e9f5cabcdef1234567 step=approve-workflow-runs -->" { + marker := unauthorizedMarker(unauthorizedStepApproveWorkflowRuns) + if marker != "<!-- hive:unauthorized step=approve-workflow-runs -->" { t.Fatalf("marker = %q", marker) } action := approveWorkflowRunsHumanAction("acme", "widget", "CI / Mutation (advisory)", []int64{40459320512, 40459320537}) - body := unauthorizedComment("e3e9f5cabcdef1234567", unauthorizedStepApproveWorkflowRuns, unauthorizedPermissionActionsWrite, action) - for _, want := range []string{marker, "`actions: write`", "approve workflow runs", "e3e9f5cabcdef", "Approve and run", "40459320512, 40459320537", "CI / Mutation (advisory)", "Actions tab of acme/widget"} { + first := unauthorizedAttempts{Count: 1, Heads: []string{"e3e9f5cabcdef1234567"}} + body := unauthorizedComment("E3E9F5CABCDEF1234567", unauthorizedStepApproveWorkflowRuns, unauthorizedPermissionActionsWrite, action, first) + for _, want := range []string{marker, "`actions: write`", "approve workflow runs", "e3e9f5cabcdef", "Approve and run", "40459320512, 40459320537", "CI / Mutation (advisory)", "Actions tab of acme/widget", first.record()} { if !strings.Contains(body, want) { t.Fatalf("comment lacks %q:\n%s", want, body) } @@ -446,6 +448,16 @@ func TestUnauthorizedCommentAndMarker(t *testing.T) { if !strings.HasPrefix(body, marker+"\n") { t.Fatalf("comment must start with the marker line:\n%s", body) } + if strings.Contains(body, "Attempt ") { + t.Fatalf("first attempt must not count itself:\n%s", body) + } + if got := parseUnauthorizedAttempts(body); !reflect.DeepEqual(got, first) { + t.Fatalf("parse(first) = %+v, want %+v", got, first) + } + second := unauthorizedComment("ffff", unauthorizedStepApproveWorkflowRuns, unauthorizedPermissionActionsWrite, action, first.next("FFFF")) + if !strings.Contains(second, "<sub>Attempt 2: the same block hit heads `e3e9f5cabcde`, `ffff`.</sub>") || !strings.Contains(second, "for head `ffff`") { + t.Fatalf("second attempt:\n%s", second) + } if got := unauthorizedReason(unauthorizedStepApproveWorkflowRuns); got != "unauthorized:approve-workflow-runs" { t.Fatalf("reason = %q", got) } @@ -552,3 +564,173 @@ func TestContributorLaneApprovesHeldRunsWhenCIUnverifiedAndAllHeld(t *testing.T) }) } } + +func TestParseUnauthorizedAttempts(t *testing.T) { + step := unauthorizedStepRerunSharedCI + for _, tc := range []struct { + name string + body string + want unauthorizedAttempts + match bool + }{ + { + name: "current form with record", + body: unauthorizedMarker(step) + "\ntext\n" + unauthorizedAttempts{Count: 3, Heads: []string{"aaa", "bbb"}}.record() + "\n", + want: unauthorizedAttempts{Count: 3, Heads: []string{"aaa", "bbb"}}, + match: true, + }, + { + name: "legacy per-head marker counts as one attempt on that head", + body: unauthorizedLegacyMarker("D61D907", step) + "\nThe hive's GitHub App lacks `actions: write`…", + want: unauthorizedAttempts{Count: 1, Heads: []string{"d61d907"}}, + match: true, + }, + { + name: "current marker without record is one unknown attempt", + body: unauthorizedMarker(step) + "\ntext", + want: unauthorizedAttempts{Count: 1}, + match: true, + }, + { + name: "malformed count falls back to one", + body: unauthorizedMarker(step) + "\n" + unauthorizedAttemptsPrefix + "x heads=aaa" + unauthorizedAttemptsSuffix, + want: unauthorizedAttempts{Count: 1, Heads: []string{"aaa"}}, + match: true, + }, + { + name: "other step does not match", + body: unauthorizedMarker(unauthorizedStepApproveWorkflowRuns) + "\ntext", + want: unauthorizedAttempts{Count: 1}, + match: false, + }, + { + name: "legacy other step does not match", + body: unauthorizedLegacyMarker("aaa", unauthorizedStepApproveWorkflowRuns) + "\ntext", + want: unauthorizedAttempts{Count: 1, Heads: []string{"aaa"}}, + match: false, + }, + } { + t.Run(tc.name, func(t *testing.T) { + if got := isUnauthorizedCommentFor(step)(tc.body); got != tc.match { + t.Fatalf("match = %v, want %v", got, tc.match) + } + if got := parseUnauthorizedAttempts(tc.body); !reflect.DeepEqual(got, tc.want) { + t.Fatalf("parse = %+v, want %+v", got, tc.want) + } + }) + } +} + +func TestUnauthorizedAttemptsNextCapsHeads(t *testing.T) { + a := unauthorizedAttempts{Count: 1, Heads: []string{"h1"}} + for i := 2; i <= 8; i++ { + a = a.next(fmt.Sprintf("H%d", i)) + } + if a.Count != 8 || !reflect.DeepEqual(a.Heads, []string{"h4", "h5", "h6", "h7", "h8"}) { + t.Fatalf("after 8 attempts: %+v", a) + } + if !a.covers("H8") || a.covers("h1") { + t.Fatalf("covers: %+v", a) + } +} + +// TestCommentUnauthorizedUpsertsPerStep pins hivecommons/hive#17066: the +// hive:unauthorized note is one comment per PR and step. The same head is +// a no-op, a new head edits the note with the attempt count, a legacy +// per-head note is adopted rather than joined, and a different step gets +// its own note. +func TestCommentUnauthorizedUpsertsPerStep(t *testing.T) { + step := unauthorizedStepRerunSharedCI + for _, tc := range []struct { + name string + existing []map[string]any + heads []string + wantPosts int + wantEdits int + wantAttempt int + wantLast string + }{ + { + name: "same head twice posts once", + heads: []string{"aaa", "aaa"}, + wantPosts: 1, + wantEdits: 0, + wantAttempt: 1, + }, + { + name: "three heads post once and edit twice", + heads: []string{"aaa", "bbb", "ccc"}, + wantPosts: 1, + wantEdits: 2, + wantAttempt: 3, + wantLast: "<sub>Attempt 3: the same block hit heads `aaa`, `bbb`, `ccc`.</sub>", + }, + { + name: "legacy per-head note is adopted in place", + existing: []map[string]any{{ + "id": 5, + "user": map[string]string{"login": testHiveAppBotLogin}, + "body": unauthorizedLegacyMarker("aaa", step) + "\nold text", + }}, + heads: []string{"aaa", "bbb"}, + wantPosts: 0, + wantEdits: 1, + wantAttempt: 2, + wantLast: "<sub>Attempt 2: the same block hit heads `aaa`, `bbb`.</sub>", + }, + { + name: "a stranger's marker is not edited", + existing: []map[string]any{{ + "id": 5, + "user": map[string]string{"login": "mallory"}, + "body": unauthorizedMarker(step) + "\nforged", + }}, + heads: []string{"aaa"}, + wantPosts: 1, + wantEdits: 0, + wantAttempt: 1, + }, + } { + t.Run(tc.name, func(t *testing.T) { + fx := validContributorFixture() + fx.prComments = tc.existing + api := newContributorLaneAPI(t, &fx) + defer api.Close() + clock := &contributorLaneClock{at: time.Date(2026, 11, 4, 12, 0, 0, 0, time.UTC)} + engine := newContributorLaneEngine(api.URL, defaultContributorLanePolicy(), clock, Options{}) + for _, head := range tc.heads { + if err := engine.commentUnauthorized(context.Background(), "acme", "widget", 7, head, step, unauthorizedPermissionActionsWrite, "do it"); err != nil { + t.Fatalf("head %s: %v", head, err) + } + } + if fx.comments != tc.wantPosts || len(fx.commentEdits) != tc.wantEdits { + t.Fatalf("posts = %d edits = %d, want %d/%d\nedits: %q", fx.comments, len(fx.commentEdits), tc.wantPosts, tc.wantEdits, fx.commentEdits) + } + var notes []string + for _, c := range fx.prComments { + if body, _ := c["body"].(string); isUnauthorizedCommentFor(step)(body) && c["user"].(map[string]string)["login"] == testHiveAppBotLogin { + notes = append(notes, body) + } + } + if len(notes) != 1 { + t.Fatalf("own notes for step = %d, want 1: %q", len(notes), notes) + } + if got := parseUnauthorizedAttempts(notes[0]); got.Count != tc.wantAttempt { + t.Fatalf("attempts = %+v, want count %d", got, tc.wantAttempt) + } + if tc.wantLast != "" && !strings.Contains(notes[0], tc.wantLast) { + t.Fatalf("note lacks %q:\n%s", tc.wantLast, notes[0]) + } + if !strings.HasPrefix(notes[0], unauthorizedMarker(step)+"\n") { + t.Fatalf("note not under the current marker:\n%s", notes[0]) + } + // A different step is its own note. + if err := engine.commentUnauthorized(context.Background(), "acme", "widget", 7, "aaa", unauthorizedStepApproveWorkflowRuns, unauthorizedPermissionActionsWrite, "click"); err != nil { + t.Fatal(err) + } + if fx.comments != tc.wantPosts+1 { + t.Fatalf("other step did not post its own note: posts = %d", fx.comments) + } + }) + } +} diff --git a/src/pkg/github/automerge/automerge_contributor_lane_test.go b/src/pkg/github/automerge/automerge_contributor_lane_test.go index 09c4f252a3..8adc14de7e 100644 --- a/src/pkg/github/automerge/automerge_contributor_lane_test.go +++ b/src/pkg/github/automerge/automerge_contributor_lane_test.go @@ -91,6 +91,9 @@ type contributorLaneFixture struct { updates int lastComment string allComments []string + // commentEdits records the bodies written by PATCH /issues/comments/ID, + // which also rewrites the matching prComments entry. + commentEdits []string // checkCompletedAt, when set, is the completed_at the check-runs // endpoint reports for sha7 (RFC 3339); empty omits the field. checkCompletedAt string @@ -474,6 +477,19 @@ func newContributorLaneAPI(t *testing.T, fx *contributorLaneFixture) *httptest.S "body": payload.Body, }) json.NewEncoder(w).Encode(map[string]any{"id": 1000 + fx.comments}) + case r.Method == http.MethodPatch && strings.HasPrefix(r.URL.Path, "/repos/acme/widget/issues/comments/"): + id, _ := strconv.ParseInt(strings.TrimPrefix(r.URL.Path, "/repos/acme/widget/issues/comments/"), 10, 64) + var payload struct { + Body string `json:"body"` + } + _ = json.NewDecoder(r.Body).Decode(&payload) + for _, c := range fx.prComments { + if cid, ok := c["id"]; ok && fmt.Sprint(cid) == strconv.FormatInt(id, 10) { + c["body"] = payload.Body + } + } + fx.commentEdits = append(fx.commentEdits, payload.Body) + json.NewEncoder(w).Encode(map[string]any{"id": id, "body": payload.Body}) case r.Method == http.MethodGet && otherPRCommentsNumber(r.URL.Path) > 0: comments := fx.otherPRComments[otherPRCommentsNumber(r.URL.Path)] if comments == nil { diff --git a/src/pkg/github/automerge/automerge_contributor_nudge.go b/src/pkg/github/automerge/automerge_contributor_nudge.go index c9b659d5a7..7ae97ec8fc 100644 --- a/src/pkg/github/automerge/automerge_contributor_nudge.go +++ b/src/pkg/github/automerge/automerge_contributor_nudge.go @@ -17,20 +17,36 @@ import ( // Contributor nudge for stage/072-returned-to-contributor // (hivecommons/hive#12436). // -// When a contributor's PR lands in stage 072 the hive posts ONE idempotent -// comment @-mentioning the author with the concrete failing checks / review -// asks and a "reply here or push a new head" line, and — through the +// When a contributor's PR lands in stage 072 the hive posts ONE comment +// @-mentioning the author with the concrete failing checks / review asks and +// a "reply here or push a new head" line, and — through the // ContributorNudgeSink the dashboard hub implements — pushes the same -// diagnosis to the author's relay session as a fix-pr task. It re-nudges once -// more at the stall threshold and then stops: 2 nudges per head, re-armed -// only when the author pushes a new head. +// diagnosis to the author's relay session as a fix-pr task. +// +// The comment is one per PR (hivecommons/hive#17067): the marker names the +// reason class it explains, and a new head red for the same class, or a +// changed class, rewrites the hive's existing nudge comment in place rather +// than posting another copy (the relay dispatch and the adoption-grace +// ledger still see every head). While the same class persists the comment +// is rewritten once more after policy.RenudgeInterval +// (auto_merge.nudge_repeat_after, default 72h) as the last reminder, then +// the hive stops: 2 nudges per PR and reason class. // ContributorNudgeMarkerPrefix opens the nudge comment's machine marker. const ContributorNudgeMarkerPrefix = "<!-- hive:contributor-nudge" -// contributorNudgeCap is the documented maximum number of nudges per head. +// contributorNudgeCap is the documented maximum number of nudges per PR +// and reason class. const contributorNudgeCap = 2 +// ContributorNudgeMarker renders the marker that keys the one nudge comment +// on a PR: `<!-- hive:contributor-nudge reason=<slug>` plus head, ordinal +// and delivery mode. The upsert searches for ContributorNudgeMarkerPrefix +// alone, so a changed reason slug still finds the comment. +func ContributorNudgeMarker(reason, head string, nudge int, mode string) string { + return fmt.Sprintf("%s reason=%s head=%s n=%d mode=%s -->", ContributorNudgeMarkerPrefix, stagelabels.NudgeReasonSlug(reason), head, nudge, nonEmpty(mode, "comment")) +} + // ContributorNudge is the diagnosis handed to the sink for one PR in stage 072. type ContributorNudge struct { Owner, Repo string @@ -54,9 +70,11 @@ type ContributorNudge struct { // HumanChangesRequested is true when a human reviewer asked for changes // (outranks CI-red in the contributor's fix queue). HumanChangesRequested bool - // Nudge is 1 for the first nudge at this head, 2 for the stall re-nudge. + // Nudge is 1 for the first nudge for this reason class, 2 for the + // repeat re-nudge, and 0 for a head-only rewrite of the existing + // comment (the class is unchanged and already counted). Nudge int - // Stalled is true when this nudge is the stall re-nudge. + // Stalled is true when this nudge is the repeat re-nudge. Stalled bool } @@ -199,11 +217,13 @@ func nudgeDiagnosisRouted(reason string, d stageDetail, route *stagelabels.Route } // ContributorNudgeComment renders the nudge comment. The marker carries the -// head, the nudge ordinal and the delivery mode so a later pass can prove the -// comment exists without a per-PR GET. +// reason class, the head, the nudge ordinal and the delivery mode so a later +// pass can prove the comment exists and what it explains without parsing +// the prose. func ContributorNudgeComment(n ContributorNudge, out ContributorNudgeOutcome) string { var b strings.Builder - fmt.Fprintf(&b, "%s head=%s n=%d mode=%s -->\n", ContributorNudgeMarkerPrefix, n.HeadSHA, n.Nudge, nonEmpty(out.Mode, "comment")) + b.WriteString(ContributorNudgeMarker(n.Reason, n.HeadSHA, n.Nudge, out.Mode)) + b.WriteString("\n") if n.Stalled { fmt.Fprintf(&b, "@%s this PR has been waiting on you for a while (`%s`). ", n.Author, stagelabels.ReturnedToContributor.Label()) } else { @@ -275,23 +295,30 @@ func nonEmpty(s, def string) string { return s } -// nudgeDue decides whether a nudge is owed for the record at this head: the -// first on entering 072 with a new head, the second once renudge elapsed -// (the stall threshold), never a third. -func nudgeDue(rec stagelabels.Record, head string, renudge time.Duration, now time.Time) (ordinal int, ok bool) { +// nudgeDue decides whether the nudge comment is owed a write for the record +// at this head and reason: ordinal 1 when the reason class is new to the PR +// (first nudge, or a changed reason rewriting the comment), 0 when a new +// head is red for the class already explained (rewrite only, uncounted), +// 2 once repeatAfter elapsed since the class was last counted — never a +// third. Same head, same class, inside the window: nothing. +func nudgeDue(rec stagelabels.Record, head, reason string, repeatAfter time.Duration, now time.Time) (ordinal int, ok bool) { if head == "" { return 0, false } - if rec.NudgeHead != head { + slug := stagelabels.NudgeReasonSlug(reason) + if rec.NudgeReason != slug { return 1, true } - if rec.NudgeCount >= contributorNudgeCap { + if rec.NudgeHead != head { + return 0, true + } + if rec.NudgeReasonCount >= contributorNudgeCap { return 0, false } - if renudge <= 0 || rec.LastNudgeAt.IsZero() || now.Sub(rec.LastNudgeAt) < renudge { + if repeatAfter <= 0 || rec.NudgeReasonAt.IsZero() || now.Sub(rec.NudgeReasonAt) < repeatAfter { return 0, false } - return rec.NudgeCount + 1, true + return rec.NudgeReasonCount + 1, true } // nudgeContributor runs the stage-072 nudge for one observation. It returns @@ -301,11 +328,7 @@ func (c *Engine) nudgeContributor(ctx context.Context, store *stagelabels.Store, if !ok || obs.Author == "" { return 0, nil } - renudge := policy.RenudgeInterval - if renudge <= 0 { - renudge = stagelabels.Dwell(stagelabels.ReturnedToContributor, policy.Dwell) - } - ordinal, due := nudgeDue(rec, obs.HeadSHA, renudge, now) + ordinal, due := nudgeDue(rec, obs.HeadSHA, obs.Reason, policy.RenudgeInterval, now) if !due { return 0, nil } @@ -323,27 +346,49 @@ func (c *Engine) nudgeContributor(ctx context.Context, store *stagelabels.Store, return 0, nil } } + // A head-only rewrite (ordinal 0) keeps the class's recorded count in + // the marker; the author pushed, so it is not the stall reminder. + shown := ordinal + if shown == 0 { + shown = max(rec.NudgeReasonCount, 1) + } n := ContributorNudge{ Owner: obs.Owner, Repo: obs.Repo, Display: obs.Display, Number: obs.Number, HeadSHA: obs.HeadSHA, Title: obs.Title, URL: obs.URL, Author: obs.Author, OpenedAt: obs.OpenedAt, Reason: obs.Reason, FailingChecks: checks, ReviewAsks: asks, HumanChangesRequested: human, - Nudge: ordinal, Stalled: ordinal > 1, + Nudge: shown, Stalled: ordinal > 1, } var out ContributorNudgeOutcome if c.contributorNudge != nil { out = c.contributorNudge.Nudge(ctx, n) } body := ContributorNudgeComment(n, out) - if _, _, err := c.gh.Issues.CreateComment(ctx, obs.Owner, obs.Repo, obs.Number, &gh.IssueComment{Body: gh.Ptr(body)}); err != nil { - c.warn("stage labels: contributor nudge failed", "repo", obs.Display, "pr", obs.Number, "error", err) - return 0, err + // One nudge comment per PR (hivecommons/hive#17067): the hive's + // existing comment carrying the marker is rewritten for a new head or + // a changed reason; an edit notifies nobody, the relay dispatch above + // is the interrupt. + posted := 0 + if existing := c.findOwnEntryComment(ctx, obs, ContributorNudgeMarkerPrefix); existing != nil { + if existing.GetBody() != body { + if _, _, err := c.gh.Issues.EditComment(ctx, obs.Owner, obs.Repo, existing.GetID(), &gh.IssueComment{Body: gh.Ptr(body)}); err != nil { // writeback:gated + c.warn("stage labels: contributor nudge edit failed", "repo", obs.Display, "pr", obs.Number, "error", err) + return 0, err + } + } + } else { + if _, _, err := c.gh.Issues.CreateComment(ctx, obs.Owner, obs.Repo, obs.Number, &gh.IssueComment{Body: gh.Ptr(body)}); err != nil { + c.warn("stage labels: contributor nudge failed", "repo", obs.Display, "pr", obs.Number, "error", err) + return 0, err + } + posted = 1 } // "queued" only says the author has a relay registered here; the work // sits in its queue whether or not that relay is connected. Counting it // as online gave an offline clanker the 2h online grace (#15566). - store.MarkNudged(key, obs.HeadSHA, ordinal, out.Online || out.Mode == "spawn" || out.Mode == "preempt", now) - c.info("stage labels: contributor nudged", "repo", obs.Display, "pr", obs.Number, "author", obs.Author, "head", obs.HeadSHA, "nudge", ordinal, "mode", nonEmpty(out.Mode, "comment"), "online", out.Online, "queue_depth", out.QueueDepth, "relay_failed", out.RelayFailed, "reason", obs.Reason) - return 1, nil + store.MarkNudged(key, obs.HeadSHA, max(ordinal, 1), out.Online || out.Mode == "spawn" || out.Mode == "preempt", now) + store.MarkNudgedReason(key, obs.Reason, ordinal, now) + c.info("stage labels: contributor nudged", "repo", obs.Display, "pr", obs.Number, "author", obs.Author, "head", obs.HeadSHA, "nudge", ordinal, "posted", posted == 1, "mode", nonEmpty(out.Mode, "comment"), "online", out.Online, "queue_depth", out.QueueDepth, "relay_failed", out.RelayFailed, "reason", obs.Reason) + return posted, nil } // withoutForkGuard drops the fork-guard checks from a nudge's failing @@ -462,10 +507,14 @@ func (c *Engine) withdrawNudge(ctx context.Context, store *stagelabels.Store, ke c.warn("stage labels: could not list comments to withdraw the contributor nudge", "repo", obs.Display, "pr", obs.Number, "error", err) return } - prefix := ContributorNudgeMarkerPrefix + " head=" + obs.HeadSHA + " " + headField := " head=" + obs.HeadSHA + " " edited := 0 for _, cm := range comments { - if !cm.Own || !strings.HasPrefix(cm.Body, prefix) || strings.Contains(cm.Body, nudgeWithdrawnMarker) { + // The marker carries the reason slug before the head + // (ContributorNudgeMarker), so match the prefix and the head field + // rather than one fixed spelling. + marker, _, _ := strings.Cut(cm.Body, "-->") + if !cm.Own || !strings.HasPrefix(cm.Body, ContributorNudgeMarkerPrefix+" ") || !strings.Contains(marker, headField) || strings.Contains(cm.Body, nudgeWithdrawnMarker) { continue } // Rewrites the hive's own nudge; an edit notifies nobody. @@ -488,50 +537,6 @@ func (c *Engine) resolveNudge(ctx context.Context, rec stagelabels.Record, had b c.contributorNudge.Resolve(ctx, obs.Owner, obs.Repo, obs.Number) } -// SignoffAttributionMarkerPrefix opens the one comment a human author gets -// when their head is held for hive-signoff-attribution; the head keeps it -// idempotent per push. -const SignoffAttributionMarkerPrefix = "<!-- hive:signoff-attribution" - -// SignoffAttributionComment renders the author-facing comment for a human -// PR parked at 071 on LaneReasonHiveSignoffAttribution: who owes the fix, -// why no agent can do it, and the exact commands. -func SignoffAttributionComment(n ContributorNudge, stage stagelabels.Stage) string { - var b strings.Builder - fmt.Fprintf(&b, "%s head=%s -->\n", SignoffAttributionMarkerPrefix, n.HeadSHA) - fmt.Fprintf(&b, "@%s this PR is back in your court (`%s`). ", n.Author, stage.Label()) - b.WriteString("Its commits are signed off as the hive App rather than as you, so a squash merge would misattribute them and the sign-off attribution check stays red. No hive agent can rewrite a contributor's commits — the fix is yours:\n\n") - for _, a := range n.ReviewAsks { - fmt.Fprintf(&b, "- %s\n", a) - } - b.WriteString("\nOnce the new head lands, CI and the review swarm re-run automatically and the PR returns to the normal path.\n") - return b.String() -} - -// nudgeSignoffAttribution posts SignoffAttributionComment once per head for -// a non-clanker author (a clanker gets the regular 072 nudge, which carries -// the same ask). It returns the number of comments posted. -func (c *Engine) nudgeSignoffAttribution(ctx context.Context, store *stagelabels.Store, key string, obs stageObservation, now time.Time) (int, error) { - rec, ok := store.Get(key) - if !ok || obs.Author == "" || obs.HeadSHA == "" || rec.NudgeHead == obs.HeadSHA { - return 0, nil - } - _, asks, _ := nudgeDiagnosis(obs.Reason, obs.Detail) - n := ContributorNudge{ - Owner: obs.Owner, Repo: obs.Repo, Display: obs.Display, Number: obs.Number, - HeadSHA: obs.HeadSHA, Title: obs.Title, URL: obs.URL, Author: obs.Author, OpenedAt: obs.OpenedAt, - Reason: obs.Reason, ReviewAsks: asks, Nudge: 1, - } - body := SignoffAttributionComment(n, fixingStage(obs)) - if _, _, err := c.gh.Issues.CreateComment(ctx, obs.Owner, obs.Repo, obs.Number, &gh.IssueComment{Body: gh.Ptr(body)}); err != nil { - c.warn("stage labels: sign-off attribution comment failed", "repo", obs.Display, "pr", obs.Number, "error", err) - return 0, err - } - store.MarkNudged(key, obs.HeadSHA, 1, false, now) - c.info("stage labels: author told to re-sign the head", "repo", obs.Display, "pr", obs.Number, "author", obs.Author, "head", obs.HeadSHA, "squash_unsafe_hive", obs.Detail.DCOSquashUnsafeHive) - return 1, nil -} - // TrustedHuman071MarkerPrefix opens the one comment a trusted human author // gets when their PR enters stage 071 (hivecommons/hive#13636); the head keeps // it idempotent per push. diff --git a/src/pkg/github/automerge/automerge_contributor_nudge_test.go b/src/pkg/github/automerge/automerge_contributor_nudge_test.go index 526626b709..472dd26235 100644 --- a/src/pkg/github/automerge/automerge_contributor_nudge_test.go +++ b/src/pkg/github/automerge/automerge_contributor_nudge_test.go @@ -105,14 +105,18 @@ func nudgeComments(api *stageAPI) []string { return out } -// One nudge per head on entering 072, a second at the stall threshold, never -// a third; a new head re-arms; leaving 072 resolves the sink entry. -func TestContributorNudgeOncePerHeadThenAtStall(t *testing.T) { +// One nudge comment per PR (hivecommons/hive#17067): posted on entering 072, +// rewritten in place for a new head red for the same reason class and for a +// changed class, rewritten once more as the repeat reminder after +// RenudgeInterval, never a third time for the same class; leaving 072 +// resolves the sink entry. +func TestContributorNudgeOncePerPRAndReason(t *testing.T) { api, closeAPI := seededStageAPI(t) defer closeAPI() + api.statefulComments = true clock := &contributorLaneClock{at: time.Date(2026, 10, 16, 12, 0, 0, 0, time.UTC)} sink := &fakeNudgeSink{outcome: ContributorNudgeOutcome{Mode: "spawn", Online: true}} - e := newNudgeEngine(t, apiURLOf(t, api), clock, sink, StageLabelPolicy{Enabled: true, ContributorNudge: true}) + e := newNudgeEngine(t, apiURLOf(t, api), clock, sink, StageLabelPolicy{Enabled: true, ContributorNudge: true, RenudgeInterval: 72 * time.Hour}) ctx := context.Background() observe := func(pr *gh.PullRequest, reason string) StageLabelResult { e.recordStage(stageLaneContributor, "acme/widget", "acme", "widget", pr, reason, false, nil) @@ -123,15 +127,22 @@ func TestContributorNudgeOncePerHeadThenAtStall(t *testing.T) { } return res } + lastEdit := func() string { + if len(api.commentEdits) == 0 { + return "" + } + return api.commentEdits[len(api.commentEdits)-1] + } + in072 := []string{"stage/072-returned-to-contributor", "role/contributor", "author/clanker"} + stalled := append([]string{"stage/stalled"}, in072...) res := observe(nudgePR(7, "aaa"), "check-failing:unit") if got := nudgeComments(api); len(got) != 1 { t.Fatalf("nudges=%d comments=%v", len(got), api.comments) } else { - c := got[0] - for _, want := range []string{"head=aaa n=1 mode=spawn", "@mallory", "`unit`", "push a new head", "parallel fix session"} { - if !strings.Contains(c, want) { - t.Fatalf("comment missing %q:\n%s", want, c) + for _, want := range []string{"reason=check-failing head=aaa n=1 mode=spawn", "@mallory", "`unit`", "push a new head", "parallel fix session"} { + if !strings.Contains(got[0], want) { + t.Fatalf("comment missing %q:\n%s", want, got[0]) } } } @@ -140,54 +151,92 @@ func TestContributorNudgeOncePerHeadThenAtStall(t *testing.T) { t.Fatalf("res=%+v sink=%+v", res, sink.nudges) } - // Same head, same stage, next cycles: idempotent. + // Same head, same class, next cycles: idempotent, even past the stall + // threshold (24h) — the repeat window is 72h. api.reset() - labels := []string{"stage/072-returned-to-contributor", "role/contributor", "author/clanker"} clock.advance(time.Hour) - observe(nudgePR(7, "aaa", labels...), "check-failing:unit") - if api.writes() != 0 || len(sink.nudges) != 1 { - t.Fatalf("re-nudged early: comments=%v sink=%d", api.comments, len(sink.nudges)) + observe(nudgePR(7, "aaa", in072...), "check-failing:unit") + if api.writes() != 0 || len(api.commentEdits) != 0 || len(sink.nudges) != 1 { + t.Fatalf("re-nudged early: comments=%v edits=%v sink=%d", api.comments, api.commentEdits, len(sink.nudges)) } - - // Stall threshold (dwell 24h): stalled label + second nudge, no third. clock.advance(23 * time.Hour) - observe(nudgePR(7, "aaa", labels...), "check-failing:unit") - if got := nudgeComments(api); len(got) != 1 || !strings.Contains(got[0], "n=2") || !strings.Contains(got[0], "last automatic reminder") { - t.Fatalf("stall nudge: %v", api.comments) + observe(nudgePR(7, "aaa", in072...), "check-failing:unit") + if len(nudgeComments(api)) != 0 || len(api.commentEdits) != 0 || len(sink.nudges) != 1 { + t.Fatalf("stall threshold nudged: comments=%v edits=%v", api.comments, api.commentEdits) } if !reflect.DeepEqual(api.added, [][]string{{"stage/stalled"}}) { t.Fatalf("stalled label: %v", api.added) } - if len(sink.nudges) != 2 || !sink.nudges[1].Stalled { + + // New head, still red for the same class (another check): the one + // comment is rewritten, nothing new is posted, the relay is told, and + // the class count does not move. + api.reset() + clock.advance(time.Hour) + res = observe(nudgePR(7, "bbb", stalled...), "check-failing:lint") + if res.Comments != 0 || len(nudgeComments(api)) != 0 || len(api.commentEdits) != 1 { + t.Fatalf("new head same class: res=%+v comments=%v edits=%v", res, api.comments, api.commentEdits) + } + for _, want := range []string{"reason=check-failing head=bbb n=1 mode=spawn", "`lint`"} { + if !strings.Contains(lastEdit(), want) { + t.Fatalf("rewrite missing %q:\n%s", want, lastEdit()) + } + } + if len(sink.nudges) != 2 || sink.nudges[1].Nudge != 1 || sink.nudges[1].Stalled { t.Fatalf("sink=%+v", sink.nudges) } + rec, _ := e.stageStore.Get(stageKey("acme", "widget", 7)) + if rec.NudgeReason != "check-failing" || rec.NudgeReasonCount != 1 || rec.NudgeHead != "bbb" { + t.Fatalf("ledger %+v", rec) + } + + // 72h after the class was first counted: the one repeat reminder, as a + // rewrite; then never again for this class. api.reset() clock.advance(48 * time.Hour) - observe(nudgePR(7, "aaa", "stage/stalled", "stage/072-returned-to-contributor", "role/contributor", "author/clanker"), "check-failing:unit") - if len(nudgeComments(api)) != 0 || len(sink.nudges) != 2 { - t.Fatalf("third nudge posted: %v", api.comments) + observe(nudgePR(7, "bbb", stalled...), "check-failing:lint") + if len(nudgeComments(api)) != 0 || len(api.commentEdits) != 2 || !strings.Contains(lastEdit(), "reason=check-failing head=bbb n=2") || !strings.Contains(lastEdit(), "last automatic reminder") { + t.Fatalf("repeat nudge: comments=%v edits=%v", api.comments, api.commentEdits) + } + if len(sink.nudges) != 3 || !sink.nudges[2].Stalled || sink.nudges[2].Nudge != 2 { + t.Fatalf("sink=%+v", sink.nudges) + } + api.reset() + clock.advance(96 * time.Hour) + observe(nudgePR(7, "bbb", stalled...), "check-failing:lint") + if len(nudgeComments(api)) != 0 || len(api.commentEdits) != 2 || len(sink.nudges) != 3 { + t.Fatalf("third nudge: comments=%v edits=%v sink=%d", api.comments, api.commentEdits, len(sink.nudges)) } - // Author pushes a new head that is still red: count restarts. + // A different class on a new head restarts the count — still as a + // rewrite of the same comment. api.reset() - observe(nudgePR(7, "bbb", "stage/stalled", "stage/072-returned-to-contributor", "role/contributor", "author/clanker"), "changes-requested") - if got := nudgeComments(api); len(got) != 1 || !strings.Contains(got[0], "head=bbb n=1") || !strings.Contains(got[0], "reviewer requested changes") { - t.Fatalf("new-head nudge: %v", api.comments) + res = observe(nudgePR(7, "ccc", stalled...), "changes-requested") + if res.Comments != 0 || len(nudgeComments(api)) != 0 || len(api.commentEdits) != 3 { + t.Fatalf("changed reason: res=%+v comments=%v edits=%v", res, api.comments, api.commentEdits) + } + for _, want := range []string{"reason=changes-requested head=ccc n=1", "reviewer requested changes"} { + if !strings.Contains(lastEdit(), want) { + t.Fatalf("rewrite missing %q:\n%s", want, lastEdit()) + } } - if len(sink.nudges) != 3 || !sink.nudges[2].HumanChangesRequested { + if len(sink.nudges) != 4 || !sink.nudges[3].HumanChangesRequested || sink.nudges[3].Nudge != 1 { t.Fatalf("sink=%+v", sink.nudges) } if len(sink.resolved) != 0 { t.Fatalf("resolved while still in 072: %v", sink.resolved) } + if len(api.comments) != 0 { + t.Fatalf("a second nudge comment was posted: %v", api.comments) + } // New head goes green and awaits review: leaves 072 → Resolve once. api.reset() - observe(nudgePR(7, "ccc", "stage/072-returned-to-contributor", "role/contributor", "author/clanker"), "required-check-missing:unit") + observe(nudgePR(7, "ddd", in072...), "required-check-missing:unit") if !reflect.DeepEqual(sink.resolved, []int{7}) { t.Fatalf("resolved=%v", sink.resolved) } - observe(nudgePR(7, "ccc", "stage/050-review-pending", "role/contributor", "author/clanker"), "required-check-missing:unit") + observe(nudgePR(7, "ddd", "stage/050-review-pending", "role/contributor", "author/clanker"), "required-check-missing:unit") if !reflect.DeepEqual(sink.resolved, []int{7}) { t.Fatalf("resolve repeated: %v", sink.resolved) } @@ -230,6 +279,7 @@ func TestContributorNudgeTerminalDisabledAndNilSink(t *testing.T) { } api.reset() + api.statefulComments = true e = newNudgeEngine(t, apiURLOf(t, api), clock, nil, StageLabelPolicy{Enabled: true, ContributorNudge: true, RenudgeInterval: time.Hour}) pr := nudgePR(9, "aaa") e.recordStage(stageLaneTrusted, "acme/widget", "acme", "widget", pr, "status-failure", false, nil) @@ -239,15 +289,15 @@ func TestContributorNudgeTerminalDisabledAndNilSink(t *testing.T) { if got := nudgeComments(api); len(got) != 1 || !strings.Contains(got[0], "mode=comment") || !strings.Contains(got[0], "`status-failure`") { t.Fatalf("nil-sink nudge: %v", api.comments) } - // RenudgeInterval overrides the dwell: second nudge after 1h, not 24h. + // RenudgeInterval times the repeat: rewritten (not re-posted) after 1h. api.reset() clock.advance(time.Hour) e.recordStage(stageLaneTrusted, "acme/widget", "acme", "widget", nudgePR(9, "aaa", "stage/072-returned-to-contributor", "role/trusted", "author/clanker"), "status-failure", false, nil) if _, err := e.ApplyStageLabels(ctx); err != nil { t.Fatal(err) } - if got := nudgeComments(api); len(got) != 1 || !strings.Contains(got[0], "n=2") { - t.Fatalf("renudge interval: %v", api.comments) + if len(nudgeComments(api)) != 0 || len(api.commentEdits) != 1 || !strings.Contains(api.commentEdits[0], "reason=status-failure head=aaa n=2") { + t.Fatalf("renudge interval: comments=%v edits=%v", api.comments, api.commentEdits) } // A hive-authored PR (self lane → 070-fixing) is never nudged. api.reset() @@ -285,15 +335,39 @@ func TestNudgeDiagnosisAndDue(t *testing.T) { if !reflect.DeepEqual(checks, []string{"links"}) { t.Fatalf("red optional without detail: %v", checks) } +} + +func TestNudgeDue(t *testing.T) { now := time.Date(2026, 10, 16, 12, 0, 0, 0, time.UTC) - if _, ok := nudgeDue(stagelabels.Record{}, "", time.Hour, now); ok { - t.Fatal("empty head due") - } - if n, ok := nudgeDue(stagelabels.Record{NudgeHead: "a", NudgeCount: 1, LastNudgeAt: now.Add(-time.Hour)}, "a", 0, now); ok || n != 0 { - t.Fatal("zero renudge interval should never re-nudge") + counted := stagelabels.Record{NudgeHead: "a", NudgeReason: "check-failing", NudgeReasonCount: 1, NudgeReasonAt: now.Add(-73 * time.Hour)} + cases := []struct { + name string + rec stagelabels.Record + head string + reason string + repeat time.Duration + ordinal int + ok bool + }{ + {name: "empty head", rec: stagelabels.Record{}, head: "", reason: "check-failing:unit", repeat: time.Hour}, + {name: "first nudge", rec: stagelabels.Record{}, head: "a", reason: "check-failing:unit", repeat: time.Hour, ordinal: 1, ok: true}, + {name: "same head same class inside window", rec: counted, head: "a", reason: "check-failing:lint", repeat: 100 * time.Hour}, + {name: "same head same class after window", rec: counted, head: "a", reason: "check-failing:lint", repeat: 72 * time.Hour, ordinal: 2, ok: true}, + {name: "zero repeat never re-nudges", rec: counted, head: "a", reason: "check-failing:unit", repeat: 0}, + {name: "zero NudgeReasonAt never re-nudges", rec: stagelabels.Record{NudgeHead: "a", NudgeReason: "check-failing", NudgeReasonCount: 1}, head: "a", reason: "check-failing:unit", repeat: time.Hour}, + {name: "cap reached", rec: stagelabels.Record{NudgeHead: "a", NudgeReason: "check-failing", NudgeReasonCount: 2, NudgeReasonAt: now.Add(-200 * time.Hour)}, head: "a", reason: "check-failing:unit", repeat: time.Hour}, + {name: "new head same class rewrites uncounted", rec: counted, head: "b", reason: "required-check-failing:lint", repeat: time.Hour, ordinal: 0, ok: true}, + {name: "new head same class at cap still rewrites", rec: stagelabels.Record{NudgeHead: "a", NudgeReason: "check-failing", NudgeReasonCount: 2, NudgeReasonAt: now}, head: "b", reason: "check-failing:unit", repeat: time.Hour, ordinal: 0, ok: true}, + {name: "changed class restarts", rec: counted, head: "a", reason: "conflicting", repeat: time.Hour, ordinal: 1, ok: true}, + {name: "legacy record without class", rec: stagelabels.Record{NudgeHead: "a", NudgeCount: 2, LastNudgeAt: now}, head: "a", reason: "check-failing:unit", repeat: time.Hour, ordinal: 1, ok: true}, } - if n, ok := nudgeDue(stagelabels.Record{NudgeHead: "a", NudgeCount: 1}, "a", time.Hour, now); ok || n != 0 { - t.Fatal("zero LastNudgeAt re-nudged") + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + n, ok := nudgeDue(tc.rec, tc.head, tc.reason, tc.repeat, now) + if n != tc.ordinal || ok != tc.ok { + t.Fatalf("nudgeDue = (%d, %v), want (%d, %v)", n, ok, tc.ordinal, tc.ok) + } + }) } } diff --git a/src/pkg/github/automerge/automerge_contributor_workflow_approval.go b/src/pkg/github/automerge/automerge_contributor_workflow_approval.go index bb26a3a436..6232e3f146 100644 --- a/src/pkg/github/automerge/automerge_contributor_workflow_approval.go +++ b/src/pkg/github/automerge/automerge_contributor_workflow_approval.go @@ -130,7 +130,7 @@ func (c *Engine) workflowFenceReleased(ctx context.Context, displayRepo, owner, verdictState = workflowApprovalVerdictAnswered } } - if hasCommentWithPrefix(comments, unauthorizedMarker(headSHA, unauthorizedStepMergeWorkflowPath)) { + if unauthorizedCommentCoversHead(comments, unauthorizedStepMergeWorkflowPath, headSHA) { // A previous process already learnt the App cannot merge this head; // re-arm the in-memory mark so the reason flips without another // merge attempt. diff --git a/src/pkg/github/automerge/automerge_contributor_workflow_approval_test.go b/src/pkg/github/automerge/automerge_contributor_workflow_approval_test.go index ab29a95117..0ffc78ef99 100644 --- a/src/pkg/github/automerge/automerge_contributor_workflow_approval_test.go +++ b/src/pkg/github/automerge/automerge_contributor_workflow_approval_test.go @@ -510,7 +510,7 @@ func TestContributorLaneWorkflowFenceMergeUnauthorizedFallback(t *testing.T) { fx.prComments = []map[string]any{{ "id": 5, "user": map[string]string{"login": testHiveAppBotLogin}, - "body": unauthorizedComment("sha7", unauthorizedStepMergeWorkflowPath, unauthorizedPermissionWorkflowsWrite, "click"), + "body": unauthorizedComment("sha7", unauthorizedStepMergeWorkflowPath, unauthorizedPermissionWorkflowsWrite, "click", unauthorizedAttempts{Count: 1, Heads: []string{"sha7"}}), }} } api := newContributorLaneAPI(t, &fx) @@ -555,7 +555,7 @@ func TestContributorLaneWorkflowFenceMergeUnauthorizedFallback(t *testing.T) { if !slices.Contains(fx.labels, unauthorizedLabel) { t.Fatalf("labels = %v, want %q", fx.labels, unauthorizedLabel) } - marker := unauthorizedMarker("sha7", unauthorizedStepMergeWorkflowPath) + marker := unauthorizedMarker(unauthorizedStepMergeWorkflowPath) unauthorizedComments := 0 for _, body := range fx.allComments { if strings.HasPrefix(body, marker) { diff --git a/src/pkg/github/automerge/automerge_marker_upsert.go b/src/pkg/github/automerge/automerge_marker_upsert.go new file mode 100644 index 0000000000..494b200e0d --- /dev/null +++ b/src/pkg/github/automerge/automerge_marker_upsert.go @@ -0,0 +1,123 @@ +package automerge + +// One marker comment per PR, edited in place (hivecommons/hive#17066). +// +// Several lane notes used to key their marker on the head SHA so a new push +// got a fresh copy: on a long-lived PR with many pushes that meant eight +// `hive:signoff-attribution` and five `hive:unauthorized` comments saying +// the same thing (hivecommons/hive#16524). The claim ledger +// (hivecommons/hive#16433) showed the quieter shape: find the hive's own +// comment carrying the marker and rewrite it, which notifies nobody, and +// keep a short, capped "updated" history inside the comment so a reader +// who saw the earlier wording knows what changed. + +import ( + "context" + "strings" + "time" + + gh "github.com/google/go-github/v72/github" +) + +const ( + // markerHistoryCap bounds the "updated" lines kept inside an upserted + // comment: the five most recent, oldest dropped first. + markerHistoryCap = 5 + // markerHistoryHeading opens the history block; every line after it + // that starts with markerHistoryBullet is one history entry. + markerHistoryHeading = "<sub>Updates (newest last):</sub>" + markerHistoryBullet = "- " + // markerHistoryTimeLayout is the timestamp a history line carries. + markerHistoryTimeLayout = "2006-01-02 15:04 UTC" +) + +// findOwnMarkerComment returns the most recent comment on owner/repo#number +// that match accepts and that one of the hive's own accounts wrote, or nil +// when none exists. Only the hive's App login counts as its own: anyone can +// type a marker, and the hive must never edit a stranger's comment. When +// the hive cannot name its App login, any author is accepted — the same +// fallback the sentinel's marker reads use. +func (c *Engine) findOwnMarkerComment(ctx context.Context, owner, repo string, number int, match func(body string) bool) (*gh.IssueComment, error) { + if c == nil || c.gh == nil || match == nil { + return nil, nil + } + comments, err := c.listIssueComments(ctx, owner, repo, number) + if err != nil { + return nil, err + } + app := "" + if c.transport != nil { + app = normalizeBotLogin(c.transport.AppBotLogin()) + } + var found *gh.IssueComment + for _, cm := range comments { + if cm == nil || !match(cm.GetBody()) { + continue + } + if app != "" && normalizeBotLogin(cm.GetUser().GetLogin()) != app { + continue + } + found = cm + } + return found, nil +} + +// editMarkerComment rewrites the hive's own comment id with body. An edit +// notifies nobody, which is the point. +func (c *Engine) editMarkerComment(ctx context.Context, owner, repo string, id int64, body string) error { + _, _, err := c.gh.Issues.EditComment(ctx, owner, repo, id, &gh.IssueComment{Body: gh.Ptr(body)}) // writeback:gated + return err +} + +// splitMarkerHistory separates an upserted comment body into the part +// before the history block and the history lines themselves (without the +// bullet). A body with no history block returns itself and nil. +func splitMarkerHistory(body string) (core string, history []string) { + idx := strings.Index(body, markerHistoryHeading) + if idx < 0 { + return strings.TrimRight(body, "\n"), nil + } + core = strings.TrimRight(body[:idx], "\n") + for _, line := range strings.Split(body[idx+len(markerHistoryHeading):], "\n") { + line = strings.TrimSpace(line) + if strings.HasPrefix(line, markerHistoryBullet) { + history = append(history, strings.TrimPrefix(line, markerHistoryBullet)) + } + } + return core, history +} + +// appendMarkerHistory adds line to history, dropping the oldest entries so +// at most markerHistoryCap remain. +func appendMarkerHistory(history []string, line string) []string { + history = append(history, line) + if len(history) > markerHistoryCap { + history = history[len(history)-markerHistoryCap:] + } + return history +} + +// markerHistoryLine renders one history entry: the time, then what changed. +func markerHistoryLine(at time.Time, change string) string { + return "updated " + at.UTC().Format(markerHistoryTimeLayout) + ": " + change +} + +// renderMarkerHistory appends the history block to core; no history means +// core alone. +func renderMarkerHistory(core string, history []string) string { + core = strings.TrimRight(core, "\n") + "\n" + if len(history) == 0 { + return core + } + var b strings.Builder + b.WriteString(core) + b.WriteString("\n") + b.WriteString(markerHistoryHeading) + b.WriteString("\n") + for _, h := range history { + b.WriteString(markerHistoryBullet) + b.WriteString(h) + b.WriteString("\n") + } + return b.String() +} diff --git a/src/pkg/github/automerge/automerge_signoff_attribution.go b/src/pkg/github/automerge/automerge_signoff_attribution.go new file mode 100644 index 0000000000..81bc33ad5c --- /dev/null +++ b/src/pkg/github/automerge/automerge_signoff_attribution.go @@ -0,0 +1,126 @@ +package automerge + +// The sign-off attribution note, one per PR (hivecommons/hive#17066). +// +// A human whose head is held for hive-signoff-attribution gets told once +// with the exact commands. The note used to carry the head in its marker +// so every push re-posted it; now the PR carries one note that a new head +// rewrites in place, with a short capped history of what changed. + +import ( + "context" + "fmt" + "strings" + "time" + + gh "github.com/google/go-github/v72/github" + "github.com/hivecommons/hive/pkg/stagelabels" +) + +// SignoffAttributionMarkerPrefix opens the one comment a human author gets +// when their head is held for hive-signoff-attribution. Comments from +// before hivecommons/hive#17066 carry ` head=<sha>` after it; the upsert +// adopts the latest of those and rewrites it under SignoffAttributionMarker. +const SignoffAttributionMarkerPrefix = "<!-- hive:signoff-attribution" + +// SignoffAttributionMarker is the full first line of the comment. +const SignoffAttributionMarker = SignoffAttributionMarkerPrefix + " -->" + +// isSignoffAttributionComment reports whether body is a sign-off +// attribution note, in either the current or the per-head legacy form. +func isSignoffAttributionComment(body string) bool { + return strings.HasPrefix(body, SignoffAttributionMarkerPrefix) +} + +// SignoffAttributionComment renders the author-facing comment for a human +// PR parked at 071 on LaneReasonHiveSignoffAttribution: who owes the fix, +// why no agent can do it, and the exact commands. history is the capped +// list of earlier rewrites (nil on first post). +func SignoffAttributionComment(n ContributorNudge, stage stagelabels.Stage, history []string) string { + return renderMarkerHistory(signoffAttributionCore(n, stage), history) +} + +// signoffAttributionCore is the comment without its history block: the +// part whose change triggers a rewrite. +func signoffAttributionCore(n ContributorNudge, stage stagelabels.Stage) string { + var b strings.Builder + b.WriteString(SignoffAttributionMarker) + b.WriteString("\n") + fmt.Fprintf(&b, "@%s this PR is back in your court (`%s`). ", n.Author, stage.Label()) + b.WriteString("Its commits are signed off as the hive App rather than as you, so a squash merge would misattribute them and the sign-off attribution check stays red. No hive agent can rewrite a contributor's commits — the fix is yours:\n\n") + for _, a := range n.ReviewAsks { + fmt.Fprintf(&b, "- %s\n", a) + } + fmt.Fprintf(&b, "\nOnce the new head lands, CI and the review swarm re-run automatically and the PR returns to the normal path. Current head: `%s`.\n", shortSHA(n.HeadSHA)) + return b.String() +} + +// signoffAttributionChange is the history line for a rewrite on a new head. +func signoffAttributionChange(headSHA string, hiveSigned int) string { + if hiveSigned <= 0 { + hiveSigned = 1 + } + plural := "s" + if hiveSigned == 1 { + plural = "" + } + return fmt.Sprintf("head `%s`, %d commit%s signed off as the hive App", shortSHA(headSHA), hiveSigned, plural) +} + +// nudgeSignoffAttribution tells a non-clanker author once per PR that the +// head needs re-signing (a clanker gets the regular 072 nudge, which +// carries the same ask). The first head posts the comment; a later head +// rewrites it in place and appends one history line. It returns the number +// of comments posted (an edit counts zero). +func (c *Engine) nudgeSignoffAttribution(ctx context.Context, store *stagelabels.Store, key string, obs stageObservation, now time.Time) (int, error) { + rec, ok := store.Get(key) + if !ok || obs.Author == "" || obs.HeadSHA == "" || rec.NudgeHead == obs.HeadSHA { + return 0, nil + } + _, asks, _ := nudgeDiagnosis(obs.Reason, obs.Detail) + n := ContributorNudge{ + Owner: obs.Owner, Repo: obs.Repo, Display: obs.Display, Number: obs.Number, + HeadSHA: obs.HeadSHA, Title: obs.Title, URL: obs.URL, Author: obs.Author, OpenedAt: obs.OpenedAt, + Reason: obs.Reason, ReviewAsks: asks, Nudge: 1, + } + stage := fixingStage(obs) + existing, err := c.findOwnMarkerComment(ctx, obs.Owner, obs.Repo, obs.Number, isSignoffAttributionComment) + if err != nil { + // A list failure reads as "none": the note is posted rather than lost. + c.warn("stage labels: could not list comments for the sign-off attribution upsert", "repo", obs.Display, "pr", obs.Number, "error", err) + } + if existing != nil { + body, changed := signoffAttributionRewrite(existing.GetBody(), n, stage, obs.Detail.DCOSquashUnsafeHive, now) + if changed { + if err := c.editMarkerComment(ctx, obs.Owner, obs.Repo, existing.GetID(), body); err != nil { + c.warn("stage labels: sign-off attribution comment edit failed", "repo", obs.Display, "pr", obs.Number, "error", err) + return 0, err + } + c.info("stage labels: sign-off attribution note updated in place", "repo", obs.Display, "pr", obs.Number, "author", obs.Author, "head", obs.HeadSHA, "squash_unsafe_hive", obs.Detail.DCOSquashUnsafeHive) + } + store.MarkNudged(key, obs.HeadSHA, 1, false, now) + return 0, nil + } + body := SignoffAttributionComment(n, stage, nil) + if _, _, err := c.gh.Issues.CreateComment(ctx, obs.Owner, obs.Repo, obs.Number, &gh.IssueComment{Body: gh.Ptr(body)}); err != nil { + c.warn("stage labels: sign-off attribution comment failed", "repo", obs.Display, "pr", obs.Number, "error", err) + return 0, err + } + store.MarkNudged(key, obs.HeadSHA, 1, false, now) + c.info("stage labels: author told to re-sign the head", "repo", obs.Display, "pr", obs.Number, "author", obs.Author, "head", obs.HeadSHA, "squash_unsafe_hive", obs.Detail.DCOSquashUnsafeHive) + return 1, nil +} + +// signoffAttributionRewrite is the body that replaces previous for the +// observation n (hiveSigned commits carry the App's sign-off), and whether +// it differs. The history gains one line only when the core text (asks, +// head) changed; an identical ask on the same head leaves the comment alone. +func signoffAttributionRewrite(previous string, n ContributorNudge, stage stagelabels.Stage, hiveSigned int, now time.Time) (string, bool) { + prevCore, history := splitMarkerHistory(previous) + core := signoffAttributionCore(n, stage) + if strings.TrimRight(core, "\n") == prevCore { + return previous, false + } + history = appendMarkerHistory(history, markerHistoryLine(now, signoffAttributionChange(n.HeadSHA, hiveSigned))) + return renderMarkerHistory(core, history), true +} diff --git a/src/pkg/github/automerge/automerge_signoff_attribution_test.go b/src/pkg/github/automerge/automerge_signoff_attribution_test.go new file mode 100644 index 0000000000..d667527d1e --- /dev/null +++ b/src/pkg/github/automerge/automerge_signoff_attribution_test.go @@ -0,0 +1,177 @@ +package automerge + +// One sign-off attribution note per PR (hivecommons/hive#17066). + +import ( + "context" + "fmt" + "strings" + "testing" + "time" + + gh "github.com/google/go-github/v72/github" + "github.com/hivecommons/hive/pkg/stagelabels" +) + +func TestMarkerHistoryRoundTrip(t *testing.T) { + at := time.Date(2026, 11, 4, 12, 4, 0, 0, time.UTC) + for _, tc := range []struct { + name string + body string + wantCore string + wantHist []string + }{ + {name: "no history", body: "<!-- m -->\nbody\n", wantCore: "<!-- m -->\nbody"}, + { + name: "two lines", + body: renderMarkerHistory("<!-- m -->\nbody", []string{"updated a", "updated b"}), + wantCore: "<!-- m -->\nbody", + wantHist: []string{"updated a", "updated b"}, + }, + { + name: "stray text after the heading is ignored", + body: "<!-- m -->\nbody\n\n" + markerHistoryHeading + "\nnot a bullet\n- kept\n", + wantCore: "<!-- m -->\nbody", + wantHist: []string{"kept"}, + }, + } { + t.Run(tc.name, func(t *testing.T) { + core, hist := splitMarkerHistory(tc.body) + if core != tc.wantCore || strings.Join(hist, "|") != strings.Join(tc.wantHist, "|") { + t.Fatalf("split = %q / %q, want %q / %q", core, hist, tc.wantCore, tc.wantHist) + } + }) + } + var hist []string + for i := 1; i <= markerHistoryCap+2; i++ { + hist = appendMarkerHistory(hist, markerHistoryLine(at.Add(time.Duration(i)*time.Minute), fmt.Sprintf("change %d", i))) + } + if len(hist) != markerHistoryCap || hist[0] != "updated 2026-11-04 12:07 UTC: change 3" || hist[markerHistoryCap-1] != "updated 2026-11-04 12:11 UTC: change 7" { + t.Fatalf("capped history = %q", hist) + } +} + +func TestSignoffAttributionRewrite(t *testing.T) { + now := time.Date(2026, 11, 4, 12, 4, 59, 0, time.UTC) + stage := stagelabels.NeedsAuthor + nudge := func(head string, hiveSigned int) ContributorNudge { + _, asks, _ := nudgeDiagnosis(stagelabels.LaneReasonHiveSignoffAttribution, stageDetail{DCOTotal: hiveSigned, DCOSquashUnsafeHive: hiveSigned}) + return ContributorNudge{Author: "clubanderson", HeadSHA: head, ReviewAsks: asks} + } + first := SignoffAttributionComment(nudge("eb40422ae63967eb7363a3f866e73121c58f2c1b", 8), stage, nil) + legacy := strings.Replace(first, SignoffAttributionMarker, SignoffAttributionMarkerPrefix+" head=eb40422ae63967eb7363a3f866e73121c58f2c1b -->", 1) + fiveDeep := first + for i := 1; i <= markerHistoryCap; i++ { + fiveDeep, _ = signoffAttributionRewrite(fiveDeep, nudge(strings.Repeat(fmt.Sprint(i), 40), 8), stage, 8, now.Add(time.Duration(i)*time.Minute)) + } + for _, tc := range []struct { + name string + previous string + head string + hiveSigned int + wantChanged bool + wantLines int + wantLast string + }{ + {name: "same head and asks leave the note alone", previous: first, head: "eb40422ae63967eb7363a3f866e73121c58f2c1b", hiveSigned: 8}, + { + name: "new head rewrites and records one line", previous: first, head: "2940830726b72f08dff5a1ef6a37bff871b4a7d5", hiveSigned: 20, + wantChanged: true, wantLines: 1, wantLast: "updated 2026-11-04 12:04 UTC: head `2940830726b7`, 20 commits signed off as the hive App", + }, + { + name: "legacy per-head note is adopted under the stable marker", previous: legacy, head: "2940830726b72f08dff5a1ef6a37bff871b4a7d5", hiveSigned: 1, + wantChanged: true, wantLines: 1, wantLast: "updated 2026-11-04 12:04 UTC: head `2940830726b7`, 1 commit signed off as the hive App", + }, + { + name: "history stays capped at five", previous: fiveDeep, head: "dc8ccef2b084b5860f317dacc5037071d78bc1b6", hiveSigned: 30, + wantChanged: true, wantLines: markerHistoryCap, wantLast: "updated 2026-11-04 12:04 UTC: head `dc8ccef2b084`, 30 commits signed off as the hive App", + }, + } { + t.Run(tc.name, func(t *testing.T) { + body, changed := signoffAttributionRewrite(tc.previous, nudge(tc.head, tc.hiveSigned), stage, tc.hiveSigned, now) + if changed != tc.wantChanged { + t.Fatalf("changed = %v, want %v\n%s", changed, tc.wantChanged, body) + } + if !changed { + if body != tc.previous { + t.Fatalf("unchanged rewrite altered the body:\n%s", body) + } + return + } + if !strings.HasPrefix(body, SignoffAttributionMarker+"\n") || strings.Contains(body, " head=") { + t.Fatalf("body not under the stable marker:\n%s", body) + } + if !strings.Contains(body, "Current head: `"+shortSHA(tc.head)+"`.") { + t.Fatalf("body does not name the current head:\n%s", body) + } + _, hist := splitMarkerHistory(body) + if len(hist) != tc.wantLines || hist[len(hist)-1] != tc.wantLast { + t.Fatalf("history = %q, want %d lines ending %q", hist, tc.wantLines, tc.wantLast) + } + if again, changedAgain := signoffAttributionRewrite(body, nudge(tc.head, tc.hiveSigned), stage, tc.hiveSigned, now.Add(time.Hour)); changedAgain || again != body { + t.Fatalf("second pass on the same head rewrote again:\n%s", again) + } + }) + } +} + +// TestApplyStageLabelsSignoffAttributionUpsertsAcrossHeads pins the +// hivecommons/hive#16524 shape: eight pushes used to mean eight notes. Now +// the first head posts, each later head edits the same comment, and a +// repeat sweep on an already-noted head writes nothing. +func TestApplyStageLabelsSignoffAttributionUpsertsAcrossHeads(t *testing.T) { + hiveCommit := stageCommitFixture{ + message: "Add OWNERS file\n\nSigned-off-by: Andy Anderson <280983584+hivecommons-hive[bot]@users.noreply.github.com>", + authorLogin: testHiveAppBotLogin, + authorName: "Andy Anderson", + authorEmail: "280983584+hivecommons-hive[bot]@users.noreply.github.com", + } + api := &stageAPI{labels: map[string]string{}, statefulComments: true, commitDetails: map[int][]stageCommitFixture{16524: {hiveCommit}}} + srv := newStageAPI(t, api) + defer srv.Close() + clock := &contributorLaneClock{at: time.Date(2026, 11, 4, 3, 1, 0, 0, time.UTC)} + e, _, store := newStageEngine(t, srv.URL, clock) + e.stageLabelPolicy = func() StageLabelPolicy { return StageLabelPolicy{Enabled: true, ContributorNudge: true} } + + sweep := func(head string, labels ...string) { + t.Helper() + pr := stagePR(16524, labels...) + pr.Head.SHA = gh.Ptr(head) + pr.User = &gh.User{Login: gh.Ptr("clubanderson")} + e.recordStage(stageLaneTrusted, "acme/widget", "acme", "widget", pr, autoMergeReasonReviewGatePrefix+ReviewGateOutcomeAwaiting, false, nil) + e.noteStageRole("acme", "widget", 16524, stagelabels.RoleTrusted) + if _, err := e.ApplyStageLabels(context.Background()); err != nil { + t.Fatal(err) + } + rec, ok := store.Get(stageKey("acme", "widget", 16524)) + if !ok || rec.Reason != stagelabels.LaneReasonHiveSignoffAttribution || rec.NudgeHead != head { + t.Fatalf("head %s: record %+v ok=%v", head, rec, ok) + } + } + held := []string{"role/trusted", "author/human", stagelabels.DCOLabel, "stage/071-needs-author"} + + sweep("eb40422", "role/trusted") + if len(api.comments) != 1 || len(api.commentEdits) != 0 { + t.Fatalf("first head: comments %q edits %q", api.comments, api.commentEdits) + } + for i, head := range []string{"d61d907", "2940830", "7879a51"} { + clock.at = clock.at.Add(10 * time.Minute) + sweep(head, held...) + if len(api.comments) != 1 || len(api.commentEdits) != i+1 { + t.Fatalf("head %s: comments %q edits %q", head, api.comments, api.commentEdits) + } + last := api.commentEdits[i] + if !strings.HasPrefix(last, SignoffAttributionMarker+"\n") || !strings.Contains(last, "Current head: `"+head+"`.") { + t.Fatalf("head %s: edit not the upserted note:\n%s", head, last) + } + if _, hist := splitMarkerHistory(last); len(hist) != i+1 || !strings.Contains(hist[i], "head `"+head+"`, 1 commit signed off as the hive App") { + t.Fatalf("head %s: history %q", head, hist) + } + } + // Same head, next sweep: nothing is written. + clock.at = clock.at.Add(10 * time.Minute) + sweep("7879a51", held...) + if len(api.comments) != 1 || len(api.commentEdits) != 3 { + t.Fatalf("repeat sweep wrote: comments %q edits %q", api.comments, api.commentEdits) + } +} diff --git a/src/pkg/github/automerge/automerge_stage_labels.go b/src/pkg/github/automerge/automerge_stage_labels.go index 326339f7b8..053dd15905 100644 --- a/src/pkg/github/automerge/automerge_stage_labels.go +++ b/src/pkg/github/automerge/automerge_stage_labels.go @@ -52,8 +52,9 @@ type StageLabelPolicy struct { // ContributorNudge turns the stage-072 nudge comment + relay interrupt // on (governor.labels.stage.contributor_nudge.enabled, default true). ContributorNudge bool - // RenudgeInterval is the delay before the single re-nudge; 0 uses the - // stage's dwell (the stall threshold). + // RenudgeInterval is the delay before the single re-nudge for a reason + // class that persists (auto_merge.nudge_repeat_after, default 72h); + // 0 never re-nudges. RenudgeInterval time.Duration // Adoption turns the stage-074 adoption on // (governor.labels.stage.adoption.enabled, default true): a contributor @@ -1640,7 +1641,8 @@ func (c *Engine) ApplyStageLabels(ctx context.Context) (StageLabelResult, error) } } else if obs.Reason == stagelabels.LaneReasonHiveSignoffAttribution { // A person owns the fix and nothing else will tell them: - // one comment per head with the exact commands. + // one comment per PR with the exact commands, rewritten + // in place on a new head (hivecommons/hive#17066). n, err := c.nudgeSignoffAttribution(ctx, store, key, obs, now) result.Comments += n if err != nil && firstErr == nil { diff --git a/src/pkg/github/automerge/automerge_stage_labels_test.go b/src/pkg/github/automerge/automerge_stage_labels_test.go index 051eee2aea..53899aa25e 100644 --- a/src/pkg/github/automerge/automerge_stage_labels_test.go +++ b/src/pkg/github/automerge/automerge_stage_labels_test.go @@ -2290,7 +2290,7 @@ func TestApplyStageLabelsHiveBotSignoffOnHumanHeadNeedsAuthorWithInstructions(t if len(api.comments) != 1 { t.Fatalf("comments %q", api.comments) } - for _, want := range []string{SignoffAttributionMarkerPrefix + " head=sha -->", "@clubanderson", "`stage/071-needs-author`", "git commit --amend --reset-author -s && git push --force-with-lease", "git config user.email"} { + for _, want := range []string{SignoffAttributionMarker + "\n", "Current head: `sha`.", "@clubanderson", "`stage/071-needs-author`", "git commit --amend --reset-author -s && git push --force-with-lease", "git config user.email"} { if !strings.Contains(api.comments[0], want) { t.Fatalf("comment lacks %q:\n%s", want, api.comments[0]) } diff --git a/src/pkg/github/automerge/automerge_stage_sharedci_test.go b/src/pkg/github/automerge/automerge_stage_sharedci_test.go index 2b331c7936..2afd546fa6 100644 --- a/src/pkg/github/automerge/automerge_stage_sharedci_test.go +++ b/src/pkg/github/automerge/automerge_stage_sharedci_test.go @@ -200,7 +200,7 @@ func TestApplyStageLabelsSharedCIIncidentWithdrawsEarlierNudge(t *testing.T) { t.Fatalf("deferred: edits=%v, want the nudge edited once", api.commentEdits) } edit := api.commentEdits[0] - for _, want := range []string{ContributorNudgeMarkerPrefix + " head=aaa n=1 mode=queued -->", "<!-- hive:contributor-nudge-withdrawn -->", "**Withdrawn:**", "shared CI incident #17003", "once #17003 closes"} { + for _, want := range []string{ContributorNudgeMarkerPrefix + " reason=check-failure head=aaa n=1 mode=queued -->", "<!-- hive:contributor-nudge-withdrawn -->", "**Withdrawn:**", "shared CI incident #17003", "once #17003 closes"} { if !strings.Contains(edit, want) { t.Errorf("withdrawn nudge lacks %q:\n%s", want, edit) } @@ -225,7 +225,10 @@ func TestApplyStageLabelsSharedCIIncidentWithdrawsEarlierNudge(t *testing.T) { open = 0 clock.at = clock.at.Add(time.Hour) observe("stage/050-review-pending", "role/contributor", "author/clanker") - if got := nudgeComments(api); !hasAdded(api, "stage/072-returned-to-contributor") || len(got) != 1 || !strings.Contains(got[0], "n=1 ") { + // One nudge comment per PR: the withdrawn comment is rewritten into + // the fresh first nudge rather than a second one posted. + got := append(nudgeComments(api), api.commentEdits...) + if !hasAdded(api, "stage/072-returned-to-contributor") || len(got) != 1 || !strings.Contains(got[0], "n=1 ") || strings.Contains(got[0], "<!-- hive:contributor-nudge-withdrawn -->") { t.Fatalf("after recovery: added=%v nudges=%v, want 072 and a fresh first nudge", api.added, got) } } diff --git a/src/pkg/github/automerge/automerge_unauthorized.go b/src/pkg/github/automerge/automerge_unauthorized.go index 6313cc1451..a872bf1ff8 100644 --- a/src/pkg/github/automerge/automerge_unauthorized.go +++ b/src/pkg/github/automerge/automerge_unauthorized.go @@ -9,7 +9,7 @@ package automerge // sits at its previous reason (`required-check-missing:<ctx>`) looking like // CI is merely slow while the sweep WARNs every tick. The owner's decision is // to say so plainly instead of widening the App: the lane marks the PR -// `unauthorized` — label hive:unauthorized, one comment per head naming the +// `unauthorized` — label hive:unauthorized, one comment per step naming the // missing permission and the exact human step, reason `unauthorized:<step>` // so the stage engine parks it at 085 and the tracker's pill column shows // the word — and clears all of it in the same tick the step stops being @@ -23,6 +23,7 @@ import ( "fmt" "net/http" "net/url" + "slices" "strconv" "strings" @@ -41,9 +42,9 @@ const ( // label on first use so it does not appear in GitHub's random colour. unauthorizedLabelColor = "6e7781" unauthorizedLabelDescription = "The hive's GitHub App lacks the permission for the next step; a maintainer must take it (see the hive:unauthorized comment)" - // unauthorizedMarkerPrefix tags the one comment per head; the marker - // carries the head and the step so a new push, or a different blocked - // step, gets a fresh note while the same head never gets two. + // unauthorizedMarkerPrefix tags the one comment per (PR, step); a + // different blocked step gets its own note while a new push rewrites + // the existing one with the attempt count. unauthorizedMarkerPrefix = "<!-- hive:unauthorized" // unauthorizedReasonPrefix is the lane reason the stage engine parks at 085. unauthorizedReasonPrefix = prstage.StageReasonUnauthorizedPrefix @@ -108,7 +109,7 @@ func (c *Engine) unauthorizedStep(owner, repo string, number int, headSHA string // markUnauthorized records that the lane's next step for this PR head needs // permission the App lacks. It adds the label when the PR does not wear it, -// posts the comment once per (head, step), logs once per (head, step) at +// upserts the one comment per (PR, step), logs once per (head, step) at // INFO, and returns the lane reason to report. Idempotent across ticks and // restarts: the label and the comment marker on the PR are the durable // state, the in-memory map only quiets the log. Label and comment failures @@ -200,32 +201,164 @@ func (c *Engine) addUnauthorizedLabel(ctx context.Context, owner, repo string, n return err } -// unauthorizedMarker is the first line of the comment for a head and step. -func unauthorizedMarker(headSHA, step string) string { +// unauthorizedMarker is the first line of the comment for a step. One +// comment per PR and step (hivecommons/hive#17066): a new head rewrites it +// with the attempt count and the heads it covers instead of posting again. +func unauthorizedMarker(step string) string { + return unauthorizedMarkerPrefix + " step=" + step + " -->" +} + +// unauthorizedLegacyMarker is the per-head first line comments carried +// before hivecommons/hive#17066; the upsert adopts the latest one. +func unauthorizedLegacyMarker(headSHA, step string) string { return unauthorizedMarkerPrefix + " head=" + strings.ToLower(headSHA) + " step=" + step + " -->" } +// unauthorizedAttemptsPrefix / unauthorizedAttemptsSuffix frame the hidden +// line that records the attempt count and the heads the note covers: +// +// <!-- hive:unauthorized-attempts n=3 heads=aaa,bbb,ccc --> +const ( + unauthorizedAttemptsPrefix = "<!-- hive:unauthorized-attempts n=" + unauthorizedAttemptsSuffix = " -->" + // unauthorizedHeadsCap bounds the heads the note remembers; the + // attempt count keeps growing past it. + unauthorizedHeadsCap = markerHistoryCap +) + +// unauthorizedAttempts is the state an existing note carries. +type unauthorizedAttempts struct { + Count int + Heads []string +} + +// isUnauthorizedCommentFor reports whether body is the hive:unauthorized +// note for step, in either the current or the per-head legacy form. +func isUnauthorizedCommentFor(step string) func(body string) bool { + marker := unauthorizedMarker(step) + suffix := " step=" + step + " -->" + return func(body string) bool { + first, _, _ := strings.Cut(body, "\n") + if first == marker { + return true + } + return strings.HasPrefix(first, unauthorizedMarkerPrefix+" head=") && strings.HasSuffix(first, suffix) + } +} + +// parseUnauthorizedAttempts reads the attempt state from an existing note. +// A legacy per-head note counts as one attempt on the head its marker +// names; a note with no record counts as one attempt on no known head. +func parseUnauthorizedAttempts(body string) unauthorizedAttempts { + for _, line := range strings.Split(body, "\n") { + line = strings.TrimSpace(line) + if !strings.HasPrefix(line, unauthorizedAttemptsPrefix) || !strings.HasSuffix(line, unauthorizedAttemptsSuffix) { + continue + } + fields := strings.Fields(strings.TrimSuffix(strings.TrimPrefix(line, unauthorizedAttemptsPrefix), unauthorizedAttemptsSuffix)) + if len(fields) == 0 { + break + } + n, err := strconv.Atoi(fields[0]) + if err != nil || n < 1 { + n = 1 + } + out := unauthorizedAttempts{Count: n} + for _, f := range fields[1:] { + if heads, ok := strings.CutPrefix(f, "heads="); ok { + for _, h := range strings.Split(heads, ",") { + if h = strings.ToLower(strings.TrimSpace(h)); h != "" { + out.Heads = append(out.Heads, h) + } + } + } + } + return out + } + first, _, _ := strings.Cut(body, "\n") + if rest, ok := strings.CutPrefix(first, unauthorizedMarkerPrefix+" head="); ok { + head, _, _ := strings.Cut(rest, " ") + if head != "" { + return unauthorizedAttempts{Count: 1, Heads: []string{strings.ToLower(head)}} + } + } + return unauthorizedAttempts{Count: 1} +} + +// covers reports whether the note already names headSHA. +func (a unauthorizedAttempts) covers(headSHA string) bool { + return slices.Contains(a.Heads, strings.ToLower(headSHA)) +} + +// next is the state after one more attempt on headSHA: the count grows and +// the head joins the remembered set (oldest dropped past the cap). +func (a unauthorizedAttempts) next(headSHA string) unauthorizedAttempts { + heads := append(slices.Clone(a.Heads), strings.ToLower(headSHA)) + if len(heads) > unauthorizedHeadsCap { + heads = heads[len(heads)-unauthorizedHeadsCap:] + } + return unauthorizedAttempts{Count: a.Count + 1, Heads: heads} +} + +// record renders the hidden attempt line. +func (a unauthorizedAttempts) record() string { + return unauthorizedAttemptsPrefix + strconv.Itoa(a.Count) + " heads=" + strings.Join(a.Heads, ",") + unauthorizedAttemptsSuffix +} + // unauthorizedComment is the comment body: the marker, then the permission -// the App lacks, the step it therefore cannot take, and what a person does. -func unauthorizedComment(headSHA, step, permission, humanAction string) string { - return fmt.Sprintf("%s\nThe hive's GitHub App lacks `%s`, so it cannot %s for head `%s`. %s Hive will resume automatically once the step is done; this label and note clear themselves.", - unauthorizedMarker(headSHA, step), permission, strings.ReplaceAll(step, "-", " "), shortSHA(headSHA), strings.TrimSpace(humanAction)) +// the App lacks, the step it therefore cannot take and what a person does, +// then the attempt record. A first attempt shows no count; later ones say +// how many heads have hit the same block. +func unauthorizedComment(headSHA, step, permission, humanAction string, attempts unauthorizedAttempts) string { + var b strings.Builder + fmt.Fprintf(&b, "%s\nThe hive's GitHub App lacks `%s`, so it cannot %s for head `%s`. %s Hive will resume automatically once the step is done; this label and note clear themselves.", + unauthorizedMarker(step), permission, strings.ReplaceAll(step, "-", " "), shortSHA(headSHA), strings.TrimSpace(humanAction)) + if attempts.Count > 1 { + short := make([]string, 0, len(attempts.Heads)) + for _, h := range attempts.Heads { + short = append(short, "`"+shortSHA(h)+"`") + } + fmt.Fprintf(&b, "\n\n<sub>Attempt %d: the same block hit heads %s.</sub>", attempts.Count, strings.Join(short, ", ")) + } + b.WriteString("\n") + b.WriteString(attempts.record()) + b.WriteString("\n") + return b.String() } -// commentUnauthorized posts the note once per (head, step): an existing -// marker on the PR, or a prior effects claim, suppresses it. +// unauthorizedCommentCoversHead reports whether comments carry the hive's +// note for step naming headSHA: a previous process already learnt the App +// cannot take the step on this head. +func unauthorizedCommentCoversHead(comments []*gh.IssueComment, step, headSHA string) bool { + match := isUnauthorizedCommentFor(step) + for _, comment := range comments { + if comment == nil || !match(comment.GetBody()) { + continue + } + if parseUnauthorizedAttempts(comment.GetBody()).covers(headSHA) { + return true + } + } + return false +} + +// commentUnauthorized keeps one note per (PR, step): a note already naming +// this head is left alone; a note for an earlier head is rewritten in place +// with the attempt count; no note posts one through the effects claim. func (c *Engine) commentUnauthorized(ctx context.Context, owner, repo string, number int, headSHA, step, permission, humanAction string) error { - comments, err := c.listIssueComments(ctx, owner, repo, number) + existing, err := c.findOwnMarkerComment(ctx, owner, repo, number, isUnauthorizedCommentFor(step)) if err != nil { return err } - marker := unauthorizedMarker(headSHA, step) - for _, comment := range comments { - if comment != nil && strings.HasPrefix(comment.GetBody(), marker) { + if existing != nil { + attempts := parseUnauthorizedAttempts(existing.GetBody()) + if attempts.covers(headSHA) { return nil } + return c.editMarkerComment(ctx, owner, repo, existing.GetID(), unauthorizedComment(headSHA, step, permission, humanAction, attempts.next(headSHA))) } - body := unauthorizedComment(headSHA, step, permission, humanAction) + marker := unauthorizedMarker(step) + body := unauthorizedComment(headSHA, step, permission, humanAction, unauthorizedAttempts{Count: 1, Heads: []string{strings.ToLower(headSHA)}}) _, err = effects.Execute(ctx, c.mutation, effects.Claim{ Repo: owner + "/" + repo, Kind: effects.KindIssueComment, diff --git a/src/pkg/github/client.go b/src/pkg/github/client.go index f789b26671..95dd99c15f 100644 --- a/src/pkg/github/client.go +++ b/src/pkg/github/client.go @@ -4,6 +4,7 @@ import ( "context" "errors" "fmt" + "hash/fnv" "log/slog" "net/http" "net/url" @@ -3635,12 +3636,36 @@ func (c *Client) ensureLabel(ctx context.Context, owner, repo, name string) erro Color: gh.Ptr("8250df"), Description: gh.Ptr("Approved by a Hive merger/owner for auto-merge on green CI"), }) - if ghErr, ok := err.(*gh.ErrorResponse); ok && ghErr.Response != nil && ghErr.Response.StatusCode == http.StatusUnprocessableEntity { + if labelAlreadyExists(err) { return nil } return err } +// labelAlreadyExists reports whether a CreateLabel error is GitHub's 422 +// for a label that already exists (a concurrent creator won the race): the +// desired end state holds and the caller may proceed. Any other 422 — "name +// is too long", "name is invalid" — is a real failure: the label was not +// created, the AddLabels that follows will fail too, and swallowing it +// here hid the reason from the dashboard (hivecommons/hive#17037). A 422 +// without an error list is kept as "already exists" for GitHub-compatible +// forges that omit it. +func labelAlreadyExists(err error) bool { + var ghErr *gh.ErrorResponse + if !errors.As(err, &ghErr) || ghErr.Response == nil || ghErr.Response.StatusCode != http.StatusUnprocessableEntity { + return false + } + if len(ghErr.Errors) == 0 { + return true + } + for _, e := range ghErr.Errors { + if e.Code == "already_exists" { + return true + } + } + return false +} + // EnsureIssueLabel creates an issue label if it does not already exist. // origin/* labels are additionally recoloured to the shared family colour. func (c *Client) EnsureIssueLabel(ctx context.Context, repo, name, color, description string) error { @@ -3677,7 +3702,7 @@ func (c *Client) EnsureIssueLabel(ctx context.Context, repo, name, color, descri Color: gh.Ptr(color), Description: gh.Ptr(clampLabelDescription(description)), }) - if ghErr, ok := err.(*gh.ErrorResponse); ok && ghErr.Response != nil && ghErr.Response.StatusCode == http.StatusUnprocessableEntity { + if labelAlreadyExists(err) { return nil } return err @@ -3923,7 +3948,7 @@ func HasHoldLabelWith(labels, extraHoldLabels []string) bool { for _, label := range extraHoldLabels { label = strings.ToLower(strings.TrimSpace(label)) if label != "" { - if strings.HasPrefix(label, "hive-pause/") { + if strings.HasPrefix(label, HiveHoldLabelPrefix) { exactHoldLabels = append(exactHoldLabels, label) } else { holdLabels = append(holdLabels, label) @@ -3948,7 +3973,7 @@ func HasHoldLabelWith(labels, extraHoldLabels []string) bool { } } for _, exact := range exactHoldLabels { - if strings.HasPrefix(exact, "hive-pause/") { + if strings.HasPrefix(exact, HiveHoldLabelPrefix) { if strings.EqualFold(strings.TrimSpace(label), exact) { return true } @@ -3970,6 +3995,32 @@ func isProvenanceLabel(lower string) bool { func isHeld(labels []string) bool { return HasHoldLabel(labels) } +// HiveHoldLabelPrefix is the prefix of the per-hive dashboard hold label +// (CanonicalHiveHoldLabel). Readers that recognise the label by prefix +// (HasHoldLabelWith, IssueStageFor, the duplicate guard) key off it. +const HiveHoldLabelPrefix = "hive-pause/" + +// githubLabelNameMaxLen is GitHub's cap on a label name: POST +// /repos/{o}/{r}/labels answers 422 "name is too long (maximum is 50 +// characters)" above it. +const githubLabelNameMaxLen = 50 + +// hiveHoldLabelHashLen is the hex length of the FNV-1a digest appended to a +// truncated hive id so two hives whose ids share a long prefix never collide +// on the same hold label. +const hiveHoldLabelHashLen = 8 + +// CanonicalHiveHoldLabel is the exact label the dashboard Hold button writes +// and every hold reader matches exactly: hive-pause/<hive-id>, or "hold" for +// a hive without an id. +// +// The result always fits GitHub's 50-character label-name cap. A hosted hive +// id such as hosted-available-oke-11-placeholder-r05x (40 chars) makes the +// plain spelling 51 chars; GitHub rejects creating it with 422, so Hold on +// that hive could never write its label and the dashboard reported "hive +// unavailable" (hivecommons/hive#17037). Over the cap the id is truncated +// and suffixed with a short hash of the full id, so the name stays unique +// per hive and stable across restarts. func CanonicalHiveHoldLabel(hiveID string) string { hiveID = strings.TrimSpace(hiveID) if hiveID == "" { @@ -3978,7 +4029,15 @@ func CanonicalHiveHoldLabel(hiveID string) string { // Avoid "hold" in this hive-scoped spelling: generic hold labels are // substring-matched for backwards compatibility, while this label must be // matched exactly so hive/<id> can stay provenance-only. - return "hive-pause/" + hiveID + label := HiveHoldLabelPrefix + hiveID + if len(label) <= githubLabelNameMaxLen { + return label + } + h := fnv.New32a() + _, _ = h.Write([]byte(hiveID)) + digest := fmt.Sprintf("%08x", h.Sum32())[:hiveHoldLabelHashLen] + keep := githubLabelNameMaxLen - len(HiveHoldLabelPrefix) - 1 - hiveHoldLabelHashLen + return HiveHoldLabelPrefix + strings.TrimRight(hiveID[:keep], "-") + "-" + digest } // HiveProvenanceLabel is the retired hive/<hive-id> label diff --git a/src/pkg/github/client_test.go b/src/pkg/github/client_test.go index d8535534c6..ec08f5a3aa 100644 --- a/src/pkg/github/client_test.go +++ b/src/pkg/github/client_test.go @@ -4,12 +4,14 @@ import ( "context" "encoding/json" "fmt" + "io" "log/slog" "net/http" "net/http/httptest" "net/url" "os" "path/filepath" + "strings" "testing" "time" @@ -722,6 +724,78 @@ func TestHasHoldLabelWithExactCanonicalHivePause(t *testing.T) { } } +// TestCanonicalHiveHoldLabelFitsGitHubCap: GitHub refuses a label name over +// 50 characters with 422, so a hosted hive id (40 chars) made the plain +// hive-pause/<id> spelling impossible to create and Hold failed on every +// item of that hive (hivecommons/hive#17037). The label stays exact, +// unique per id and stable across calls. +func TestCanonicalHiveHoldLabelFitsGitHubCap(t *testing.T) { + long := "hosted-available-oke-11-placeholder-r05x" + if len(HiveHoldLabelPrefix+long) <= githubLabelNameMaxLen { + t.Fatalf("fixture must exceed the cap: %d", len(HiveHoldLabelPrefix+long)) + } + got := CanonicalHiveHoldLabel(long) + if len(got) > githubLabelNameMaxLen { + t.Fatalf("CanonicalHiveHoldLabel(%q) = %q (%d chars), exceeds GitHub's %d", long, got, len(got), githubLabelNameMaxLen) + } + if !strings.HasPrefix(got, HiveHoldLabelPrefix+"hosted-available-oke-11-") { + t.Fatalf("truncated label %q should keep the readable id prefix", got) + } + if got != CanonicalHiveHoldLabel(" "+long+" ") { + t.Fatal("label must be stable for the same id") + } + if other := CanonicalHiveHoldLabel(long[:len(long)-1] + "y"); other == got { + t.Fatalf("two ids with a shared long prefix collapsed onto %q", got) + } + if !HasHoldLabelWith([]string{got}, []string{got}) { + t.Fatal("the shortened label must still read as an exact hive hold") + } + if short := CanonicalHiveHoldLabel("h1"); short != "hive-pause/h1" { + t.Fatalf("a short id is unchanged: %q", short) + } + if hyph := CanonicalHiveHoldLabel("abcdefghij-abcdefghij-abcdefghij-xxxxxxxxxx"); strings.Contains(hyph, "--") { + t.Fatalf("a truncation ending on '-' must not double the separator: %q", hyph) + } +} + +// TestEnsureIssueLabelReturnsNonAlreadyExists422: only GitHub's +// already_exists 422 means the label is there; a "name is too long" 422 +// must come back to the caller, not be swallowed as success +// (hivecommons/hive#17037). +func TestEnsureIssueLabelReturnsNonAlreadyExists422(t *testing.T) { + var creates int + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + switch { + case r.Method == http.MethodGet && strings.Contains(r.URL.Path, "/labels/"): + http.NotFound(w, r) + case r.Method == http.MethodPost && strings.HasSuffix(r.URL.Path, "/labels"): + creates++ + var body struct{ Name string } + _ = json.NewDecoder(r.Body).Decode(&body) + w.WriteHeader(http.StatusUnprocessableEntity) + if strings.HasPrefix(body.Name, "dup") { + _, _ = io.WriteString(w, `{"message":"Validation Failed","errors":[{"resource":"Label","code":"already_exists","field":"name"}]}`) + return + } + _, _ = io.WriteString(w, `{"message":"Validation Failed","errors":[{"resource":"Label","code":"custom","field":"name","message":"name is too long (maximum is 50 characters)"}]}`) + default: + http.NotFound(w, r) + } + })) + defer srv.Close() + c := NewClient("token", "o", []string{"r"}, slog.Default(), srv.URL) + if err := c.EnsureIssueLabel(context.Background(), "o/r", "dup-label", "8250df", "d"); err != nil { + t.Fatalf("already_exists must be success, got %v", err) + } + err := c.EnsureIssueLabel(context.Background(), "o/r", "hive-pause/hosted-available-oke-11-placeholder-r05x", "8250df", "d") + if err == nil || !strings.Contains(err.Error(), "name is too long") { + t.Fatalf("an over-long name must surface GitHub's reason, got %v", err) + } + if creates != 2 { + t.Fatalf("creates = %d, want 2", creates) + } +} + func TestIsExempt(t *testing.T) { t.Run("permanent labels always exempt", func(t *testing.T) { c := &Client{} diff --git a/src/pkg/github/issue_blocked_test.go b/src/pkg/github/issue_blocked_test.go index a1c15a6175..091889b7d3 100644 --- a/src/pkg/github/issue_blocked_test.go +++ b/src/pkg/github/issue_blocked_test.go @@ -346,15 +346,21 @@ func TestReviewBacklogFilesIntroducedAndTouchedItemsBlockedOnItsPR(t *testing.T) c.SetReviewBacklogRouting(func() ReviewBacklogRouting { return ReviewBacklogRouting{ Severity: config.ReviewSeverityConfig{BlockAt: "P2"}, - Backlog: config.ReviewBacklogConfig{Destination: config.ReviewBacklogGitHubIssue, Labels: []string{"nit", "help wanted"}}, + Backlog: config.ReviewBacklogConfig{Destination: config.ReviewBacklogGitHubIssue, Labels: []string{"nit", "help wanted"}, MinSeverity: "P3"}, } }) recs := captureAudit(c) - report := routingReport(t, 5, "abc", + // Two passes: findings from one pass that share a perspective collapse + // into one item (hivecommons/hive#17065), and this test wants each + // finding's own blocked note. + for _, finding := range []map[string]any{ nit("only-in-pr", "low", "pkg/new.go", 3, "introduced by the PR"), - nit("on-base", "low", "pkg/old.go", 4, "already there")) - if err := c.fileOutOfScopeReviewBacklog(context.Background(), ReviewRequest{Repo: "o/r", Number: 5, Agent: "reviewer", Report: report}, time.Now()); err != nil { - t.Fatal(err) + nit("on-base", "low", "pkg/old.go", 4, "already there"), + } { + report := routingReport(t, 5, "abc", finding) + if err := c.fileOutOfScopeReviewBacklog(context.Background(), ReviewRequest{Repo: "o/r", Number: 5, Agent: "reviewer", Report: report}, time.Now()); err != nil { + t.Fatal(err) + } } if len(issues) != 2 { t.Fatalf("issues = %d, want 2", len(issues)) diff --git a/src/pkg/github/issue_request_watcher.go b/src/pkg/github/issue_request_watcher.go index 85795ba95c..274e030d8b 100644 --- a/src/pkg/github/issue_request_watcher.go +++ b/src/pkg/github/issue_request_watcher.go @@ -790,6 +790,15 @@ func (c *Client) handleOneIssueRequest(ctx context.Context, path string, nowFn f if err == nil && !created { c.noteCommentSuppressed() } + } else if note, ok := OriginFooterNote(commentBody); ok && req.BlockedOnPR == 0 { + // Free text whose only marker is the identity footer is an + // agent note: one upserted comment per item, or a status + // section in quiet mode (hivecommons/hive#17067). + var created bool + created, err = c.postOriginNote(ctx, req.Repo, req.Number, req.Agent, note, nowFn()) + if err == nil && !created { + c.noteCommentSuppressed() + } } else { err = c.CreateIssueCommentBudgeted(ctx, req.Repo, req.Number, commentBody) } diff --git a/src/pkg/github/origin_notes.go b/src/pkg/github/origin_notes.go new file mode 100644 index 0000000000..81ccf4f02b --- /dev/null +++ b/src/pkg/github/origin_notes.go @@ -0,0 +1,78 @@ +package github + +import ( + "context" + "strings" + "time" + + "github.com/hivecommons/hive/pkg/prstatus" +) + +// OriginNotesMarker tags the one comment per item that collects an agent's +// free-text notes — the relayed `gh pr comment` bodies whose only marker +// is the identity footer's `<!-- hive:origin … -->` (hivecommons/hive#17067). +// Each new note edits that comment in place instead of posting another. +const OriginNotesMarker = "<!-- hive:origin-notes -->" + +// originNotesHeading opens the collected-notes comment. +const originNotesHeading = "**Agent notes** — updated in place; edits do not notify. Full history is in the Activity Monitor." + +// originNotesKeep caps how many notes the collected comment retains; the +// oldest drop off first. +const originNotesKeep = 10 + +// originNoteStatusKey is the status-comment section the notes fold into in +// quiet notification mode. +const originNoteStatusKey = prstatus.KeyAgentNotePrefix + "origin" + +// originNoteEntry renders one note as a list item. Continuation lines are +// indented so a multi-paragraph note stays inside its bullet. +func originNoteEntry(agent, note string, now time.Time) string { + head := "- " + if agent = strings.TrimSpace(agent); agent != "" { + head += "**" + agent + "** " + } + head += "(" + now.UTC().Format("2006-01-02 15:04 UTC") + "): " + lines := strings.Split(strings.TrimSpace(note), "\n") + for i := 1; i < len(lines); i++ { + lines[i] = " " + lines[i] + } + return head + strings.Join(lines, "\n") +} + +// renderOriginNotes returns the collected-notes comment body with entry +// appended to the notes already in previous (or a fresh comment when +// previous is empty), keeping at most originNotesKeep entries. +func renderOriginNotes(previous, entry string) string { + var entries []string + if i := strings.Index(previous, "\n- "); i >= 0 { + for _, block := range strings.Split(previous[i+1:], "\n- ") { + block = strings.TrimRight(block, "\n") + if strings.TrimSpace(block) == "" { + continue + } + entries = append(entries, "- "+strings.TrimPrefix(block, "- ")) + } + } + entries = append(entries, entry) + if len(entries) > originNotesKeep { + entries = entries[len(entries)-originNotesKeep:] + } + return OriginNotesMarker + "\n" + originNotesHeading + "\n\n" + strings.Join(entries, "\n") +} + +// postOriginNote delivers an agent's free-text note without a new +// notification per note: in quiet mode it is the agent-note section of the +// item's status comment; otherwise it is appended to the one +// OriginNotesMarker comment on the item, created on first use. Reports +// whether a comment was created. +func (c *Client) postOriginNote(ctx context.Context, repo string, number int, agent, note string, now time.Time) (bool, error) { + entry := originNoteEntry(agent, note, now) + if c.notificationsQuiet() { + return c.UpsertPRStatusSection(ctx, repo, number, originNoteStatusKey, entry) + } + res, err := c.EditIssueMarkerComment(ctx, repo, number, OriginNotesMarker, func(previous string) string { + return renderOriginNotes(previous, entry) + }) + return res.Created, err +} diff --git a/src/pkg/github/origin_notes_test.go b/src/pkg/github/origin_notes_test.go new file mode 100644 index 0000000000..3e92674dcd --- /dev/null +++ b/src/pkg/github/origin_notes_test.go @@ -0,0 +1,136 @@ +package github + +import ( + "context" + "strings" + "testing" + "time" + + "github.com/hivecommons/hive/pkg/prstatus" +) + +const testOriginFooter = "\n\n---\n🐝 **Hive Agent**: `a1` | **Instance:** `test-hive` | **SHA:** `abc1234`\n<!-- hive:origin hive=test-hive at=2026-11-07T10:00:00Z -->" + +// The footer the wrapper emits for a hive without an instance id: no origin marker. +const testBareFooter = "\n\n---\n🐝 **Hive Agent**: `a1` | **SHA:** `abc1234`" + +// Only a free-text body whose sole marker is the identity footer's origin +// marker is an agent note; anything else keeps its own path. +func TestOriginFooterNote(t *testing.T) { + tests := []struct { + name string + body string + want string + ok bool + }{ + {"plain note with footer", "Looked at this; the flake is in the retry loop." + testOriginFooter, "Looked at this; the flake is in the retry loop.", true}, + {"multi-line note", "First line.\n\nSecond paragraph." + testOriginFooter, "First line.\n\nSecond paragraph.", true}, + {"crlf body", strings.ReplaceAll("Note here."+testOriginFooter, "\n", "\r\n"), "Note here.", true}, + {"no footer", "Just a comment.", "", false}, + {"footer only", testOriginFooter, "", false}, + {"footer without origin marker", "Note." + testBareFooter, "", false}, + {"origin marker without footer", "Note.\n\n<!-- hive:origin hive=h at=2026-11-07T10:00:00Z -->", "", false}, + {"verification marker present", "Verified.\n<!-- hive-verified -->" + testOriginFooter, "", false}, + {"status marker present", prstatus.Marker + "\nstate" + testOriginFooter, "", false}, + {"footer not at end", "x" + testOriginFooter + "\n\ntrailing text", "", false}, + } + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + got, ok := OriginFooterNote(tc.body) + if ok != tc.ok || got != tc.want { + t.Fatalf("OriginFooterNote() = %q, %v; want %q, %v", got, ok, tc.want, tc.ok) + } + }) + } +} + +// Notes accumulate under the one marker comment, oldest dropping past the cap. +func TestRenderOriginNotes(t *testing.T) { + now := time.Date(2026, 11, 7, 10, 0, 0, 0, time.UTC) + tests := []struct { + name string + previous string + entry string + wantCount int + wantFirst string + wantAbsent string + }{ + {"fresh", "", originNoteEntry("a1", "first", now), 1, "**a1** (2026-11-07 10:00 UTC): first", ""}, + {"append", renderOriginNotes("", originNoteEntry("a1", "first", now)), originNoteEntry("a2", "second\nmore", now), 2, "first", ""}, + {"cap", func() string { + body := "" + for i := 0; i < originNotesKeep; i++ { + body = renderOriginNotes(body, originNoteEntry("a", strings.Repeat("x", i+1), now)) + } + return body + }(), originNoteEntry("a", "newest", now), originNotesKeep, "xx", "): x\n"}, + } + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + got := renderOriginNotes(tc.previous, tc.entry) + if !strings.HasPrefix(got, OriginNotesMarker+"\n") { + t.Fatalf("missing marker:\n%s", got) + } + if n := strings.Count(got, "\n- "); n != tc.wantCount { + t.Fatalf("entries = %d, want %d:\n%s", n, tc.wantCount, got) + } + if !strings.Contains(got, tc.wantFirst) { + t.Fatalf("missing %q:\n%s", tc.wantFirst, got) + } + if tc.wantAbsent != "" && strings.Contains(got, tc.wantAbsent) { + t.Fatalf("oldest entry should have dropped:\n%s", got) + } + if !strings.HasSuffix(got, tc.entry) { + t.Fatalf("newest entry not last:\n%s", got) + } + }) + } +} + +// Normal mode: the first note creates the marker comment, the next edits it. +// Quiet mode: notes are a section of the status comment. +func TestPostOriginNoteOneCommentPerItem(t *testing.T) { + ctx := context.Background() + now := time.Date(2026, 11, 7, 10, 0, 0, 0, time.UTC) + tests := []struct { + name string + quiet bool + wantCreates int + wantEdits int + wantMarker string + }{ + {"normal mode edits the notes comment", false, 1, 2, OriginNotesMarker}, + {"quiet mode folds into status", true, 1, 2, prstatus.Marker}, + } + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + s := &statusCommentServer{} + c := testClient(t, s.start(t).URL) + c.SetAppBotLogin("hive-app[bot]") + c.SetNotificationsQuiet(func() bool { return tc.quiet }) + for i, note := range []string{"first", "second", "third"} { + created, err := c.postOriginNote(ctx, "o/r", 7, "agent-1", note, now.Add(time.Duration(i)*time.Minute)) + if err != nil { + t.Fatal(err) + } + if created != (i == 0) { + t.Fatalf("note %d: created=%v", i, created) + } + } + if s.creates != tc.wantCreates || s.edits != tc.wantEdits { + t.Fatalf("creates=%d edits=%d, want %d/%d", s.creates, s.edits, tc.wantCreates, tc.wantEdits) + } + body, _ := s.comments[0]["body"].(string) + if !strings.Contains(body, tc.wantMarker) || !strings.Contains(body, "third") { + t.Fatalf("comment body:\n%s", body) + } + if tc.quiet { + if sec, ok := prstatus.Get(body, originNoteStatusKey); !ok || !strings.Contains(sec, "third") { + t.Fatalf("status section = %q, %v", sec, ok) + } + } else if !strings.Contains(body, "first") { + t.Fatalf("earlier note dropped:\n%s", body) + } + }) + } +} diff --git a/src/pkg/github/review_backlog.go b/src/pkg/github/review_backlog.go index dc4d7feae5..3b25a205a2 100644 --- a/src/pkg/github/review_backlog.go +++ b/src/pkg/github/review_backlog.go @@ -43,8 +43,10 @@ type reviewBacklogLedger struct { // Fingerprints maps repo → finding fingerprint → filed item, so a // finding re-raised on any PR updates its existing item. Fingerprints map[string]map[string]reviewBacklogFingerprintRecord `json:"fingerprints,omitempty"` - // PRDailyCount counts items filed or updated per "<pr key>@<UTC day>". - PRDailyCount map[string]int `json:"pr_daily_count,omitempty"` + // PRItemCount counts items filed or re-raised per "<repo>#<pr>" over the + // PR's lifetime (hivecommons/hive#17065); the per-day counter it replaces + // let a long-lived PR file max_per_pr_per_day items every UTC day. + PRItemCount map[string]int `json:"pr_item_count,omitempty"` // SplitKeys maps a folded finding's link-marker key to every closed // host issue it has been split out of (hivecommons/hive#13914). A // finding can be split more than once when the split lands in an open @@ -72,7 +74,7 @@ type reviewBacklogLedger struct { // the issue each call creates, so releasing it between the call and the // save would reopen the lost-update window. The cost is that the run // loop's split sweep waits while a review's backlog filing is in flight, -// bounded by the review's per-PR daily cap and the sweep's per-pass cap. +// bounded by the review's per-PR cap and the sweep's per-pass cap. var reviewBacklogLedgerMu sync.Mutex // splitFrom reports whether key was already split out of host. @@ -134,7 +136,7 @@ func newReviewBacklogLedger() *reviewBacklogLedger { SummaryCommented: map[string]bool{}, PRFiledIssueCount: map[string]int{}, Fingerprints: map[string]map[string]reviewBacklogFingerprintRecord{}, - PRDailyCount: map[string]int{}, + PRItemCount: map[string]int{}, SplitKeys: map[string][]int{}, PRFindings: map[string][]reviewBacklogPRFinding{}, StillPresentHeads: map[string]string{}, @@ -168,8 +170,8 @@ func loadReviewBacklog(path string) (*reviewBacklogLedger, error) { if l.Fingerprints == nil { l.Fingerprints = map[string]map[string]reviewBacklogFingerprintRecord{} } - if l.PRDailyCount == nil { - l.PRDailyCount = map[string]int{} + if l.PRItemCount == nil { + l.PRItemCount = map[string]int{} } if l.SplitKeys == nil { l.SplitKeys = map[string][]int{} @@ -209,8 +211,13 @@ func (l *reviewBacklogLedger) save(path string, now time.Time) error { // review.backlog destination (hivecommons/hive#11089) and are de-duplicated // per repo by ReviewFindingFingerprint: a finding another PR already filed is // appended to the existing item instead of filed again. Every item filed or -// updated counts toward the per-PR daily cap, and each pass that wrote -// anything leaves one batch audit entry. +// re-raised counts toward the per-PR lifetime cap (review.backlog.max_per_pr), +// and each pass that wrote anything leaves one batch audit entry. +// +// Findings below review.backlog.min_severity (hivecommons/hive#17065) are +// never items: they are listed in one upserted Follow-ups comment on the PR. +// New findings from one pass that share a perspective and scope are +// collapsed into a single item with a checklist. // // Findings in files changed by the PR or missing on its base are parked on // that PR; findings in untouched files can be worked immediately (#14473). @@ -250,10 +257,10 @@ func (c *Client) fileReviewBacklog(ctx context.Context, req ReviewRequest, now t return err } prKey := ReviewLinkKey(req.Repo, req.Number) - dayKey := reviewBacklogDayKey(prKey, now) - dailyCap := reviewBacklogDailyCap(routing, routed, outOfScopeCap) - dailyRemaining := dailyCap - ledger.PRDailyCount[dayKey] + prCap := reviewBacklogPRCap(routing, routed, outOfScopeCap) + remaining := prCap - ledger.PRItemCount[prKey] outOfScopeRemaining := outOfScopeCap - ledger.PRFiledIssueCount[prKey] + minSeverity := routing.Backlog.EffectiveMinSeverity() sink, labels := c.reviewBacklogTarget(routing) destination := sink.Destination() headSHA := reqHeadSHAFromReports(reports) @@ -266,6 +273,12 @@ func (c *Client) fileReviewBacklog(ctx context.Context, req ReviewRequest, now t // onto an existing item, or already tracked for this PR — for the // decided review's Follow-ups section. var listed []reviewBacklogFiled + // held is every finding below review.backlog.min_severity: listed in + // the PR's Follow-ups comment, never an item. + var held []reviewBacklogHeldFinding + // pending is every finding that needs a new item; filed after the loop + // so findings sharing a perspective collapse into one item. + var pending []reviewBacklogPending var updated, capped int for _, report := range reports { for _, finding := range report.Findings { @@ -279,17 +292,20 @@ func (c *Client) fileReviewBacklog(ctx context.Context, req ReviewRequest, now t if !outOfScope && (!belowLine || !ReviewFindingBelowLine(finding, routing.Severity.BlockAt)) { continue } + if ReviewFindingBelowMinSeverity(finding, minSeverity) { + held = append(held, reviewBacklogHeldFinding{Perspective: report.Perspective, Finding: finding}) + continue + } key := reviewBacklogKey(req.Repo, req.Number, report.Perspective, finding) if prev, ok := ledger.Items[key]; ok { listed = append(listed, reviewBacklogFiled{number: prev.IssueNumber, key: prev.ItemKey, url: prev.IssueURL, title: reviewBacklogIssueTitle(report.Perspective, finding), status: reviewBacklogListedTracked}) // The same perspective reporting it again at a new head - // leaves the once-per-head "still present" note. - if tracked, isTracked := ledger.prFinding(req.Repo, req.Number, finding); isTracked && dailyRemaining > 0 && ledger.stillPresentDue(req.Repo, req.Number, tracked.ref(), headSHA) { + // leaves the once-per-head "still present" note; bounded + // per head, it does not spend the per-PR cap. + if tracked, isTracked := ledger.prFinding(req.Repo, req.Number, finding); isTracked && ledger.stillPresentDue(req.Repo, req.Number, tracked.ref(), headSHA) { if err := sink.AppendToItem(ctx, req.Repo, tracked.ref(), reviewBacklogStillPresentComment(headSHA, []review.Perspective{report.Perspective})); err != nil { return err } - ledger.PRDailyCount[dayKey]++ - dailyRemaining-- } continue } @@ -323,12 +339,10 @@ func (c *Client) fileReviewBacklog(ctx context.Context, req ReviewRequest, now t record.IssueNumber, record.IssueURL, record.ItemKey = tracked.ItemNumber, tracked.ItemURL, tracked.ItemKey ledger.Items[key] = record listed = append(listed, reviewBacklogFiled{number: tracked.ItemNumber, key: tracked.ItemKey, url: tracked.ItemURL, title: reviewBacklogIssueTitle(report.Perspective, finding), status: reviewBacklogListedTracked}) - if dailyRemaining > 0 && ledger.stillPresentDue(req.Repo, req.Number, tracked.ref(), headSHA) { + if ledger.stillPresentDue(req.Repo, req.Number, tracked.ref(), headSHA) { if err := sink.AppendToItem(ctx, req.Repo, tracked.ref(), reviewBacklogStillPresentComment(headSHA, []review.Perspective{report.Perspective})); err != nil { return err } - ledger.PRDailyCount[dayKey]++ - dailyRemaining-- } continue } @@ -357,7 +371,7 @@ func (c *Client) fileReviewBacklog(ctx context.Context, req ReviewRequest, now t listed = append(listed, reviewBacklogFiled{number: known.ItemNumber, key: known.ItemKey, url: known.ItemURL, title: reviewBacklogIssueTitle(report.Perspective, finding), status: reviewBacklogListedTracked}) continue } - if dailyRemaining <= 0 { + if remaining <= 0 { capped++ continue } @@ -369,123 +383,52 @@ func (c *Client) fileReviewBacklog(ctx context.Context, req ReviewRequest, now t ledger.setFingerprint(req.Repo, fp, known) ledger.Items[key] = record ledger.addPRFinding(req.Repo, req.Number, finding, known.ref(), headSHA) - ledger.PRDailyCount[dayKey]++ - dailyRemaining-- + ledger.PRItemCount[prKey]++ + remaining-- updated++ listed = append(listed, reviewBacklogFiled{number: known.ItemNumber, key: known.ItemKey, url: known.ItemURL, title: reviewBacklogIssueTitle(report.Perspective, finding), status: reviewBacklogListedUpdated}) continue } - if dailyRemaining <= 0 || (outOfScope && outOfScopeRemaining <= 0) { - capped++ - continue - } - title := reviewBacklogIssueTitle(report.Perspective, finding) - missing := baseProbe.FileMissingOnBase(ctx, finding.File) - touched, filesKnown := false, true - if !missing { - touched, filesKnown = changedFiles(ctx, finding.File) - } - blocked := missing || touched || !filesKnown - itemLabels := labels - if blocked { - itemLabels = blockedBacklogLabels(labels) - } - body := c.reviewBacklogIssueBody(req, report.Perspective, finding, headSHA, routing.Severity.BlockAt, fp) - if missing { - body = blockedBacklogNote(req.Repo, req.Number, finding.File, baseProbe.BaseRef(ctx)) + body - } else if blocked { - note := blockedOnReviewedPRNote(req.Repo, req.Number) - if !filesKnown { - note = strings.Replace(note, "is about code that PR is changing", "could not be checked against the PR's changed files", 1) - } - body = note + body - } - ref, err := sink.CreateItem(ctx, ReviewBacklogItem{ - Repo: req.Repo, - Title: title, - Body: body, - Labels: itemLabels, - Perspective: report.Perspective, - Finding: finding, - }) - if err != nil && ref.ID == "" { + pending = append(pending, reviewBacklogPending{perspective: report.Perspective, finding: finding, key: key, fp: fp, record: record, outOfScope: outOfScope}) + } + } + for _, group := range groupReviewBacklogPending(pending) { + if remaining <= 0 || (group[0].outOfScope && outOfScopeRemaining <= 0) { + capped += len(group) + continue + } + filed, ok, createErr := c.createReviewBacklogGroup(ctx, reviewBacklogGroupInput{ + req: req, ledger: ledger, sink: sink, labels: labels, destination: destination, + headSHA: headSHA, blockAt: routing.Severity.BlockAt, baseProbe: baseProbe, changedFiles: changedFiles, + group: group, now: now, + }) + if createErr != nil && !ok { + return createErr + } + if !ok { + continue + } + if group[0].outOfScope { + ledger.PRFiledIssueCount[prKey]++ + outOfScopeRemaining-- + } + ledger.PRItemCount[prKey]++ + remaining-- + filedIssues = append(filedIssues, filed) + listed = append(listed, filed) + if createErr != nil { + // The item exists but a follow-up step (Projects column, + // Jira status) failed: keep the ledger entry so a retry + // does not file it twice. + if err := ledger.save("", now); err != nil { return err } - createErr := err - if ref.ID == "" { - continue - } - if ref.Reused && createErr == nil { - // hivecommons/hive#13604: the comment must carry the whole - // finding or it is lost when the twin closes. - if err := sink.AppendToItem(ctx, req.Repo, ref, c.reviewBacklogFoldedComment(req, report.Perspective, finding, headSHA, fp, key)); err != nil { - return err - } - } - if !ref.Reused && ref.SameFileAs > 0 && createErr == nil { - // hivecommons/hive#13906: the item exists, so a failed - // cross-link must not fail the pass and re-file it. - if err := sink.AppendToItem(ctx, req.Repo, ref, reviewBacklogSameFileComment(finding, ref.SameFileAs, ref.SameFilePath)); err != nil { - c.logger.Warn("review backlog: same-file cross-link comment failed", - slog.String("repo", req.Repo), slog.String("item", ref.Key), - slog.Int("same_file_as", ref.SameFileAs), slog.String("error", err.Error())) - } - } - if ref.Number > 0 { - c.recordWriteAudit(AuditActionReviewBacklogIssueFiled, hiveWriteMeta(), - WriteTarget{Repo: req.Repo, Number: ref.Number}, - "pr", strconv.Itoa(req.Number), - "perspective", string(report.Perspective), - "reused", strconv.FormatBool(ref.Reused), - "blocked", strconv.FormatBool(blocked), - "destination", destination, - "review_agent", req.Agent) - } - record.IssueNumber, record.IssueURL, record.ItemKey = ref.Number, ref.URL, ref.Key - ledger.Items[key] = record - ledger.addPRFinding(req.Repo, req.Number, finding, ref, headSHA) - fpRecord := reviewBacklogFingerprintRecord{ - Destination: destination, - ItemID: ref.ID, - ItemKey: ref.Key, - ItemNumber: ref.Number, - ItemURL: ref.URL, - PRs: []int{req.Number}, - FiledAt: now.UTC(), - UpdatedAt: now.UTC(), - File: normaliseFingerprintPath(finding.File), - Title: strings.TrimSpace(finding.Title), - } - if !ref.Reused { - // A filing folded into an open twin keeps the twin's own - // state (#13364). Keep source provenance for new items, - // but only park findings related to the PR. - fpRecord.BlockedOnPR = req.Number - if blocked { - fpRecord.BlockState = reviewBacklogBlockBlocked - } - } - ledger.setFingerprint(req.Repo, fp, fpRecord) - if outOfScope { - ledger.PRFiledIssueCount[prKey]++ - outOfScopeRemaining-- - } - ledger.PRDailyCount[dayKey]++ - dailyRemaining-- - filed := reviewBacklogFiled{number: ref.Number, key: ref.Key, url: ref.URL, title: title, folded: ref.Reused, status: reviewBacklogListedFiled} - filedIssues = append(filedIssues, filed) - listed = append(listed, filed) - if createErr != nil { - // The item exists but a follow-up step (Projects column, - // Jira status) failed: keep the ledger entry so a retry - // does not file it twice. - if err := ledger.save("", now); err != nil { - return err - } - return createErr - } + return createErr } } + if len(held) > 0 { + c.upsertReviewFollowUpsComment(ctx, req, held, minSeverity) + } if len(filedIssues) > 0 || updated > 0 { c.recordWriteAudit(AuditActionReviewBacklogBatchRouted, hiveWriteMeta(), WriteTarget{Repo: req.Repo, Number: req.Number}, @@ -495,7 +438,6 @@ func (c *Client) fileReviewBacklog(ctx context.Context, req ReviewRequest, now t "capped", strconv.Itoa(capped), "review_agent", req.Agent) } - ledger.pruneDailyCounts(now) if decided { // Heads mode (#13833): list what this head's findings map to in the // decided review itself, every head, instead of a once-per-PR @@ -518,7 +460,7 @@ func (c *Client) fileReviewBacklog(ctx context.Context, req ReviewRequest, now t return filedIssues[i].key < filedIssues[j].key }) if !ledger.SummaryCommented[prKey] { - if _, err := c.PostNoteOrFold(ctx, req.Repo, req.Number, prstatus.KeyReviewBacklog, reviewBacklogSummaryComment(filedIssues, dailyCap)); err != nil { + if _, err := c.PostNoteOrFold(ctx, req.Repo, req.Number, prstatus.KeyReviewBacklog, reviewBacklogSummaryComment(filedIssues, prCap)); err != nil { return err } c.recordWriteAudit(AuditActionReviewBacklogSummaryPosted, hiveWriteMeta(), @@ -634,7 +576,7 @@ func reviewBacklogSummaryComment(issues []reviewBacklogFiled, cap int) string { fmt.Fprintf(&b, "- %s — %s\n", ref, issue.title) } } - fmt.Fprintf(&b, "\nCap: %d backlog item(s) per PR per day.", cap) + fmt.Fprintf(&b, "\nCap: %d backlog item(s) per PR.", cap) return b.String() } diff --git a/src/pkg/github/review_backlog_collapse.go b/src/pkg/github/review_backlog_collapse.go new file mode 100644 index 0000000000..2e2254cbe9 --- /dev/null +++ b/src/pkg/github/review_backlog_collapse.go @@ -0,0 +1,334 @@ +package github + +import ( + "context" + "fmt" + "log/slog" + "sort" + "strconv" + "strings" + "time" + + "github.com/hivecommons/hive/pkg/outputschema" + "github.com/hivecommons/hive/pkg/review" +) + +// reviewFollowUpsCommentMarker tags the one PR comment that lists findings +// held below review.backlog.min_severity (hivecommons/hive#17065). It is +// edited in place on every pass, like the claim ledger, so a PR carries one +// such comment however many reviews it gets. +const reviewFollowUpsCommentMarker = "<!-- hive:review-followups-comment v1 -->" + +// reviewFollowUpsSummaryMaxLen bounds the one-line summary quoted per held +// finding in the Follow-ups comment. +const reviewFollowUpsSummaryMaxLen = 200 + +// reviewBacklogHeldFinding is a finding below review.backlog.min_severity: +// listed in the PR's Follow-ups comment, never filed as an item. +type reviewBacklogHeldFinding struct { + Perspective review.Perspective + Finding outputschema.Finding +} + +// reviewBacklogPending is a finding that needs a new backlog item, held +// back until the whole report is read so findings sharing a perspective +// and scope are filed as one item. +type reviewBacklogPending struct { + perspective review.Perspective + finding outputschema.Finding + key string + fp string + record reviewBacklogRecord + outOfScope bool +} + +// groupReviewBacklogPending groups pending findings by family — perspective +// and scope — in first-seen order, keeping each group's findings in report +// order. +func groupReviewBacklogPending(pending []reviewBacklogPending) [][]reviewBacklogPending { + var order []string + groups := map[string][]reviewBacklogPending{} + for _, p := range pending { + k := string(p.perspective) + "\x00" + strconv.FormatBool(p.outOfScope) + if _, ok := groups[k]; !ok { + order = append(order, k) + } + groups[k] = append(groups[k], p) + } + out := make([][]reviewBacklogPending, 0, len(order)) + for _, k := range order { + out = append(out, groups[k]) + } + return out +} + +type reviewBacklogGroupInput struct { + req ReviewRequest + ledger *reviewBacklogLedger + sink ReviewBacklogSink + labels []string + destination string + headSHA string + blockAt string + baseProbe *reviewBacklogBaseProbe + changedFiles func(context.Context, string) (bool, bool) + group []reviewBacklogPending + now time.Time +} + +// createReviewBacklogGroup files one backlog item for group: the finding's +// own item when the group has one, else one collapsed item with a checklist +// (hivecommons/hive#17065). Every finding in the group is recorded in the +// ledger against the item, so a later head or PR raising any of them is +// de-duplicated as before. ok is false when nothing was filed; a non-nil +// error with ok true means the item exists but a follow-up step failed. +func (c *Client) createReviewBacklogGroup(ctx context.Context, in reviewBacklogGroupInput) (reviewBacklogFiled, bool, error) { + req, ledger, sink, group := in.req, in.ledger, in.sink, in.group + if len(group) == 0 { + return reviewBacklogFiled{}, false, nil + } + first := group[0] + perspective := first.perspective + var missingFile string + blocked, filesKnown := false, true + for _, p := range group { + if in.baseProbe.FileMissingOnBase(ctx, p.finding.File) { + blocked = true + if missingFile == "" { + missingFile = p.finding.File + } + continue + } + touched, known := in.changedFiles(ctx, p.finding.File) + if touched || !known { + blocked = true + } + if !known { + filesKnown = false + } + } + itemLabels := in.labels + if blocked { + itemLabels = blockedBacklogLabels(in.labels) + } + var title, body string + if len(group) == 1 { + title = reviewBacklogIssueTitle(perspective, first.finding) + body = c.reviewBacklogIssueBody(req, perspective, first.finding, in.headSHA, in.blockAt, first.fp) + } else { + title = reviewBacklogGroupTitle(req, perspective, len(group)) + body = c.reviewBacklogGroupBody(req, perspective, group, in.headSHA, in.blockAt) + } + switch { + case missingFile != "": + body = blockedBacklogNote(req.Repo, req.Number, missingFile, in.baseProbe.BaseRef(ctx)) + body + case blocked: + note := blockedOnReviewedPRNote(req.Repo, req.Number) + if !filesKnown { + note = strings.Replace(note, "is about code that PR is changing", "could not be checked against the PR's changed files", 1) + } + body = note + body + } + ref, err := sink.CreateItem(ctx, ReviewBacklogItem{ + Repo: req.Repo, + Title: title, + Body: body, + Labels: itemLabels, + Perspective: perspective, + Finding: first.finding, + }) + if err != nil && ref.ID == "" { + return reviewBacklogFiled{}, false, err + } + createErr := err + if ref.ID == "" { + return reviewBacklogFiled{}, false, nil + } + if ref.Reused && createErr == nil { + // hivecommons/hive#13604: the comment must carry the whole + // finding or it is lost when the twin closes; one per finding so + // the split sweep reads each back. + for _, p := range group { + if err := sink.AppendToItem(ctx, req.Repo, ref, c.reviewBacklogFoldedComment(req, perspective, p.finding, in.headSHA, p.fp, p.key)); err != nil { + return reviewBacklogFiled{}, false, err + } + } + } + if !ref.Reused && ref.SameFileAs > 0 && createErr == nil { + // hivecommons/hive#13906: the item exists, so a failed + // cross-link must not fail the pass and re-file it. + if err := sink.AppendToItem(ctx, req.Repo, ref, reviewBacklogSameFileComment(first.finding, ref.SameFileAs, ref.SameFilePath)); err != nil { + c.logger.Warn("review backlog: same-file cross-link comment failed", + slog.String("repo", req.Repo), slog.String("item", ref.Key), + slog.Int("same_file_as", ref.SameFileAs), slog.String("error", err.Error())) + } + } + if ref.Number > 0 { + c.recordWriteAudit(AuditActionReviewBacklogIssueFiled, hiveWriteMeta(), + WriteTarget{Repo: req.Repo, Number: ref.Number}, + "pr", strconv.Itoa(req.Number), + "perspective", string(perspective), + "findings", strconv.Itoa(len(group)), + "reused", strconv.FormatBool(ref.Reused), + "blocked", strconv.FormatBool(blocked), + "destination", in.destination, + "review_agent", req.Agent) + } + for _, p := range group { + record := p.record + record.IssueNumber, record.IssueURL, record.ItemKey = ref.Number, ref.URL, ref.Key + ledger.Items[p.key] = record + ledger.addPRFinding(req.Repo, req.Number, p.finding, ref, in.headSHA) + fpRecord := reviewBacklogFingerprintRecord{ + Destination: in.destination, + ItemID: ref.ID, + ItemKey: ref.Key, + ItemNumber: ref.Number, + ItemURL: ref.URL, + PRs: []int{req.Number}, + FiledAt: in.now.UTC(), + UpdatedAt: in.now.UTC(), + File: normaliseFingerprintPath(p.finding.File), + Title: strings.TrimSpace(p.finding.Title), + } + if !ref.Reused { + // A filing folded into an open twin keeps the twin's own + // state (#13364). Keep source provenance for new items, + // but only park findings related to the PR. + fpRecord.BlockedOnPR = req.Number + if blocked { + fpRecord.BlockState = reviewBacklogBlockBlocked + } + } + ledger.setFingerprint(req.Repo, p.fp, fpRecord) + } + return reviewBacklogFiled{number: ref.Number, key: ref.Key, url: ref.URL, title: title, folded: ref.Reused, status: reviewBacklogListedFiled}, true, createErr +} + +// reviewBacklogGroupTitle names a collapsed item: `[reviewer] Review backlog +// (<perspective>): <repo>#<pr> — N follow-ups`. It keeps the `Review backlog +// (<perspective>):` lead every backlog item has, so title canonicalisation +// and the fold matcher treat it like any other item. +func reviewBacklogGroupTitle(req ReviewRequest, p review.Perspective, n int) string { + return reviewBacklogIssueTitle(p, outputschema.Finding{Title: fmt.Sprintf("%s#%d — %d follow-ups", strings.TrimSpace(req.Repo), req.Number, n)}) +} + +// reviewBacklogGroupBody is the body of a collapsed item: one checklist +// entry per finding, each with its severity, evidence, summary and +// fingerprint so nothing a per-finding item would have carried is lost. +func (c *Client) reviewBacklogGroupBody(req ReviewRequest, p review.Perspective, group []reviewBacklogPending, headSHA, blockAt string) string { + owner, repoName := c.splitRepo(req.Repo) + var b strings.Builder + fmt.Fprintf(&b, "Filed from %s in the Hive review of PR #%d: %d %s findings collapsed into one item. Tick each off as it is addressed.\n\n", reviewBacklogReason(group[0].finding, blockAt), req.Number, len(group), p) + fmt.Fprintf(&b, "PR: #%d (%s)\n", req.Number, reviewPRURL(owner, repoName, req.Number)) + fmt.Fprintf(&b, "Perspective: %s\n\n", p) + b.WriteString("### Findings\n\n") + for _, g := range group { + f := g.finding + file := strings.TrimSpace(f.File) + fmt.Fprintf(&b, "- [ ] **%s** — %s (`%s:%d`)\n", strings.TrimSpace(f.Title), reviewFindingSeverityLine(f), file, f.Line) + if link := reviewFindingPermalink(owner, repoName, headSHA, f); link != "" { + fmt.Fprintf(&b, " %s\n", link) + } + if summary := strings.TrimSpace(f.Summary); summary != "" { + fmt.Fprintf(&b, " %s\n", summary) + } + fmt.Fprintf(&b, " Fingerprint: `%s`\n", g.fp) + } + fmt.Fprintf(&b, "\n%s\n", reviewBacklogFooter) + return b.String() +} + +// upsertReviewFollowUpsComment lists the findings held below +// review.backlog.min_severity in the PR's single Follow-ups comment, edited +// in place; entries already there (including ones a human ticked) are kept +// and new ones appended. Best effort: a failure is logged, the pass is not +// failed, and the findings return on the next review of the PR. +func (c *Client) upsertReviewFollowUpsComment(ctx context.Context, req ReviewRequest, held []reviewBacklogHeldFinding, minSeverity string) { + res, err := c.EditIssueMarkerComment(ctx, req.Repo, req.Number, reviewFollowUpsCommentMarker, func(previous string) string { + return renderReviewFollowUpsComment(previous, held, minSeverity) + }) + if err != nil { + c.logger.Warn("review backlog: follow-ups comment not updated", + slog.String("repo", req.Repo), slog.Int("number", req.Number), + slog.Int("held", len(held)), slog.String("error", err.Error())) + return + } + if res.Created || res.Edited { + c.recordWriteAudit(AuditActionReviewBacklogSummaryPosted, hiveWriteMeta(), + WriteTarget{Repo: req.Repo, Number: req.Number}, + "held", strconv.Itoa(len(held)), + "min_severity", minSeverity, + "review_agent", req.Agent) + } +} + +// renderReviewFollowUpsComment merges held into previous (the comment's +// prior body, "" when none) and returns the full comment. Checklist lines +// are keyed on their text after the checkbox so a ticked entry stays ticked +// and a re-reported finding is not listed twice. +func renderReviewFollowUpsComment(previous string, held []reviewBacklogHeldFinding, minSeverity string) string { + type entry struct { + checked bool + text string + } + var entries []entry + seen := map[string]bool{} + for _, line := range strings.Split(previous, "\n") { + trimmed := strings.TrimSpace(line) + var checked bool + var text string + switch { + case strings.HasPrefix(trimmed, "- [ ] "): + text = strings.TrimSpace(strings.TrimPrefix(trimmed, "- [ ] ")) + case strings.HasPrefix(trimmed, "- [x] "), strings.HasPrefix(trimmed, "- [X] "): + checked, text = true, strings.TrimSpace(trimmed[len("- [x] "):]) + default: + continue + } + if text == "" || seen[text] { + continue + } + seen[text] = true + entries = append(entries, entry{checked: checked, text: text}) + } + for _, h := range held { + text := reviewFollowUpLine(h) + if seen[text] { + continue + } + seen[text] = true + entries = append(entries, entry{text: text}) + } + if len(entries) == 0 { + return "" + } + sort.SliceStable(entries, func(i, j int) bool { return entries[i].text < entries[j].text }) + var b strings.Builder + b.WriteString(reviewFollowUpsCommentMarker) + fmt.Fprintf(&b, "\n### Review follow-ups (below `review.backlog.min_severity: %s`)\n", minSeverity) + b.WriteString("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.\n\n") + for _, e := range entries { + box := "[ ]" + if e.checked { + box = "[x]" + } + fmt.Fprintf(&b, "- %s %s\n", box, e.text) + } + return b.String() +} + +// reviewFollowUpLine is one held finding's checklist text: +// `**P3 low** docs-currency — <title> (`file:line`): <summary>`. +func reviewFollowUpLine(h reviewBacklogHeldFinding) string { + f := h.Finding + text := fmt.Sprintf("**P%d %s** %s — %s (`%s:%d`)", ReviewFindingPriority(f.Severity), strings.ToLower(strings.TrimSpace(string(f.Severity))), h.Perspective, strings.TrimSpace(f.Title), strings.TrimSpace(f.File), f.Line) + summary := strings.Join(strings.Fields(f.Summary), " ") + if r := []rune(summary); len(r) > reviewFollowUpsSummaryMaxLen { + summary = string(r[:reviewFollowUpsSummaryMaxLen-1]) + "…" + } + if summary != "" { + text += ": " + summary + } + return text +} diff --git a/src/pkg/github/review_backlog_collapse_test.go b/src/pkg/github/review_backlog_collapse_test.go new file mode 100644 index 0000000000..0306128efe --- /dev/null +++ b/src/pkg/github/review_backlog_collapse_test.go @@ -0,0 +1,315 @@ +package github + +import ( + "context" + "encoding/json" + "fmt" + "io" + "net/http" + "net/http/httptest" + "strings" + "testing" + "time" + + "github.com/hivecommons/hive/pkg/config" + "github.com/hivecommons/hive/pkg/outputschema" + "github.com/hivecommons/hive/pkg/review" +) + +func TestReviewFindingBelowMinSeverity(t *testing.T) { + for _, tc := range []struct { + name string + severity string + minSeverity string + want bool + }{ + {name: "low below default", severity: "low", want: true}, + {name: "info below default", severity: "info", want: true}, + {name: "medium at default", severity: "medium"}, + {name: "high above default", severity: "high"}, + {name: "P3 files everything", severity: "info", minSeverity: "P3"}, + {name: "P1 holds medium", severity: "medium", minSeverity: "p1", want: true}, + {name: "P0 holds high", severity: "high", minSeverity: "P0", want: true}, + {name: "P0 keeps critical", severity: "critical", minSeverity: "P0"}, + {name: "invalid uses default", severity: "low", minSeverity: "P9", want: true}, + } { + t.Run(tc.name, func(t *testing.T) { + f := outputschema.Finding{Severity: outputschema.Severity(tc.severity)} + if got := ReviewFindingBelowMinSeverity(f, tc.minSeverity); got != tc.want { + t.Fatalf("below = %v, want %v", got, tc.want) + } + }) + } +} + +func TestGroupReviewBacklogPending(t *testing.T) { + p := func(persp review.Perspective, title string, oos bool) reviewBacklogPending { + return reviewBacklogPending{perspective: persp, finding: outputschema.Finding{Title: title}, outOfScope: oos} + } + for _, tc := range []struct { + name string + pending []reviewBacklogPending + want [][]string + }{ + {name: "empty"}, + {name: "one", pending: []reviewBacklogPending{p("docs-currency", "a", false)}, want: [][]string{{"a"}}}, + { + name: "same perspective collapses in order", + pending: []reviewBacklogPending{ + p("docs-currency", "a", false), p("correctness", "b", false), p("docs-currency", "c", false), + }, + want: [][]string{{"a", "c"}, {"b"}}, + }, + { + name: "scope splits a perspective", + pending: []reviewBacklogPending{ + p("style", "in", false), p("style", "out", true), p("style", "in2", false), + }, + want: [][]string{{"in", "in2"}, {"out"}}, + }, + } { + t.Run(tc.name, func(t *testing.T) { + groups := groupReviewBacklogPending(tc.pending) + var got [][]string + for _, g := range groups { + var titles []string + for _, f := range g { + titles = append(titles, f.finding.Title) + } + got = append(got, titles) + } + if fmt.Sprint(got) != fmt.Sprint(tc.want) { + t.Fatalf("groups = %v, want %v", got, tc.want) + } + }) + } +} + +func TestRenderReviewFollowUpsComment(t *testing.T) { + held := func(persp review.Perspective, title, sev, file string, line int, summary string) reviewBacklogHeldFinding { + return reviewBacklogHeldFinding{Perspective: persp, Finding: outputschema.Finding{Title: title, Severity: outputschema.Severity(sev), File: file, Line: line, Summary: summary}} + } + docs := held("docs-currency", "stale example", "low", "docs/a.md", 3, "shows the old flag") + docsLine := "- [ ] **P3 low** docs-currency — stale example (`docs/a.md:3`): shows the old flag" + for _, tc := range []struct { + name string + previous string + held []reviewBacklogHeldFinding + want []string + wantNot []string + empty bool + }{ + {name: "nothing", empty: true}, + { + name: "fresh comment", + held: []reviewBacklogHeldFinding{docs}, + want: []string{reviewFollowUpsCommentMarker, "min_severity: P2", docsLine}, + }, + { + name: "re-report is not listed twice", + previous: reviewFollowUpsCommentMarker + "\n### x\n\n" + docsLine + "\n", + held: []reviewBacklogHeldFinding{docs}, + want: []string{docsLine}, + }, + { + name: "ticked entry stays ticked and new one is appended", + previous: reviewFollowUpsCommentMarker + "\n\n- [x] **P3 low** docs-currency — stale example (`docs/a.md:3`): shows the old flag\n", + held: []reviewBacklogHeldFinding{docs, held("style", "naming", "info", "pkg/c.go", 4, "prefer camelCase")}, + want: []string{"- [x] **P3 low** docs-currency — stale example (`docs/a.md:3`): shows the old flag", "- [ ] **P3 info** style — naming (`pkg/c.go:4`): prefer camelCase"}, + wantNot: []string{docsLine}, + }, + { + name: "long summary is collapsed to one line and truncated", + held: []reviewBacklogHeldFinding{held("style", "long", "low", "pkg/l.go", 1, strings.Repeat("word\n", 100))}, + want: []string{"…", "(`pkg/l.go:1`): word word"}, + wantNot: []string{"word\nword"}, + }, + } { + t.Run(tc.name, func(t *testing.T) { + got := renderReviewFollowUpsComment(tc.previous, tc.held, "P2") + if tc.empty { + if got != "" { + t.Fatalf("want empty body, got %q", got) + } + return + } + for _, w := range tc.want { + if !strings.Contains(got, w) { + t.Errorf("body missing %q:\n%s", w, got) + } + } + for _, w := range tc.wantNot { + if strings.Contains(got, w) { + t.Errorf("body must not contain %q:\n%s", w, got) + } + } + if n := strings.Count(got, docsLine[:len("- [ ] **P3 low** docs-currency — stale example")]); n > 1 { + t.Errorf("entry listed %d times:\n%s", n, got) + } + }) + } +} + +// followUpsCommentServer serves the PR's issue comments so the Follow-ups +// marker comment can be created once and then edited in place. +type followUpsCommentServer struct { + bodies []string + patches int +} + +func (s *followUpsCommentServer) handler(t *testing.T) http.HandlerFunc { + t.Helper() + return func(w http.ResponseWriter, r *http.Request) { + w.Header().Set("Content-Type", "application/json") + switch { + case r.Method == http.MethodGet && r.URL.Path == "/repos/o/r/issues/5/comments": + var out []map[string]any + for i, b := range s.bodies { + out = append(out, map[string]any{"id": i + 1, "body": b, "user": map[string]any{"login": "hive[bot]"}}) + } + if out == nil { + out = []map[string]any{} + } + _ = json.NewEncoder(w).Encode(out) + case r.Method == http.MethodPost && r.URL.Path == "/repos/o/r/issues/5/comments": + var payload struct { + Body string `json:"body"` + } + _ = json.NewDecoder(r.Body).Decode(&payload) + s.bodies = append(s.bodies, payload.Body) + fmt.Fprintf(w, `{"id":%d}`, len(s.bodies)) + case r.Method == http.MethodPatch && strings.HasPrefix(r.URL.Path, "/repos/o/r/issues/comments/"): + var id int + _, _ = fmt.Sscanf(r.URL.Path, "/repos/o/r/issues/comments/%d", &id) + var payload struct { + Body string `json:"body"` + } + _ = json.NewDecoder(r.Body).Decode(&payload) + if id < 1 || id > len(s.bodies) { + w.WriteHeader(http.StatusNotFound) + return + } + s.bodies[id-1] = payload.Body + s.patches++ + fmt.Fprintf(w, `{"id":%d}`, id) + default: + w.WriteHeader(http.StatusNotFound) + _, _ = io.WriteString(w, `{"message":"not found"}`) + } + } +} + +// Findings below review.backlog.min_severity are never items: they land in +// one Follow-ups comment per PR, edited in place on later passes, while +// findings at or above the line still file (hivecommons/hive#17065). +func TestReviewBacklogHoldsFindingsBelowMinSeverityInOneComment(t *testing.T) { + for _, tc := range []struct { + name string + minSeverity string + wantItems int + wantHeld bool + }{ + {name: "default P2 holds the P3 nits", wantItems: 1, wantHeld: true}, + // All three share the correctness perspective, so filing them + // yields one collapsed item, not three. + {name: "P3 files everything", minSeverity: "P3", wantItems: 1}, + {name: "P1 holds the medium too", minSeverity: "P1", wantItems: 0, wantHeld: true}, + } { + t.Run(tc.name, func(t *testing.T) { + withReviewBacklogState(t) + server := &followUpsCommentServer{} + srv := httptest.NewServer(server.handler(t)) + defer srv.Close() + c := reviewTestClient(t, srv.URL) + sink := &fakeBacklogSink{dest: config.ReviewBacklogLinear} + c.SetReviewBacklogRouting(func() ReviewBacklogRouting { + return ReviewBacklogRouting{ + Severity: config.ReviewSeverityConfig{BlockAt: "P1"}, + Backlog: config.ReviewBacklogConfig{Destination: config.ReviewBacklogLinear, MinSeverity: tc.minSeverity}, + Sink: sink, + } + }) + ctx := context.Background() + now := time.Date(2026, 11, 7, 12, 0, 0, 0, time.UTC) + report := routingReport(t, 5, "abc", + nit("unused variable", "medium", "pkg/a.go", 7, "x is assigned and never read"), + nit("stale example", "low", "docs/a.md", 3, "shows the old flag"), + nit("naming", "info", "pkg/c.go", 4, "prefer camelCase"), + ) + req := ReviewRequest{Repo: "o/r", Number: 5, Agent: "reviewer", Report: report} + if err := c.fileOutOfScopeReviewBacklog(ctx, req, now); err != nil { + t.Fatal(err) + } + if len(sink.created) != tc.wantItems { + t.Fatalf("created = %d, want %d: %+v", len(sink.created), tc.wantItems, sink.created) + } + if tc.minSeverity == "P3" { + if got := sink.created[0].Title; !strings.HasSuffix(got, "o/r#5 — 3 follow-ups") { + t.Fatalf("P3 must file every finding, collapsed: title = %q", got) + } + } + var followUps []string + for _, b := range server.bodies { + if strings.Contains(b, reviewFollowUpsCommentMarker) { + followUps = append(followUps, b) + } + } + if !tc.wantHeld { + if len(followUps) != 0 { + t.Fatalf("follow-ups comment posted with nothing held: %v", followUps) + } + return + } + if len(followUps) != 1 { + t.Fatalf("follow-ups comments = %d, want 1", len(followUps)) + } + for _, want := range []string{"stale example (`docs/a.md:3`)", "naming (`pkg/c.go:4`)"} { + if !strings.Contains(followUps[0], want) { + t.Errorf("follow-ups comment missing %q:\n%s", want, followUps[0]) + } + } + if tc.minSeverity == "P1" && !strings.Contains(followUps[0], "unused variable") { + t.Errorf("P1 must hold the medium finding too:\n%s", followUps[0]) + } + + // Next head: same nits plus one more. The comment is edited, + // never posted again, and lists the old and the new entries. + again := routingReport(t, 5, "abd", + nit("stale example", "low", "docs/a.md", 3, "shows the old flag"), + nit("naming", "info", "pkg/c.go", 4, "prefer camelCase"), + nit("typo", "low", "pkg/b.go", 9, "receive"), + ) + if err := c.fileOutOfScopeReviewBacklog(ctx, ReviewRequest{Repo: "o/r", Number: 5, Agent: "reviewer", Report: again}, now.Add(time.Hour)); err != nil { + t.Fatal(err) + } + // The PR's once-per-PR backlog summary is also a POST; the + // Follow-ups comment itself is created once and then edited. + var followUpPosts int + for _, b := range server.bodies { + if strings.Contains(b, reviewFollowUpsCommentMarker) { + followUpPosts++ + } + } + if followUpPosts != 1 || server.patches != 1 { + t.Fatalf("follow-ups comments=%d patches=%d, want one create then one edit", followUpPosts, server.patches) + } + body := followUps[0] + for _, b := range server.bodies { + if strings.Contains(b, reviewFollowUpsCommentMarker) { + body = b + } + } + for _, want := range []string{"stale example", "naming", "typo (`pkg/b.go:9`)"} { + if !strings.Contains(body, want) { + t.Errorf("edited follow-ups comment missing %q:\n%s", want, body) + } + } + if strings.Count(body, "stale example") != 1 { + t.Errorf("re-reported nit listed twice:\n%s", body) + } + if len(sink.created) != tc.wantItems { + t.Fatalf("held findings were filed on the second pass: %+v", sink.created) + } + }) + } +} diff --git a/src/pkg/github/review_backlog_dedupe_test.go b/src/pkg/github/review_backlog_dedupe_test.go index 3cfebe4b8d..4e0634e6a4 100644 --- a/src/pkg/github/review_backlog_dedupe_test.go +++ b/src/pkg/github/review_backlog_dedupe_test.go @@ -110,7 +110,7 @@ func TestReviewBacklogOneItemPerFindingAcrossPerspectivesAndHeads(t *testing.T) c.SetReviewBacklogRouting(func() ReviewBacklogRouting { return ReviewBacklogRouting{ Severity: config.ReviewSeverityConfig{BlockAt: "P1"}, - Backlog: config.ReviewBacklogConfig{Destination: config.ReviewBacklogLinear, MaxPerPRPerDay: 10}, + Backlog: config.ReviewBacklogConfig{Destination: config.ReviewBacklogLinear, MaxPerPRPerDay: 10, MinSeverity: "P3"}, Sink: sink, } }) diff --git a/src/pkg/github/review_backlog_heads_test.go b/src/pkg/github/review_backlog_heads_test.go index 1788d4dcc5..3ffa73e4dc 100644 --- a/src/pkg/github/review_backlog_heads_test.go +++ b/src/pkg/github/review_backlog_heads_test.go @@ -71,7 +71,7 @@ func headsBacklogClient(t *testing.T, srvURL string, sink *fakeBacklogSink) *Cli c.SetReviewBacklogRouting(func() ReviewBacklogRouting { return ReviewBacklogRouting{ Severity: config.ReviewSeverityConfig{BlockAt: "P2"}, - Backlog: config.ReviewBacklogConfig{Destination: config.ReviewBacklogLinear, Labels: []string{"followup"}}, + Backlog: config.ReviewBacklogConfig{Destination: config.ReviewBacklogLinear, Labels: []string{"followup"}, MinSeverity: "P3"}, Sink: sink, } }) @@ -239,7 +239,7 @@ func TestReconcileReviewBacklogBlocks(t *testing.T) { sink := &fakeResolverSink{fakeBacklogSink: fakeBacklogSink{dest: config.ReviewBacklogLinear}} c := reviewTestClient(t, srv.URL) c.SetReviewBacklogRouting(func() ReviewBacklogRouting { - return ReviewBacklogRouting{Backlog: config.ReviewBacklogConfig{Destination: config.ReviewBacklogLinear}, Sink: sink} + return ReviewBacklogRouting{Backlog: config.ReviewBacklogConfig{Destination: config.ReviewBacklogLinear, MinSeverity: "P3"}, Sink: sink} }) now := time.Now().UTC() ledger := newReviewBacklogLedger() @@ -336,7 +336,7 @@ func TestReconcileReviewBacklogBlocksSupersede(t *testing.T) { sink := &fakeResolverSink{fakeBacklogSink: fakeBacklogSink{dest: config.ReviewBacklogLinear}} c := reviewTestClient(t, srv.URL) c.SetReviewBacklogRouting(func() ReviewBacklogRouting { - return ReviewBacklogRouting{Backlog: config.ReviewBacklogConfig{Destination: config.ReviewBacklogLinear}, Sink: sink} + return ReviewBacklogRouting{Backlog: config.ReviewBacklogConfig{Destination: config.ReviewBacklogLinear, MinSeverity: "P3"}, Sink: sink} }) now := time.Now().UTC() ledger := newReviewBacklogLedger() diff --git a/src/pkg/github/review_backlog_routing.go b/src/pkg/github/review_backlog_routing.go index b2ccccef48..2b450f8ed3 100644 --- a/src/pkg/github/review_backlog_routing.go +++ b/src/pkg/github/review_backlog_routing.go @@ -353,11 +353,12 @@ func appendLabelOnce(labels []string, label string) []string { return append(labels, label) } -// reviewBacklogDailyCap is review.backlog.max_per_pr_per_day when routing is -// configured, else the legacy per-PR cap. -func reviewBacklogDailyCap(r ReviewBacklogRouting, routed bool, legacyCap int) int { +// reviewBacklogPRCap is review.backlog.max_per_pr (per PR lifetime, +// hivecommons/hive#17065) when routing is configured, else the legacy per-PR +// cap. +func reviewBacklogPRCap(r ReviewBacklogRouting, routed bool, legacyCap int) int { if routed { - return r.Backlog.EffectiveMaxPerPRPerDay() + return r.Backlog.EffectiveMaxPerPR() } if legacyCap <= 0 { return DefaultReviewBacklogIssueCap @@ -402,6 +403,22 @@ func ReviewFindingBelowLine(f outputschema.Finding, blockAt string) bool { return ReviewFindingPriority(f.Severity) > line } +// ReviewFindingBelowMinSeverity reports whether f is below +// review.backlog.min_severity (P0–P3): such a finding is listed in the PR's +// Follow-ups comment instead of filed as an item (hivecommons/hive#17065). +// An unrecognised minSeverity is treated as the default. +func ReviewFindingBelowMinSeverity(f outputschema.Finding, minSeverity string) bool { + m, ok := config.NormalizeReviewBacklogMinSeverity(minSeverity) + if !ok { + m = config.DefaultReviewBacklogMinSeverity + } + line, err := strconv.Atoi(strings.TrimPrefix(m, "P")) + if err != nil { + return false + } + return ReviewFindingPriority(f.Severity) > line +} + // ReviewFindingFingerprint is sha256(rule | path | snippet) for a finding: // the finding title is the rule, the cited file the path, and the summary // the snippet. Text is lower-cased with whitespace runs collapsed and paths @@ -484,24 +501,6 @@ func (l *reviewBacklogLedger) setFingerprint(repo, fp string, rec reviewBacklogF l.Fingerprints[key][fp] = rec } -const reviewBacklogDayLayout = "2006-01-02" - -func reviewBacklogDayKey(prKey string, now time.Time) string { - return prKey + "@" + now.UTC().Format(reviewBacklogDayLayout) -} - -// pruneDailyCounts drops per-day counters older than yesterday so the ledger -// does not grow without bound. -func (l *reviewBacklogLedger) pruneDailyCounts(now time.Time) { - cutoff := now.UTC().AddDate(0, 0, -1).Format(reviewBacklogDayLayout) - for k := range l.PRDailyCount { - i := strings.LastIndex(k, "@") - if i < 0 || k[i+1:] < cutoff { - delete(l.PRDailyCount, k) - } - } -} - func reviewPRURL(owner, repo string, number int) string { return fmt.Sprintf("https://github.com/%s/%s/pull/%d", owner, repo, number) } diff --git a/src/pkg/github/review_backlog_routing_test.go b/src/pkg/github/review_backlog_routing_test.go index 1e07931418..b351f51423 100644 --- a/src/pkg/github/review_backlog_routing_test.go +++ b/src/pkg/github/review_backlog_routing_test.go @@ -94,28 +94,26 @@ func TestReviewBacklogTargetFallsBackToGitHubWithReviewerAgentLabel(t *testing.T } } -func TestReviewBacklogDailyCapAndPrune(t *testing.T) { - if got := reviewBacklogDailyCap(ReviewBacklogRouting{}, false, 0); got != DefaultReviewBacklogIssueCap { - t.Fatalf("unrouted cap = %d, want legacy default %d", got, DefaultReviewBacklogIssueCap) - } - if got := reviewBacklogDailyCap(ReviewBacklogRouting{}, false, 5); got != 5 { - t.Fatalf("unrouted cap = %d, want legacy 5", got) - } - if got := reviewBacklogDailyCap(ReviewBacklogRouting{}, true, 5); got != config.DefaultReviewBacklogMaxPerPRPerDay { - t.Fatalf("routed default cap = %d, want %d", got, config.DefaultReviewBacklogMaxPerPRPerDay) - } - if got := reviewBacklogDailyCap(ReviewBacklogRouting{Backlog: config.ReviewBacklogConfig{MaxPerPRPerDay: 4}}, true, 5); got != 4 { - t.Fatalf("routed cap = %d, want 4", got) - } - now := time.Date(2026, 10, 9, 12, 0, 0, 0, time.UTC) - l := newReviewBacklogLedger() - l.PRDailyCount["o/r#5@2026-10-01"] = 3 - l.PRDailyCount["o/r#5@2026-10-08"] = 2 - l.PRDailyCount[reviewBacklogDayKey("o/r#5", now)] = 1 - l.PRDailyCount["garbage"] = 1 - l.pruneDailyCounts(now) - if len(l.PRDailyCount) != 2 || l.PRDailyCount["o/r#5@2026-10-08"] != 2 || l.PRDailyCount["o/r#5@2026-10-09"] != 1 { - t.Fatalf("pruned counts = %v, want yesterday and today only", l.PRDailyCount) +func TestReviewBacklogPRCap(t *testing.T) { + for _, tc := range []struct { + name string + routing ReviewBacklogRouting + routed bool + legacy int + want int + }{ + {name: "unrouted default", want: DefaultReviewBacklogIssueCap}, + {name: "unrouted legacy", legacy: 5, want: 5}, + {name: "routed default", routed: true, legacy: 5, want: config.DefaultReviewBacklogMaxPerPR}, + {name: "routed max_per_pr", routing: ReviewBacklogRouting{Backlog: config.ReviewBacklogConfig{MaxPerPR: 4}}, routed: true, legacy: 5, want: 4}, + {name: "routed retired per-day alias", routing: ReviewBacklogRouting{Backlog: config.ReviewBacklogConfig{MaxPerPRPerDay: 7}}, routed: true, want: 7}, + {name: "max_per_pr wins over alias", routing: ReviewBacklogRouting{Backlog: config.ReviewBacklogConfig{MaxPerPR: 2, MaxPerPRPerDay: 7}}, routed: true, want: 2}, + } { + t.Run(tc.name, func(t *testing.T) { + if got := reviewBacklogPRCap(tc.routing, tc.routed, tc.legacy); got != tc.want { + t.Fatalf("cap = %d, want %d", got, tc.want) + } + }) } } @@ -233,7 +231,7 @@ func prCommentServer(t *testing.T, bodies map[int][]string) *httptest.Server { return srv } -func TestReviewBacklogRoutesBelowLineFindingsWithDedupAndDailyCap(t *testing.T) { +func TestReviewBacklogRoutesBelowLineFindingsWithDedupAndPRCap(t *testing.T) { withReviewBacklogState(t) comments := map[int][]string{} srv := prCommentServer(t, comments) @@ -243,7 +241,7 @@ func TestReviewBacklogRoutesBelowLineFindingsWithDedupAndDailyCap(t *testing.T) c.SetReviewBacklogRouting(func() ReviewBacklogRouting { return ReviewBacklogRouting{ Severity: config.ReviewSeverityConfig{BlockAt: "P1"}, - Backlog: config.ReviewBacklogConfig{Destination: config.ReviewBacklogLinear, Labels: []string{"nit"}, MaxPerPRPerDay: 2}, + Backlog: config.ReviewBacklogConfig{Destination: config.ReviewBacklogLinear, Labels: []string{"nit"}, MaxPerPR: 2, MinSeverity: "P3"}, Sink: sink, } }) @@ -254,15 +252,13 @@ func TestReviewBacklogRoutesBelowLineFindingsWithDedupAndDailyCap(t *testing.T) pr5 := routingReport(t, 5, "abc", nit("unused variable", "medium", "pkg/a.go", 7, "x is assigned and never read"), nit("blocking bug", "high", "pkg/a.go", 9, "this blocks and must not be filed"), - nit("typo in comment", "low", "pkg/b.go", 3, "receive should be receive"), - nit("naming", "info", "pkg/c.go", 4, "prefer camelCase"), map[string]any{"title": "no evidence", "severity": "low", "summary": "uncited", "review_scope": "in-scope"}, ) if err := c.fileOutOfScopeReviewBacklog(ctx, ReviewRequest{Repo: "o/r", Number: 5, Agent: "reviewer", Report: pr5}, day1); err != nil { t.Fatalf("file PR 5: %v", err) } - if len(sink.created) != 2 { - t.Fatalf("created = %d, want 2 (daily cap) below-line items", len(sink.created)) + if len(sink.created) != 1 { + t.Fatalf("created = %d, want 1 below-line item", len(sink.created)) } first := sink.created[0] if first.Repo != "o/r" || first.Title != "[reviewer] Review backlog (correctness): unused variable" || strings.Join(first.Labels, ",") != "nit,blocked" { @@ -289,17 +285,52 @@ func TestReviewBacklogRoutesBelowLineFindingsWithDedupAndDailyCap(t *testing.T) t.Errorf("filed a blocking or uncited finding: %q", item.Title) } } - if len(comments[5]) != 1 || !strings.Contains(comments[5][0], "ENG-1") || !strings.Contains(comments[5][0], "ENG-2") { - t.Fatalf("PR 5 summary comments = %v, want one listing ENG-1 and ENG-2", comments[5]) + if len(comments[5]) != 1 || !strings.Contains(comments[5][0], "ENG-1") { + t.Fatalf("PR 5 summary comments = %v, want one listing ENG-1", comments[5]) } batch := assertTypedWrite(t, *recs, AuditActionReviewBacklogBatchRouted, "o/r", 5, 1) - for _, want := range []string{"destination=linear", "filed=2", "updated=0", "capped=1"} { + for _, want := range []string{"destination=linear", "filed=1", "updated=0", "capped=0"} { if !strings.Contains(batch.Detail, want) { t.Errorf("batch detail %q missing %q", batch.Detail, want) } } assertTypedWrite(t, *recs, AuditActionReviewBacklogIssueFiled, "", 0, 0) + // A later head adds two P3 nits from the same perspective: one + // collapsed item with a checklist, not two (hivecommons/hive#17065). + pr5b := routingReport(t, 5, "abd", + nit("unused variable", "medium", "pkg/a.go", 7, "x is assigned and never read"), + nit("typo in comment", "low", "pkg/b.go", 3, "receive should be receive"), + nit("naming", "info", "pkg/c.go", 4, "prefer camelCase"), + ) + if err := c.fileOutOfScopeReviewBacklog(ctx, ReviewRequest{Repo: "o/r", Number: 5, Agent: "reviewer", Report: pr5b}, day1.Add(time.Hour)); err != nil { + t.Fatalf("file PR 5 head abd: %v", err) + } + if len(sink.created) != 2 { + t.Fatalf("created = %d, want the two nits collapsed into one item", len(sink.created)) + } + group := sink.created[1] + if group.Title != "[reviewer] Review backlog (correctness): o/r#5 — 2 follow-ups" { + t.Fatalf("collapsed title = %q", group.Title) + } + for _, want := range []string{"- [ ] **typo in comment** — low (P3) (`pkg/b.go:3`)", "- [ ] **naming** — info (P3) (`pkg/c.go:4`)", "https://github.com/o/r/blob/abd/pkg/b.go#L3", "prefer camelCase", "2 correctness findings collapsed into one item"} { + if !strings.Contains(group.Body, want) { + t.Errorf("collapsed body missing %q:\n%s", want, group.Body) + } + } + // The cap is per PR lifetime: a third pass, even a day later, files + // nothing new. + pr5c := routingReport(t, 5, "abe", nit("shadowed err", "medium", "pkg/d.go", 2, "err is shadowed")) + if err := c.fileOutOfScopeReviewBacklog(ctx, ReviewRequest{Repo: "o/r", Number: 5, Agent: "reviewer", Report: pr5c}, day1.Add(48*time.Hour)); err != nil { + t.Fatal(err) + } + if len(sink.created) != 2 { + t.Fatalf("per-PR cap reset: created = %d, want still 2", len(sink.created)) + } + if len(comments[5]) != 1 { + t.Fatalf("PR 5 summary comments = %d, want still one", len(comments[5])) + } + // PR 6 re-raises the first finding: reflowed text, other line, other head. pr6 := routingReport(t, 6, "def", nit("Unused Variable", "medium", "./pkg/a.go", 42, "x is assigned\nand never read"), @@ -313,10 +344,16 @@ func TestReviewBacklogRoutesBelowLineFindingsWithDedupAndDailyCap(t *testing.T) if len(sink.created) != 2 { t.Fatalf("re-raise created a new item: %d items", len(sink.created)) } - if len(sink.appends) != 1 { - t.Fatalf("appends = %d, want one update of the existing item", len(sink.appends)) + // Head abd re-reported "unused variable", so ENG-1 carries one + // still-present note (bounded per head, not by the cap); PR 6's + // re-raise is the only other update. + if len(sink.appends) != 2 { + t.Fatalf("appends = %d, want one still-present note and one re-raise", len(sink.appends)) } - up := sink.appends[0] + if !strings.Contains(sink.appends[0].comment, reviewBacklogStillPresentMarker) || sink.appends[0].ref.Key != "ENG-1" { + t.Fatalf("first append = %+v, want a still-present note on ENG-1", sink.appends[0]) + } + up := sink.appends[1] if up.ref.ID != "id-1" || up.ref.Key != "ENG-1" { t.Fatalf("updated %+v, want ENG-1", up.ref) } @@ -336,22 +373,18 @@ func TestReviewBacklogRoutesBelowLineFindingsWithDedupAndDailyCap(t *testing.T) if !ok || fmt.Sprint(rec.PRs) != "[5 6]" || rec.Destination != config.ReviewBacklogLinear || rec.ItemKey != "ENG-1" { t.Fatalf("fingerprint record = %+v ok=%v, want PRs [5 6] on linear ENG-1", rec, ok) } - - // Same day, PR 5 again: still capped. Next day: the capped finding files. - if err := c.fileOutOfScopeReviewBacklog(ctx, ReviewRequest{Repo: "o/r", Number: 5, Agent: "reviewer", Report: pr5}, day1.Add(time.Hour)); err != nil { - t.Fatal(err) - } - if len(sink.created) != 2 { - t.Fatalf("same-day re-review created past the cap: %d", len(sink.created)) - } - if err := c.fileOutOfScopeReviewBacklog(ctx, ReviewRequest{Repo: "o/r", Number: 5, Agent: "reviewer", Report: pr5}, day1.Add(24*time.Hour)); err != nil { - t.Fatal(err) - } - if len(sink.created) != 3 || !strings.Contains(sink.created[2].Title, "naming") { - t.Fatalf("next day: created = %d, want the capped finding filed", len(sink.created)) + // Both collapsed findings map to the collapsed item. + for _, f := range []outputschema.Finding{ + {Title: "typo in comment", File: "pkg/b.go", Summary: "receive should be receive"}, + {Title: "naming", File: "pkg/c.go", Summary: "prefer camelCase"}, + } { + rec, ok := ledger.fingerprint("o/r", ReviewFindingFingerprint(f)) + if !ok || rec.ItemKey != "ENG-2" { + t.Fatalf("%s: fingerprint record = %+v ok=%v, want ENG-2", f.Title, rec, ok) + } } - if len(comments[5]) != 1 { - t.Fatalf("PR 5 summary comments = %d, want still one", len(comments[5])) + if got := ledger.PRItemCount[ReviewLinkKey("o/r", 5)]; got != 2 { + t.Fatalf("PR 5 lifetime count = %d, want 2", got) } } @@ -367,7 +400,7 @@ func TestReviewBacklogNoBlockingLineLeavesInScopeFindingsAlone(t *testing.T) { backlogBelow := false c.SetReviewBacklog(func() (bool, int) { return false, 3 }) c.SetReviewBacklogRouting(func() ReviewBacklogRouting { - return ReviewBacklogRouting{Severity: config.ReviewSeverityConfig{BlockAt: "P1", BacklogBelow: &backlogBelow}, Sink: sink} + return ReviewBacklogRouting{Backlog: config.ReviewBacklogConfig{MinSeverity: "P3"}, Severity: config.ReviewSeverityConfig{BlockAt: "P1", BacklogBelow: &backlogBelow}, Sink: sink} }) if err := c.fileOutOfScopeReviewBacklog(context.Background(), ReviewRequest{Repo: "o/r", Number: 5, Agent: "reviewer", Report: report}, time.Now()); err != nil { t.Fatal(err) @@ -384,7 +417,7 @@ func TestReviewBacklogCreateErrors(t *testing.T) { c.SetReviewBacklogRouting(func() ReviewBacklogRouting { return ReviewBacklogRouting{ Severity: config.ReviewSeverityConfig{BlockAt: "P2"}, - Backlog: config.ReviewBacklogConfig{Destination: config.ReviewBacklogJira}, + Backlog: config.ReviewBacklogConfig{Destination: config.ReviewBacklogJira, MinSeverity: "P3"}, Sink: sink, } }) @@ -443,7 +476,7 @@ func TestReviewBacklogGitHubIssueDestinationOverHTTP(t *testing.T) { // linear is not active, so the fallback GitHub issue sink is used. return ReviewBacklogRouting{ Severity: config.ReviewSeverityConfig{BlockAt: "P2"}, - Backlog: config.ReviewBacklogConfig{Destination: config.ReviewBacklogLinear, Labels: []string{"nit"}}, + Backlog: config.ReviewBacklogConfig{Destination: config.ReviewBacklogLinear, Labels: []string{"nit"}, MinSeverity: "P3"}, } }) recs := captureAudit(c) @@ -494,7 +527,7 @@ func TestReviewBacklogRefilesWhenLedgerItemClosed(t *testing.T) { c.SetReviewBacklogRouting(func() ReviewBacklogRouting { return ReviewBacklogRouting{ Severity: config.ReviewSeverityConfig{BlockAt: "P1"}, - Backlog: config.ReviewBacklogConfig{Destination: config.ReviewBacklogLinear, MaxPerPRPerDay: 5}, + Backlog: config.ReviewBacklogConfig{Destination: config.ReviewBacklogLinear, MaxPerPRPerDay: 5, MinSeverity: "P3"}, Sink: sink, } }) @@ -535,7 +568,7 @@ func TestReviewBacklogStateProbeErrorAppendsAndSamePRSkipsProbe(t *testing.T) { c.SetReviewBacklogRouting(func() ReviewBacklogRouting { return ReviewBacklogRouting{ Severity: config.ReviewSeverityConfig{BlockAt: "P1"}, - Backlog: config.ReviewBacklogConfig{Destination: config.ReviewBacklogLinear, MaxPerPRPerDay: 5}, + Backlog: config.ReviewBacklogConfig{Destination: config.ReviewBacklogLinear, MaxPerPRPerDay: 5, MinSeverity: "P3"}, Sink: sink, } }) @@ -658,7 +691,7 @@ func TestReviewBacklogGitHubSinkFoldsIntoOpenAgentTwin(t *testing.T) { c.SetReviewBacklogRouting(func() ReviewBacklogRouting { return ReviewBacklogRouting{ Severity: config.ReviewSeverityConfig{BlockAt: "P2"}, - Backlog: config.ReviewBacklogConfig{Destination: config.ReviewBacklogGitHubIssue, Labels: []string{"nit"}}, + Backlog: config.ReviewBacklogConfig{Destination: config.ReviewBacklogGitHubIssue, Labels: []string{"nit"}, MinSeverity: "P3"}, } }) finding := nit("nit", "low", "pkg/a.go", 3, "minor") @@ -708,7 +741,7 @@ func TestReviewBacklogFoldedTwinKeepsFullFinding(t *testing.T) { c.SetReviewBacklogRouting(func() ReviewBacklogRouting { return ReviewBacklogRouting{ Severity: config.ReviewSeverityConfig{BlockAt: "P1"}, - Backlog: config.ReviewBacklogConfig{Destination: config.ReviewBacklogLinear, Labels: []string{"nit"}, MaxPerPRPerDay: 5}, + Backlog: config.ReviewBacklogConfig{Destination: config.ReviewBacklogLinear, Labels: []string{"nit"}, MaxPerPRPerDay: 5, MinSeverity: "P3"}, Sink: sink, } }) @@ -835,7 +868,7 @@ func TestReviewBacklogGitHubSinkReusedTwinDoesNotInheritBlocked(t *testing.T) { c.SetReviewBacklogRouting(func() ReviewBacklogRouting { return ReviewBacklogRouting{ Severity: config.ReviewSeverityConfig{BlockAt: "P2"}, - Backlog: config.ReviewBacklogConfig{Destination: config.ReviewBacklogGitHubIssue, Labels: []string{"nit", "help wanted"}}, + Backlog: config.ReviewBacklogConfig{Destination: config.ReviewBacklogGitHubIssue, Labels: []string{"nit", "help wanted"}, MinSeverity: "P3"}, } }) recs := captureAudit(c) @@ -928,7 +961,7 @@ func TestReviewBacklogGitHubSinkFilesSeparatelyForSameFileDifferentFinding(t *te c.SetReviewBacklogRouting(func() ReviewBacklogRouting { return ReviewBacklogRouting{ Severity: config.ReviewSeverityConfig{BlockAt: "P2"}, - Backlog: config.ReviewBacklogConfig{Destination: config.ReviewBacklogGitHubIssue, Labels: []string{"nit"}}, + Backlog: config.ReviewBacklogConfig{Destination: config.ReviewBacklogGitHubIssue, Labels: []string{"nit"}, MinSeverity: "P3"}, } }) finding := nit("nit", "low", "pkg/a.go", 3, "minor") diff --git a/src/pkg/github/review_backlog_same_file_path_test.go b/src/pkg/github/review_backlog_same_file_path_test.go index a981e20084..f48ea158ae 100644 --- a/src/pkg/github/review_backlog_same_file_path_test.go +++ b/src/pkg/github/review_backlog_same_file_path_test.go @@ -69,7 +69,7 @@ func TestReviewBacklogSameFileNamesSharedPath(t *testing.T) { c.SetReviewBacklogRouting(func() ReviewBacklogRouting { return ReviewBacklogRouting{ Severity: config.ReviewSeverityConfig{BlockAt: "P2"}, - Backlog: config.ReviewBacklogConfig{Destination: config.ReviewBacklogGitHubIssue, Labels: []string{"nit"}}, + Backlog: config.ReviewBacklogConfig{Destination: config.ReviewBacklogGitHubIssue, Labels: []string{"nit"}, MinSeverity: "P3"}, } }) finding := nit("Tracking issue #490 already closed despite five outputs still pending", "low", "config/factory-build-backlog.toml", 12, diff --git a/src/pkg/github/review_backlog_scope_test.go b/src/pkg/github/review_backlog_scope_test.go index b34feb74da..7580399164 100644 --- a/src/pkg/github/review_backlog_scope_test.go +++ b/src/pkg/github/review_backlog_scope_test.go @@ -61,11 +61,11 @@ func TestReviewBacklogBlocksOnlyRelatedFiles(t *testing.T) { defer srv.Close() sink := &fakeBacklogSink{dest: config.ReviewBacklogLinear} c := headsBacklogClient(t, srv.URL, sink) - report := routingReport(t, 5, "abc", nit("first", "low", file, 7, "evidence"), nit("second", "low", file, 8, "other evidence")) + report := routingReport(t, 5, "abc", nit("first", "low", file, 7, "evidence")) if err := c.fileOutOfScopeReviewBacklog(context.Background(), ReviewRequest{Repo: "o/r", Number: 5, Agent: "reviewer", Report: report}, time.Now()); err != nil { t.Fatal(err) } - if len(sink.created) != 2 { + if len(sink.created) != 1 { t.Fatalf("created %d items", len(sink.created)) } for _, item := range sink.created { diff --git a/src/pkg/github/review_backlog_selfcheck_test.go b/src/pkg/github/review_backlog_selfcheck_test.go index a2b6b4dad1..82be5c8237 100644 --- a/src/pkg/github/review_backlog_selfcheck_test.go +++ b/src/pkg/github/review_backlog_selfcheck_test.go @@ -65,7 +65,7 @@ func TestReconcileReviewBacklogBlocksSelfVerifiesOnMerge(t *testing.T) { sink := &fakeCloserSink{fakeResolverSink: fakeResolverSink{fakeBacklogSink: fakeBacklogSink{dest: config.ReviewBacklogLinear}}} c := reviewTestClient(t, srv.URL) c.SetReviewBacklogRouting(func() ReviewBacklogRouting { - return ReviewBacklogRouting{Backlog: config.ReviewBacklogConfig{Destination: config.ReviewBacklogLinear}, Sink: sink} + return ReviewBacklogRouting{Backlog: config.ReviewBacklogConfig{Destination: config.ReviewBacklogLinear, MinSeverity: "P3"}, Sink: sink} }) ledger := newReviewBacklogLedger() rec := func(key, file, title string) reviewBacklogFingerprintRecord { @@ -139,7 +139,7 @@ func TestReconcileReviewBacklogBlocksLiftsWhenSinkCannotClose(t *testing.T) { sink := &fakeResolverSink{fakeBacklogSink: fakeBacklogSink{dest: config.ReviewBacklogLinear}} c := reviewTestClient(t, srv.URL) c.SetReviewBacklogRouting(func() ReviewBacklogRouting { - return ReviewBacklogRouting{Backlog: config.ReviewBacklogConfig{Destination: config.ReviewBacklogLinear}, Sink: sink} + return ReviewBacklogRouting{Backlog: config.ReviewBacklogConfig{Destination: config.ReviewBacklogLinear, MinSeverity: "P3"}, Sink: sink} }) ledger := newReviewBacklogLedger() ledger.setFingerprint("o/r", "fp", reviewBacklogFingerprintRecord{Destination: config.ReviewBacklogLinear, ItemID: "id", ItemKey: "ENG-1", BlockedOnPR: 5, BlockState: reviewBacklogBlockBlocked, File: "pkg/deleted.go", Title: "Review backlog (style): prWarnOnce"}) diff --git a/src/pkg/github/review_request_watcher_test.go b/src/pkg/github/review_request_watcher_test.go index 4f12d0e976..05b421f419 100644 --- a/src/pkg/github/review_request_watcher_test.go +++ b/src/pkg/github/review_request_watcher_test.go @@ -497,7 +497,9 @@ func TestReviewRequestWatcherFilesOutOfScopeBacklogOnce(t *testing.T) { if !containsString(payload.Labels, reviewBacklogLabel) { t.Errorf("created issue labels = %v, want %s", payload.Labels, reviewBacklogLabel) } - if !strings.Contains(payload.Body, "PR: #5") || !strings.Contains(payload.Body, "Evidence: `pkg/old.go:") { + // Both fixture findings share the correctness perspective, so + // they collapse into one checklist item (hivecommons/hive#17065). + if !strings.Contains(payload.Body, "PR: #5") || !strings.Contains(payload.Body, "(`pkg/old.go:10`)") || !strings.Contains(payload.Body, "(`pkg/old.go:20`)") { t.Errorf("created issue body did not link PR/evidence: %q", payload.Body) } w.Header().Set("Content-Type", "application/json") @@ -508,7 +510,7 @@ func TestReviewRequestWatcherFilesOutOfScopeBacklogOnce(t *testing.T) { Body string `json:"body"` } _ = json.NewDecoder(r.Body).Decode(&payload) - if !strings.Contains(payload.Body, reviewBacklogSummaryMarker) || !strings.Contains(payload.Body, "#101") || !strings.Contains(payload.Body, "#102") { + if !strings.Contains(payload.Body, reviewBacklogSummaryMarker) || !strings.Contains(payload.Body, "#101") || !strings.Contains(payload.Body, "2 follow-ups") { t.Errorf("summary comment missing filed issues: %q", payload.Body) } w.Header().Set("Content-Type", "application/json") @@ -533,8 +535,8 @@ func TestReviewRequestWatcherFilesOutOfScopeBacklogOnce(t *testing.T) { if reviews != 2 { t.Fatalf("reviews = %d, want 2 re-reviews", reviews) } - if createdIssues != 2 { - t.Fatalf("created backlog issues = %d, want 2 with no duplicates on re-review", createdIssues) + if createdIssues != 1 { + t.Fatalf("created backlog issues = %d, want one collapsed item with no duplicates on re-review", createdIssues) } if prSummaryComments != 1 { t.Fatalf("PR summary comments = %d, want one", prSummaryComments) @@ -714,8 +716,8 @@ func TestReviewRequestWatcher_PerHeadBackstop(t *testing.T) { if !resp.OK || resp.State != ReviewEventRecordVerdict || posts != 1 { t.Fatalf("second review on the same head must record the verdict but post nothing: %+v posts=%d", resp, posts) } - if createdIssues != 2 || prSummaryComments != 1 { - t.Fatalf("suppressed verdict should file capped backlog once: issues=%d summary=%d", createdIssues, prSummaryComments) + if createdIssues != 1 || prSummaryComments != 1 { + t.Fatalf("suppressed verdict should file the backlog once, both findings collapsed into one item: issues=%d summary=%d", createdIssues, prSummaryComments) } if !strings.Contains(resp.Note, "already carries 1 hive review") || !strings.Contains(resp.Note, "--revise") { t.Fatalf("note must explain the cap and the way out: %q", resp.Note) diff --git a/src/pkg/github/write_surface_internal_test.go b/src/pkg/github/write_surface_internal_test.go index 6241e64384..561b18a91f 100644 --- a/src/pkg/github/write_surface_internal_test.go +++ b/src/pkg/github/write_surface_internal_test.go @@ -519,14 +519,16 @@ func TestReviewBacklog_FiledIssuesAndSummaryAudited(t *testing.T) { } c.ProcessReviewRequestsOnce(context.Background()) - rec := assertTypedWrite(t, *recs, AuditActionReviewBacklogIssueFiled, "o/r", 101, 2) - for _, want := range []string{"pr=5", "perspective=correctness", "reused=false", "review_agent=reviewer"} { + // The two fixture findings share a perspective and collapse into one + // item, so one filed entry carrying findings=2 (hivecommons/hive#17065). + rec := assertTypedWrite(t, *recs, AuditActionReviewBacklogIssueFiled, "o/r", 101, 1) + for _, want := range []string{"pr=5", "perspective=correctness", "findings=2", "reused=false", "review_agent=reviewer"} { if !strings.Contains(rec.Detail, want) { t.Errorf("filed-issue detail %q missing %q", rec.Detail, want) } } rec = assertTypedWrite(t, *recs, AuditActionReviewBacklogSummaryPosted, "o/r", 5, 1) - if !strings.Contains(rec.Detail, "issues=2") { - t.Errorf("summary detail %q missing issues=2", rec.Detail) + if !strings.Contains(rec.Detail, "issues=1") { + t.Errorf("summary detail %q missing issues=1", rec.Detail) } } diff --git a/src/pkg/hub/autopick_pool_fallback_test.go b/src/pkg/hub/autopick_pool_fallback_test.go new file mode 100644 index 0000000000..970d7d68c7 --- /dev/null +++ b/src/pkg/hub/autopick_pool_fallback_test.go @@ -0,0 +1,246 @@ +package hub + +import ( + "log/slog" + "net/http" + "net/http/httptest" + "strings" + "testing" + "time" +) + +// Cluster IDs used by the fallback tests. fallbackClusterID stands in for the +// second public pool (lke648397 in production); unregisteredClusterID is a +// pool that has placeholders on disk but no clusters.json entry. +const ( + fallbackClusterID = "lke648397" + secondFallbackCluster = "aks-eu" + unregisteredClusterID = "ghost-cluster" +) + +// placeholderSpec is one available placeholder to seed for a test case. +type placeholderSpec struct { + id string + cluster string +} + +func seedPlaceholders(t *testing.T, specs []placeholderSpec) { + t.Helper() + for _, p := range specs { + if err := saveSaaSHive(&SaaSHive{ID: p.id, Owner: hubAdminUsername, Status: statusAvailable, ClusterID: p.cluster}); err != nil { + t.Fatal(err) + } + } +} + +func newFallbackTestHub() *HubServer { + return &HubServer{ + logger: slog.Default(), + hubSecret: testHubSecret, + saveCh: make(chan struct{}, 1), + clusters: map[string]ClusterConfig{ + defaultClusterID: *dynamicCluster(), + fallbackClusterID: {ID: fallbackClusterID, Name: "lke"}, + secondFallbackCluster: {ID: secondFallbackCluster, Name: "aks"}, + gpuClusterID: {ID: gpuClusterID, Name: "gpu", PullOnly: true}, + }, + } +} + +// TestAutoPickPlaceholderFallback is the table over (preferred pool empty / +// non-empty) x (other pools empty / non-empty) plus the hard pins that must +// never fall back. +func TestAutoPickPlaceholderFallback(t *testing.T) { + tests := []struct { + name string + preferred string + placeholders []placeholderSpec + wantID string + wantPool string + }{ + { + name: "preferred non-empty, others non-empty -> preferred wins", + preferred: defaultClusterID, + placeholders: []placeholderSpec{ + {"oke-1", defaultClusterID}, + {"lke-1", fallbackClusterID}, + {"lke-2", fallbackClusterID}, + }, + wantID: "oke-1", + wantPool: defaultClusterID, + }, + { + name: "preferred empty, others empty -> nothing", + preferred: defaultClusterID, + placeholders: nil, + wantID: "", + wantPool: defaultClusterID, + }, + { + name: "preferred empty, one other pool non-empty -> fall back", + preferred: defaultClusterID, + placeholders: []placeholderSpec{ + {"lke-2", fallbackClusterID}, + {"lke-1", fallbackClusterID}, + }, + wantID: "lke-1", + wantPool: fallbackClusterID, + }, + { + name: "preferred empty, several pools -> most available first", + preferred: defaultClusterID, + placeholders: []placeholderSpec{ + {"aks-1", secondFallbackCluster}, + {"lke-1", fallbackClusterID}, + {"lke-2", fallbackClusterID}, + }, + wantID: "lke-1", + wantPool: fallbackClusterID, + }, + { + name: "preferred empty, equal counts -> tie-break by cluster id", + preferred: defaultClusterID, + placeholders: []placeholderSpec{ + {"lke-1", fallbackClusterID}, + {"aks-1", secondFallbackCluster}, + }, + wantID: "aks-1", + wantPool: secondFallbackCluster, + }, + { + name: "preferred empty, only GPU pool has placeholders -> no fallback onto GPU", + preferred: defaultClusterID, + placeholders: []placeholderSpec{ + {"gpu-1", gpuClusterID}, + }, + wantID: "", + wantPool: defaultClusterID, + }, + { + name: "preferred empty, only unregistered cluster has placeholders -> skipped", + preferred: defaultClusterID, + placeholders: []placeholderSpec{ + {"ghost-1", unregisteredClusterID}, + }, + wantID: "", + wantPool: defaultClusterID, + }, + { + name: "private request: GPU pool empty, public pools full -> stays pinned", + preferred: gpuClusterID, + placeholders: []placeholderSpec{ + {"oke-1", defaultClusterID}, + {"lke-1", fallbackClusterID}, + }, + wantID: "", + wantPool: gpuClusterID, + }, + { + name: "private request: GPU pool non-empty -> GPU placeholder", + preferred: gpuClusterID, + placeholders: []placeholderSpec{ + {"gpu-1", gpuClusterID}, + {"oke-1", defaultClusterID}, + }, + wantID: "gpu-1", + wantPool: gpuClusterID, + }, + } + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + cleanup := helperSetupTempDirs(t) + defer cleanup() + mkUser(t, hubAdminUsername) + seedPlaceholders(t, tc.placeholders) + + s := newFallbackTestHub() + gotID, gotPool := s.autoPickPlaceholder(tc.preferred) + if gotID != tc.wantID || gotPool != tc.wantPool { + t.Errorf("autoPickPlaceholder(%q) = (%q, %q), want (%q, %q)", tc.preferred, gotID, gotPool, tc.wantID, tc.wantPool) + } + }) + } +} + +// TestHandleApproveProvisionPoolFallback drives the handler end to end: a +// public request with an empty default pool is served from another pool and +// the claimed hive keeps that pool's cluster_id; an admin's explicit pick is +// still strict (409 when the chosen placeholder is not available) and a fully +// empty fleet still 409s with a message that names the fallback scope. +func TestHandleApproveProvisionPoolFallback(t *testing.T) { + pending := func(user string) *ProvisionRequest { + return &ProvisionRequest{ + Username: user, Org: "acme", Repos: "repo", PrimaryRepo: "repo", ACMMLevel: 2, + AuthMethod: "public", RequestedAt: time.Now().UTC().Format(time.RFC3339), Status: provisionStatusPending, + } + } + + tests := []struct { + name string + placeholders []placeholderSpec + body string + wantCode int + wantHive string + wantCluster string + wantBodyHas string + }{ + { + name: "auto-pick falls back to the other pool", + placeholders: []placeholderSpec{{"lke-1", fallbackClusterID}}, + body: "", + wantCode: http.StatusOK, + wantHive: "lke-1", + wantCluster: fallbackClusterID, + }, + { + name: "auto-pick with every pool empty -> 409 naming the fallback scope", + placeholders: nil, + body: "", + wantCode: http.StatusConflict, + wantBodyHas: "or any other registered pool", + }, + { + name: "explicit pick of an unavailable placeholder stays strict even though another pool has capacity", + placeholders: []placeholderSpec{{"lke-1", fallbackClusterID}}, + body: `{"hive_id":"oke-missing"}`, + wantCode: http.StatusConflict, + wantBodyHas: "selected placeholder is not available", + }, + } + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + cleanup := helperSetupTempDirs(t) + defer cleanup() + mkUser(t, hubAdminUsername) + seedPlaceholders(t, tc.placeholders) + if err := saveProvisionRequest(pending("bob")); err != nil { + t.Fatal(err) + } + + s := newFallbackTestHub() + rec := httptest.NewRecorder() + req := setPathValue(reqWithUser(http.MethodPut, "/approve-prov", tc.body, hubAdminUsername), "username", "bob") + s.handleApproveProvision(rec, req) + + if rec.Code != tc.wantCode { + t.Fatalf("status = %d, want %d (body=%s)", rec.Code, tc.wantCode, rec.Body.String()) + } + if tc.wantBodyHas != "" && !strings.Contains(rec.Body.String(), tc.wantBodyHas) { + t.Errorf("body = %s, want it to contain %q", rec.Body.String(), tc.wantBodyHas) + } + if tc.wantHive == "" { + return + } + got := loadSaaSHive(tc.wantHive) + if got == nil { + t.Fatalf("hive %q missing after approve", tc.wantHive) + } + if got.Owner != "bob" || got.Status != statusAssigned { + t.Errorf("hive %q owner/status = %q/%q, want bob/%s", tc.wantHive, got.Owner, got.Status, statusAssigned) + } + if got.ClusterID != tc.wantCluster { + t.Errorf("hive %q ClusterID = %q, want %q (fallback must keep the placeholder's real pool)", tc.wantHive, got.ClusterID, tc.wantCluster) + } + }) + } +} diff --git a/src/pkg/hub/saas_provisioning.go b/src/pkg/hub/saas_provisioning.go index 28cec59029..ae46e7d3a7 100644 --- a/src/pkg/hub/saas_provisioning.go +++ b/src/pkg/hub/saas_provisioning.go @@ -613,8 +613,11 @@ func (s *HubServer) handleApproveProvision(w http.ResponseWriter, r *http.Reques // Approving now ASSIGNS an available placeholder instead of just bumping // quota for a manual provision. Pick the pool from the request's auth_method - // (private → the heartbeat-only cluster / GPU pool, otherwise → the hub-reachable cluster / public pool). If no - // placeholder is available in that pool, tell the admin to provision more. + // (private → the heartbeat-only cluster / GPU pool, otherwise → the hub-reachable cluster / public pool). + // The public preference is soft: when that pool is empty, Auto-pick falls + // back to any other registered non-GPU pool with a placeholder (see + // autoPickPlaceholder). Only when every eligible pool is empty does the + // admin get told to provision more. pool := poolClusterForAuthMethod(pr.AuthMethod) hiveID := strings.TrimSpace(approveBody.HiveID) if hiveID != "" { @@ -626,10 +629,19 @@ func (s *HubServer) handleApproveProvision(w http.ResponseWriter, r *http.Reques return } } else { - hiveID = findAvailablePlaceholder(pool) + var pickedPool string + hiveID, pickedPool = s.autoPickPlaceholder(pool) + if hiveID != "" && pickedPool != pool { + s.logger.Info(fmt.Sprintf("approve: pool %s empty, falling back to %s", pool, pickedPool), "target", targetUsername, "hive", hiveID) + pool = pickedPool + } } if hiveID == "" { - http.Error(w, fmt.Sprintf(`{"error":"no available placeholder hive in pool %q — provision more placeholders"}`, pool), http.StatusConflict) + scope := "" + if pool != gpuClusterID { + scope = " or any other registered pool" + } + http.Error(w, fmt.Sprintf(`{"error":"no available placeholder hive in pool %q%s — provision more placeholders"}`, pool, scope), http.StatusConflict) return } @@ -904,6 +916,69 @@ func findAvailablePlaceholder(clusterID string) string { return "" } +// autoPickPlaceholder implements Auto-pick for handleApproveProvision: it +// returns the ID of an available placeholder and the pool it came from. +// +// The preferred pool is tried first. If it is empty AND the preference is +// soft (the public/default pool), the pick falls back to any OTHER cluster +// registered in clusters.json that has an available placeholder — ordered by +// most available first, tie-broken by cluster ID, so the choice is +// deterministic. Two pins stay hard and never fall back: a private request +// stays on the GPU pool (its spokes are heartbeat-only and the pool is a +// tenancy boundary), and the GPU pool is never used to satisfy a public +// request. Returns ("", preferredPool) when no eligible pool has a +// placeholder. +func (s *HubServer) autoPickPlaceholder(preferredPool string) (hiveID, pool string) { + if id := findAvailablePlaceholder(preferredPool); id != "" { + return id, preferredPool + } + if preferredPool == gpuClusterID { + return "", preferredPool + } + + type poolCount struct { + id string + count int + first string + } + byPool := map[string]*poolCount{} + for _, h := range listSaaSHives() { + if h.Status != statusAvailable || !isHubAdmin(h.Owner) { + continue + } + cid := clusterIDForHive(&h) + if cid == preferredPool || cid == gpuClusterID { + continue + } + if _, registered := s.clusters[cid]; !registered { + continue + } + pc := byPool[cid] + if pc == nil { + pc = &poolCount{id: cid, first: h.ID} + byPool[cid] = pc + } + pc.count++ + if h.ID < pc.first { + pc.first = h.ID + } + } + if len(byPool) == 0 { + return "", preferredPool + } + candidates := make([]*poolCount, 0, len(byPool)) + for _, pc := range byPool { + candidates = append(candidates, pc) + } + sort.Slice(candidates, func(i, j int) bool { + if candidates[i].count != candidates[j].count { + return candidates[i].count > candidates[j].count + } + return candidates[i].id < candidates[j].id + }) + return candidates[0].first, candidates[0].id +} + // AvailablePlaceholder is one row of the approve-picker dropdown: an available // placeholder hive the admin can assign a provision request to. type AvailablePlaceholder struct { diff --git a/src/pkg/knowledge/filestore.go b/src/pkg/knowledge/filestore.go index 19525d1c8c..2840ad0602 100644 --- a/src/pkg/knowledge/filestore.go +++ b/src/pkg/knowledge/filestore.go @@ -58,11 +58,13 @@ type filePage struct { Path string ModTime time.Time Embedding []float64 + Scope *FactScope // Lifecycle frontmatter (#11102); see resolveLifecycleState for defaults. State LifecycleState Supersedes string SupersededBy string + Author string } // NewFileStore creates a store that indexes markdown files under rootDir. @@ -211,6 +213,10 @@ func (s *FileStore) reindex() { page.State = parsed.state page.Supersedes = parsed.supersedes page.SupersededBy = parsed.supersededBy + if !parsed.scope.IsZero() { + page.Scope = parsed.scope + } + page.Author = parsed.author pages[slug] = page return nil @@ -543,6 +549,8 @@ type parsedObsidianFile struct { state LifecycleState supersedes string supersededBy string + scope *FactScope + author string } var wikilinkRe = regexp.MustCompile(`\[\[([^\]|]+)(?:\|[^\]]+)?\]\]`) @@ -573,8 +581,33 @@ func parseObsidianFileDetailed(content string, fallbackTitle string) parsedObsid frontmatter := content[4 : 4+endIdx] parsed.body = strings.TrimSpace(content[4+endIdx+4:]) + // The parser is line-oriented and trims indentation, so a nested + // `scope:` block is recognised by state: once "scope:" is seen, the + // keys paths/labels/lanes belong to it until the next unrelated key. + inScope := false for _, line := range strings.Split(frontmatter, "\n") { line = strings.TrimSpace(line) + if line == "scope:" { + inScope = true + if parsed.scope == nil { + parsed.scope = &FactScope{} + } + continue + } + if inScope { + if consumed := parsed.scope.setFromLine(line); consumed { + continue + } + if strings.HasPrefix(line, "- ") || line == "" { + // Block-list items are not supported inside scope: + // (documented); skip them rather than let them leak + // into tags. + continue + } + if strings.Contains(line, ":") { + inScope = false + } + } if strings.HasPrefix(line, "title:") { parsed.title = strings.TrimSpace(strings.TrimPrefix(line, "title:")) parsed.title = strings.Trim(parsed.title, "\"'") @@ -597,6 +630,10 @@ func parseObsidianFileDetailed(content string, fallbackTitle string) parsedObsid if strings.HasPrefix(line, "superseded_by:") { parsed.supersededBy = strings.Trim(strings.TrimSpace(strings.TrimPrefix(line, "superseded_by:")), "\"'") } + if strings.HasPrefix(line, "author:") || strings.HasPrefix(line, "owner:") { + _, value, _ := strings.Cut(line, ":") + parsed.author = strings.Trim(strings.TrimSpace(value), "\"'") + } if strings.HasPrefix(line, "source:") { parsed.source = strings.Trim(strings.TrimSpace(strings.TrimPrefix(line, "source:")), "\"'") } @@ -691,8 +728,10 @@ func (p filePage) effectiveLayer() LayerType { // applyLifecycle copies the page's lifecycle and TOC metadata onto f, defaulting // legacy pages without a recorded state to approved. func (p filePage) applyLifecycle(f *Fact) { + f.Scope = p.Scope f.Supersedes = p.Supersedes f.SupersededBy = p.SupersededBy + f.Author = p.Author f.State = resolveLifecycleState(p.State, p.Status, p.SupersededBy) f.Updated = p.ModTime f.BodySize = len(p.Body) diff --git a/src/pkg/knowledge/knowledge_coverage_test.go b/src/pkg/knowledge/knowledge_coverage_test.go index b3403f1dcb..6c7fa69ba6 100644 --- a/src/pkg/knowledge/knowledge_coverage_test.go +++ b/src/pkg/knowledge/knowledge_coverage_test.go @@ -535,7 +535,7 @@ func TestPrimer_ExpandWithGraph(t *testing.T) { p.SetGraphStore(gs) facts := []Fact{{Slug: "seed", Title: "Seed Fact", Confidence: 0.9, Layer: LayerProject}} - expanded := p.expandWithGraph(facts, nil) + expanded := p.expandWithGraph(facts, nil, KickContext{}) if len(expanded) < 2 { t.Fatalf("expected graph expansion to add related fact, got %d facts", len(expanded)) } @@ -553,7 +553,7 @@ func TestPrimer_ExpandWithGraph(t *testing.T) { func TestPrimer_ExpandWithGraph_NoGraph(t *testing.T) { p := NewPrimer(nil, PrimerConfig{MaxFacts: 25}, covLogger()) facts := []Fact{{Slug: "a"}} - if got := p.expandWithGraph(facts, nil); len(got) != 1 { + if got := p.expandWithGraph(facts, nil, KickContext{}); len(got) != 1 { t.Errorf("expected passthrough without graph, got %d", len(got)) } } diff --git a/src/pkg/knowledge/lifecycle.go b/src/pkg/knowledge/lifecycle.go index 4aa20f6b33..8ac574db3d 100644 --- a/src/pkg/knowledge/lifecycle.go +++ b/src/pkg/knowledge/lifecycle.go @@ -101,10 +101,19 @@ func lifecycleAllowed(st LifecycleState, include []LifecycleState) bool { // is listed in include. With a nil/empty include only approved (current) // knowledge survives. Retained facts have State populated. func FilterByLifecycle(facts []Fact, include []LifecycleState) []Fact { + return FilterByLifecycleFor(facts, include, nil) +} + +// FilterByLifecycleFor is FilterByLifecycle that additionally keeps draft +// facts authored by one of draftAuthors (#17076). It is the kick-path filter: +// the scheduler lists the kicked agent's identities when that agent's +// knowledge.agent_scopes entry opts into drafts, so an agent is primed with +// the drafts it wrote while every other draft is still excluded. +func FilterByLifecycleFor(facts []Fact, include []LifecycleState, draftAuthors []string) []Fact { out := make([]Fact, 0, len(facts)) for _, f := range facts { st := f.EffectiveState() - if !lifecycleAllowed(st, include) { + if !lifecycleAllowedFor(f, st, include, draftAuthors) { continue } f.State = st @@ -113,6 +122,32 @@ func FilterByLifecycle(facts []Fact, include []LifecycleState) []Fact { return out } +// lifecycleAllowedFor is lifecycleAllowed plus the author-matched draft rule +// of FilterByLifecycleFor. +func lifecycleAllowedFor(f Fact, st LifecycleState, include []LifecycleState, draftAuthors []string) bool { + if lifecycleAllowed(st, include) { + return true + } + return st == StateDraft && DraftAuthoredBy(f, draftAuthors) +} + +// DraftAuthoredBy reports whether f carries an author and that author is one +// of authors (case-insensitive, surrounding space ignored). An authorless +// fact never matches, so drafts from sources that record no author stay +// hidden. +func DraftAuthoredBy(f Fact, authors []string) bool { + author := strings.TrimSpace(f.Author) + if author == "" { + return false + } + for _, a := range authors { + if strings.EqualFold(strings.TrimSpace(a), author) { + return true + } + } + return false +} + // SetLifecycleState records state on the fact identified by slug by rewriting // its frontmatter. Setting a state other than superseded clears any // superseded_by link so the fact is not implicitly re-superseded on load. diff --git a/src/pkg/knowledge/primer.go b/src/pkg/knowledge/primer.go index ab6f43494f..ff9ed0e4b0 100644 --- a/src/pkg/knowledge/primer.go +++ b/src/pkg/knowledge/primer.go @@ -97,9 +97,20 @@ func (p *Primer) Prime(ctx context.Context, filePaths []string, keywords []strin // applied on top of the primer's lifecycle filter, so it can only narrow what // the agent is shown, and graph expansion never pulls in an out-of-scope fact. func (p *Primer) PrimeScoped(ctx context.Context, scope *TOCScope, filePaths []string, keywords []string) *PrimedKnowledge { + return p.PrimeForKick(ctx, scope, KickContext{Paths: filePaths}, keywords) +} + +// PrimeForKick is PrimeScoped with the kick's context (#17045): the lane, the +// labels of the issues being primed and, when the caller knows them, the file +// paths being touched. Facts that carry a `scope:` are kept only when the +// context matches one of its dimensions (FactScope.Admits); unscoped facts are +// selected by relevance exactly as before. kc.Paths also feed the search query, +// as filePaths did in PrimeScoped. The count of relevant facts the context +// excluded is reported in PrimedKnowledge.ScopedOut. +func (p *Primer) PrimeForKick(ctx context.Context, scope *TOCScope, kc KickContext, keywords []string) *PrimedKnowledge { start := time.Now() - query := buildQuery(filePaths, keywords) + query := buildQuery(kc.Paths, keywords) if query == "" { return &PrimedKnowledge{} } @@ -141,10 +152,17 @@ func (p *Primer) PrimeScoped(ctx context.Context, scope *TOCScope, filePaths []s // Filter after the precedence merge so a higher-precedence layer that // deprecates a slug hides it rather than surfacing a lower layer's copy. - merged := FilterByLifecycle(p.mergeWithPrecedence(allFacts), p.config.IncludeStates) + // An agent that opted into its own drafts (TOCScope.DraftAuthors, #17076) + // gets those on top of what the primer's lifecycle filter admits. + var draftAuthors []string + if scope != nil { + draftAuthors = scope.DraftAuthors + } + merged := FilterByLifecycleFor(p.mergeWithPrecedence(allFacts), p.config.IncludeStates, draftAuthors) if scope != nil { merged = scope.Filter(merged) } + merged, scopedOut := FilterByKickContext(merged, kc) reranked := p.rerankFisherRao(query, merged) prioritized := p.applyPriority(reranked) @@ -152,11 +170,12 @@ func (p *Primer) PrimeScoped(ctx context.Context, scope *TOCScope, filePaths []s prioritized = prioritized[:p.config.MaxFacts] } - prioritized = p.expandWithGraph(prioritized, scope) + prioritized = p.expandWithGraph(prioritized, scope, kc) elapsed := time.Since(start).Milliseconds() p.logger.Info("knowledge primed", "facts", len(prioritized), + "scoped_out", scopedOut, "http_layers", len(p.layers), "file_stores", len(p.fileStores), "graph", p.graphStore != nil, @@ -182,6 +201,7 @@ func (p *Primer) PrimeScoped(ctx context.Context, scope *TOCScope, filePaths []s Hints: hints, QueryTime: elapsed, MaxBytes: p.config.MaxBytes, + ScopedOut: scopedOut, } } @@ -275,8 +295,9 @@ const graphExpansionConfidenceDecay = 0.8 // expandWithGraph performs one-hop traversal from each primed fact's slug, // pulling in related facts that aren't already in the result set. A non-nil -// scope excludes related facts outside it. -func (p *Primer) expandWithGraph(facts []Fact, scope *TOCScope) []Fact { +// scope excludes related facts outside it, and a related fact's own `scope:` +// must admit the kick context. +func (p *Primer) expandWithGraph(facts []Fact, scope *TOCScope, kc KickContext) []Fact { if p.graphStore == nil || len(facts) == 0 { return facts } @@ -302,12 +323,19 @@ func (p *Primer) expandWithGraph(facts []Fact, scope *TOCScope) []Fact { for _, ls := range p.fileStores { if relFact, err := ls.store.ReadPage(relSlug); err == nil { relFact.Layer = ls.layerType - if !lifecycleAllowed(relFact.EffectiveState(), p.config.IncludeStates) { + var draftAuthors []string + if scope != nil { + draftAuthors = scope.DraftAuthors + } + if !lifecycleAllowedFor(*relFact, relFact.EffectiveState(), p.config.IncludeStates, draftAuthors) { break } if scope != nil && !scope.InScope(*relFact) { break } + if !relFact.Scope.Admits(kc) { + break + } relFact.Confidence *= graphExpansionConfidenceDecay expanded = append(expanded, *relFact) break diff --git a/src/pkg/knowledge/primer_render.go b/src/pkg/knowledge/primer_render.go index 6175681214..64f0000af0 100644 --- a/src/pkg/knowledge/primer_render.go +++ b/src/pkg/knowledge/primer_render.go @@ -72,6 +72,7 @@ func primerMaxBytes(n int) int { // reader of the kick knows the primer was bounded rather than exhaustive. func (pk *PrimedKnowledge) Render() (string, PrimerOmitted) { var omitted PrimerOmitted + pk.rendered = nil if len(pk.Facts) == 0 { return "", omitted } @@ -109,6 +110,7 @@ func (pk *PrimedKnowledge) Render() (string, PrimerOmitted) { headingWritten = true } b.WriteString(entry) + pk.rendered = append(pk.rendered, f.Slug) remaining -= need } } @@ -144,11 +146,15 @@ func (pk *PrimedKnowledge) Render() (string, PrimerOmitted) { return b.String(), omitted } -// renderPrimerFact renders one fact as a list entry: title, optional -// confidence and source, then the body indented beneath it. +// renderPrimerFact renders one fact as a list entry: title, a "(draft)" +// marker for uncurated facts (#17076), optional confidence and source, then +// the body indented beneath it. func renderPrimerFact(f Fact) string { var b strings.Builder b.WriteString("- **" + f.Title + "**") + if f.EffectiveState() == StateDraft { + b.WriteString(" (draft)") + } if f.ConfidenceScored && f.Confidence < 1.0 { b.WriteString(" (confidence: " + formatConfidence(f.Confidence) + ")") } diff --git a/src/pkg/knowledge/primer_rendered_slugs_test.go b/src/pkg/knowledge/primer_rendered_slugs_test.go new file mode 100644 index 0000000000..9d3eaefb9f --- /dev/null +++ b/src/pkg/knowledge/primer_rendered_slugs_test.go @@ -0,0 +1,40 @@ +package knowledge + +import ( + "reflect" + "testing" +) + +// RenderedSlugs (hivecommons/hive#17052) tells the mid-task advisor which +// entries the kick really carried, so it never re-sends a capped-out one and +// never counts a capped-out one as already delivered. + +func TestPrimerRenderedSlugs_TracksKeptFactsOnly(t *testing.T) { + pk := &PrimedKnowledge{Facts: renderFacts(20, 280), MaxBytes: 2048} + if pk.RenderedSlugs() != nil { + t.Fatal("slugs before Render should be nil") + } + _, omitted := pk.Render() + got := pk.RenderedSlugs() + if len(got)+omitted.Facts != len(pk.Facts) || len(got) == 0 { + t.Fatalf("rendered %d + omitted %d != %d", len(got), omitted.Facts, len(pk.Facts)) + } + var want []string + for _, f := range pk.Facts[:len(got)] { + want = append(want, f.Slug) + } + if !reflect.DeepEqual(got, want) { + t.Errorf("slugs = %v, want %v", got, want) + } + got[0] = "mutated" + if pk.RenderedSlugs()[0] == "mutated" { + t.Error("RenderedSlugs must return a copy") + } + + // A second Render starts the list over instead of appending. + pk.MaxBytes = 1 << 20 + pk.Render() + if n := len(pk.RenderedSlugs()); n != len(pk.Facts) { + t.Errorf("uncapped re-render kept %d slugs, want %d", n, len(pk.Facts)) + } +} diff --git a/src/pkg/knowledge/scope.go b/src/pkg/knowledge/scope.go new file mode 100644 index 0000000000..048e501162 --- /dev/null +++ b/src/pkg/knowledge/scope.go @@ -0,0 +1,168 @@ +package knowledge + +import ( + "path" + "strings" +) + +// FactScope says where a fact applies (hivecommons/hive#17045). It is the +// frontmatter `scope:` block of a knowledge entry: +// +// scope: +// paths: [src/scripts/**, .github/scripts/integration-governance.cjs] +// labels: [area/ci] +// lanes: [developer, reviewer] +// +// Each dimension is a list; an empty list places no constraint on that +// dimension. A fact with no scope at all applies everywhere and is selected by +// relevance alone, exactly as before scopes existed. +type FactScope struct { + // Paths are repo-relative globs; "**" matches any number of segments. + Paths []string `json:"paths,omitempty"` + // Labels are issue labels, compared case-insensitively. + Labels []string `json:"labels,omitempty"` + // Lanes are base agent / lane names, compared case-insensitively. + Lanes []string `json:"lanes,omitempty"` +} + +// IsZero reports whether the scope constrains nothing. +func (s *FactScope) IsZero() bool { + return s == nil || (len(s.Paths) == 0 && len(s.Labels) == 0 && len(s.Lanes) == 0) +} + +// KickContext is what the primer knows about the work a kick is for. The +// scheduler fills Lane and Labels from the lane name and the primed issues; +// Paths is filled only by callers that know which files are being touched. +type KickContext struct { + Lane string + Labels []string + Paths []string +} + +// IsZero reports whether the context carries nothing to match on. +func (kc KickContext) IsZero() bool { + return kc.Lane == "" && len(kc.Labels) == 0 && len(kc.Paths) == 0 +} + +// Admits reports whether a fact carrying scope s may be shown for kc. An +// unscoped fact is always admitted. A scoped fact is admitted when at least one +// declared dimension matches — the dimensions are OR-ed, so an entry scoped to +// both a path glob and a label surfaces for either trigger. A declared +// dimension the context knows nothing about (no paths at kick time, say) simply +// cannot match; it does not admit by default, because the point of a scope is +// that the fact is not paid for on every kick. +func (s *FactScope) Admits(kc KickContext) bool { + if s.IsZero() { + return true + } + if kc.Lane != "" && containsFold(s.Lanes, kc.Lane) { + return true + } + for _, l := range kc.Labels { + if containsFold(s.Labels, l) { + return true + } + } + for _, p := range kc.Paths { + for _, pattern := range s.Paths { + if scopeGlobMatch(pattern, p) { + return true + } + } + } + return false +} + +// FilterByKickContext drops facts whose scope does not admit kc and reports how +// many it dropped. Unscoped facts pass unchanged; a zero context drops every +// scoped fact. +func FilterByKickContext(facts []Fact, kc KickContext) ([]Fact, int) { + kept := facts[:0:0] + dropped := 0 + for _, f := range facts { + if f.Scope.Admits(kc) { + kept = append(kept, f) + continue + } + dropped++ + } + return kept, dropped +} + +// scopeGlobMatch matches a repo-relative path against a glob whose segments +// follow path.Match, with "**" matching zero or more whole segments. Both sides +// are normalised to forward slashes without a leading "./". +func scopeGlobMatch(pattern, p string) bool { + pattern = normaliseScopePath(pattern) + p = normaliseScopePath(p) + if pattern == "" || p == "" { + return false + } + return matchSegments(strings.Split(pattern, "/"), strings.Split(p, "/")) +} + +func normaliseScopePath(s string) string { + s = strings.ReplaceAll(strings.TrimSpace(s), "\\", "/") + s = strings.TrimPrefix(s, "./") + return strings.Trim(s, "/") +} + +func matchSegments(pattern, segs []string) bool { + for len(pattern) > 0 { + if pattern[0] == "**" { + // "**" at the end matches whatever remains, including nothing. + if len(pattern) == 1 { + return true + } + for i := 0; i <= len(segs); i++ { + if matchSegments(pattern[1:], segs[i:]) { + return true + } + } + return false + } + if len(segs) == 0 { + return false + } + if ok, err := path.Match(pattern[0], segs[0]); err != nil || !ok { + return false + } + pattern, segs = pattern[1:], segs[1:] + } + return len(segs) == 0 +} + +// parseScopeList parses the inline-list value of one scope key ("[a, b]" or a +// bare "a, b"); entries are trimmed and unquoted, empties dropped. +func parseScopeList(value string) []string { + value = strings.TrimSpace(value) + value = strings.TrimSuffix(strings.TrimPrefix(value, "["), "]") + var out []string + for _, item := range strings.Split(value, ",") { + item = strings.Trim(strings.TrimSpace(item), "\"'") + if item != "" { + out = append(out, item) + } + } + return out +} + +// setFromLine applies one trimmed frontmatter line inside a `scope:` block and +// reports whether the line was a scope key. +func (s *FactScope) setFromLine(line string) bool { + key, value, ok := strings.Cut(line, ":") + if !ok { + return false + } + switch strings.TrimSpace(key) { + case "paths": + s.Paths = parseScopeList(value) + case "labels": + s.Labels = parseScopeList(value) + case "lanes": + s.Lanes = parseScopeList(value) + default: + return false + } + return true +} diff --git a/src/pkg/knowledge/scope_test.go b/src/pkg/knowledge/scope_test.go new file mode 100644 index 0000000000..87f7d1050c --- /dev/null +++ b/src/pkg/knowledge/scope_test.go @@ -0,0 +1,229 @@ +package knowledge + +import ( + "io" + "log/slog" + "os" + "path/filepath" + "strings" + "testing" +) + +func TestScopeGlobMatch(t *testing.T) { + tests := []struct { + pattern, path string + want bool + }{ + {"src/scripts/**", "src/scripts/check.sh", true}, + {"src/scripts/**", "src/scripts/sub/deep.sh", true}, + {"src/scripts/**", "src/scripts", true}, + {"src/scripts/**", "src/script.go", false}, + {"src/**/*.go", "src/pkg/knowledge/primer.go", true}, + {"src/**/*.go", "src/main.go", true}, + {"src/**/*.go", "src/pkg/knowledge/README.md", false}, + {"**/server.go", "src/pkg/hub/server.go", true}, + {"**/server.go", "server.go", true}, + {".github/scripts/integration-governance.cjs", ".github/scripts/integration-governance.cjs", true}, + {".github/scripts/integration-governance.cjs", ".github/scripts/other.cjs", false}, + {"./src/go.work", "src/go.work", true}, + {"src/go.work", "./src/go.work/", true}, + {"", "src/x", false}, + {"src/**", "", false}, + } + for _, tc := range tests { + if got := scopeGlobMatch(tc.pattern, tc.path); got != tc.want { + t.Errorf("scopeGlobMatch(%q, %q) = %v, want %v", tc.pattern, tc.path, got, tc.want) + } + } +} + +func TestFactScopeAdmits(t *testing.T) { + scoped := &FactScope{ + Paths: []string{"src/scripts/**"}, + Labels: []string{"area/ci"}, + Lanes: []string{"reviewer"}, + } + tests := []struct { + name string + scope *FactScope + kc KickContext + want bool + }{ + {"nil scope admits anything", nil, KickContext{}, true}, + {"empty scope admits anything", &FactScope{}, KickContext{Lane: "x"}, true}, + {"scoped fact, empty context", scoped, KickContext{}, false}, + {"lane match, case-insensitive", scoped, KickContext{Lane: "Reviewer"}, true}, + {"lane mismatch", scoped, KickContext{Lane: "developer"}, false}, + {"label match among others", scoped, KickContext{Labels: []string{"kind/bug", "AREA/CI"}}, true}, + {"label mismatch", scoped, KickContext{Labels: []string{"kind/bug"}}, false}, + {"path match", scoped, KickContext{Paths: []string{"src/scripts/x.sh"}}, true}, + {"path mismatch", scoped, KickContext{Paths: []string{"src/pkg/x.go"}}, false}, + {"dimensions are OR-ed", scoped, KickContext{Lane: "developer", Labels: []string{"area/ci"}}, true}, + {"paths-only scope cannot match a lane", &FactScope{Paths: []string{"src/**"}}, KickContext{Lane: "reviewer"}, false}, + } + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + if got := tc.scope.Admits(tc.kc); got != tc.want { + t.Fatalf("Admits = %v, want %v", got, tc.want) + } + }) + } +} + +func TestFilterByKickContext(t *testing.T) { + facts := []Fact{ + {Slug: "open"}, + {Slug: "ci", Scope: &FactScope{Labels: []string{"area/ci"}}}, + {Slug: "scripts", Scope: &FactScope{Paths: []string{"src/scripts/**"}}}, + } + tests := []struct { + name string + kc KickContext + wantSlugs []string + wantDropped int + }{ + {"zero context keeps only unscoped", KickContext{}, []string{"open"}, 2}, + {"label admits the ci fact", KickContext{Labels: []string{"area/ci"}}, []string{"open", "ci"}, 1}, + {"paths admit the scripts fact", KickContext{Paths: []string{"src/scripts/a.sh"}}, []string{"open", "scripts"}, 1}, + } + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + kept, dropped := FilterByKickContext(facts, tc.kc) + if dropped != tc.wantDropped { + t.Fatalf("dropped = %d, want %d", dropped, tc.wantDropped) + } + var slugs []string + for _, f := range kept { + slugs = append(slugs, f.Slug) + } + if strings.Join(slugs, ",") != strings.Join(tc.wantSlugs, ",") { + t.Fatalf("kept = %v, want %v", slugs, tc.wantSlugs) + } + }) + } +} + +func TestParseObsidianFile_ScopeBlock(t *testing.T) { + tests := []struct { + name string + content string + wantScope *FactScope + wantTags []string + }{ + { + name: "inline lists, keys after scope still parsed", + content: "---\ntitle: T\nscope:\n paths: [src/scripts/**, .github/x.cjs]\n labels: ['area/ci']\n lanes: [reviewer]\ntags: [repo:org/name, ci]\n---\nbody", + wantScope: &FactScope{ + Paths: []string{"src/scripts/**", ".github/x.cjs"}, + Labels: []string{"area/ci"}, + Lanes: []string{"reviewer"}, + }, + wantTags: []string{"repo:org/name", "ci"}, + }, + { + name: "no scope block", + content: "---\ntitle: T\ntags: [a]\n---\nbody", + wantScope: nil, + wantTags: []string{"a"}, + }, + { + name: "all-empty scope collapses to nil", + content: "---\nscope:\n paths: []\n labels: []\n lanes: []\n---\nbody", + wantScope: nil, + }, + { + name: "block list items inside scope do not leak into tags", + content: "---\ntags: [a]\nscope:\n paths:\n - src/x\n lanes: [dev]\n---\nbody", + wantScope: &FactScope{Lanes: []string{"dev"}}, + wantTags: []string{"a"}, + }, + { + name: "scope keys outside a scope block are ignored", + content: "---\npaths: [src/x]\nlanes: [dev]\n---\nbody", + wantScope: nil, + }, + } + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + parsed := parseObsidianFileDetailed(tc.content, "fallback") + got := parsed.scope + if got.IsZero() { + got = nil + } + if (got == nil) != (tc.wantScope == nil) { + t.Fatalf("scope = %+v, want %+v", got, tc.wantScope) + } + if got != nil { + if strings.Join(got.Paths, "|") != strings.Join(tc.wantScope.Paths, "|") || + strings.Join(got.Labels, "|") != strings.Join(tc.wantScope.Labels, "|") || + strings.Join(got.Lanes, "|") != strings.Join(tc.wantScope.Lanes, "|") { + t.Fatalf("scope = %+v, want %+v", got, tc.wantScope) + } + } + if strings.Join(parsed.tags, "|") != strings.Join(tc.wantTags, "|") { + t.Fatalf("tags = %v, want %v", parsed.tags, tc.wantTags) + } + }) + } +} + +func TestPrimeForKick_ScopedEntries(t *testing.T) { + dir := t.TempDir() + write := func(name, content string) { + t.Helper() + if err := os.WriteFile(filepath.Join(dir, name), []byte(content), 0o644); err != nil { + t.Fatal(err) + } + } + write("repin.md", "---\ntitle: Repin trusted scripts tree\ntype: gotcha\nlayer: project\nscope:\n paths: [src/scripts/**]\n labels: [area/ci]\n---\nEditing src/scripts requires a repin of the trusted scripts tree.") + write("workspace.md", "---\ntitle: Two-module workspace for scripts\ntype: reference\nlayer: project\n---\nsrc is a two-module Go workspace; scripts live beside it.") + + logger := slog.New(slog.NewTextHandler(io.Discard, nil)) + store, err := NewFileStore(dir, "repo-knowledge", logger) + if err != nil { + t.Fatal(err) + } + p := NewPrimer(nil, PrimerConfig{}, logger) + p.AddFileStore("repo-knowledge", store, LayerProject) + + keywords := []string{"scripts", "trusted", "repin", "workspace"} + has := func(pk *PrimedKnowledge, slug string) bool { + for _, f := range pk.Facts { + if f.Slug == slug { + return true + } + } + return false + } + + tests := []struct { + name string + kc KickContext + wantRepin bool + wantScopedOut int + }{ + {"kick without matching context hides the scoped entry", KickContext{Lane: "developer"}, false, 1}, + {"label admits it", KickContext{Lane: "developer", Labels: []string{"area/ci"}}, true, 0}, + {"path admits it", KickContext{Paths: []string{"src/scripts/x.sh"}}, true, 0}, + } + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + pk := p.PrimeForKick(t.Context(), nil, tc.kc, keywords) + if !has(pk, "workspace") { + t.Fatalf("unscoped entry must always be primed; got %+v", pk.Facts) + } + if has(pk, "repin") != tc.wantRepin { + t.Fatalf("repin primed = %v, want %v", !tc.wantRepin, tc.wantRepin) + } + if pk.ScopedOut != tc.wantScopedOut { + t.Fatalf("ScopedOut = %d, want %d", pk.ScopedOut, tc.wantScopedOut) + } + }) + } + + // PrimeScoped's file paths double as the kick's paths. + pk := p.PrimeScoped(t.Context(), nil, []string{"src/scripts/x.sh"}, keywords) + if !has(pk, "repin") { + t.Fatalf("PrimeScoped with a matching file path should admit the scoped entry; got %+v", pk.Facts) + } +} diff --git a/src/pkg/knowledge/toc.go b/src/pkg/knowledge/toc.go index cc88cd653b..d8b1b2b054 100644 --- a/src/pkg/knowledge/toc.go +++ b/src/pkg/knowledge/toc.go @@ -65,6 +65,26 @@ type TOCScope struct { // IncludeStates admits non-approved lifecycle states; approved entries are // always visible. IncludeStates []LifecycleState + // DraftAuthors lets the kick primer carry draft facts written by one of + // these identities even though the primer itself admits approved facts + // only (#17076). The scheduler sets it from the kicked agent's name, its + // base agent and the hive's owner logins when the agent's agent_scopes + // entry lists draft in include_states. TOC and API reads leave it empty. + DraftAuthors []string +} + +// ListsDraft reports whether an include_states config list opts into drafts +// explicitly, via "draft" or "all". An empty list does not: AgentScope treats +// it as "defer to the request or primer", which never admits drafts on the +// kick path. +func ListsDraft(includeStates []string) bool { + for _, st := range includeStates { + st = strings.ToLower(strings.TrimSpace(st)) + if st == string(StateDraft) || st == "all" { + return true + } + } + return false } // AgentScope builds the scope an agent is bound to by knowledge.agent_scopes diff --git a/src/pkg/knowledge/types.go b/src/pkg/knowledge/types.go index 483a87710a..b692372283 100644 --- a/src/pkg/knowledge/types.go +++ b/src/pkg/knowledge/types.go @@ -268,8 +268,12 @@ type Fact struct { Layer LayerType `json:"layer"` Sources []Source `json:"sources,omitempty"` Related []string `json:"related,omitempty"` - UsageCount int `json:"usage_count"` - LastUsed time.Time `json:"last_used,omitempty"` + // Author is the entry's `author:` (or `owner:`) frontmatter: the agent or + // person who wrote it. The kick primer uses it to let a draft reach the + // agent that owns it (#17076); empty for sources that record no author. + Author string `json:"author,omitempty"` + UsageCount int `json:"usage_count"` + LastUsed time.Time `json:"last_used,omitempty"` // State is the lifecycle state (draft, approved, deprecated, superseded). // Empty means the fact predates lifecycle states; see EffectiveState. @@ -282,6 +286,10 @@ type Fact struct { SupersededBy string `json:"superseded_by,omitempty"` Phase FactPhase `json:"phase,omitempty"` + // Scope says where the fact applies (the entry's `scope:` block, + // #17045). Nil means everywhere; see FactScope.Admits. + Scope *FactScope `json:"scope,omitempty"` + // Updated, BodySize and Origin feed the table of contents (#11103). They // are populated by file-backed stores only and never serialized, so // existing fact payloads are unchanged. @@ -309,6 +317,18 @@ type PrimedKnowledge struct { // MaxBytes bounds the rendered prompt text (PrimerConfig.MaxBytes). Zero // means DefaultPrimerMaxBytes. MaxBytes int `json:"-"` + // rendered is the slugs Render kept, in render order, for the mid-task + // advisor's "never repeat what the kick carried" rule (#17052). + rendered []string + // ScopedOut counts relevant facts the kick context excluded because their + // scope (paths, labels, lanes) did not match (#17045). + ScopedOut int `json:"-"` +} + +// RenderedSlugs returns the slugs of the facts the last Render kept — the +// entries the kick actually carried, excluding those the byte cap dropped. +func (pk *PrimedKnowledge) RenderedSlugs() []string { + return append([]string(nil), pk.rendered...) } // FormatForPrompt renders primed facts as markdown for injection into an agent's diff --git a/src/pkg/scheduler/kick_agentsmd_remote.go b/src/pkg/scheduler/kick_agentsmd_remote.go new file mode 100644 index 0000000000..97a600ebf3 --- /dev/null +++ b/src/pkg/scheduler/kick_agentsmd_remote.go @@ -0,0 +1,158 @@ +package scheduler + +import ( + "context" + "os" + "path/filepath" + "strings" + "time" + + "github.com/hivecommons/hive/crux/agentsmd" + "github.com/hivecommons/hive/pkg/config" +) + +// AgentsMdFetcher is the one GitHub call the remote AGENTS.md fallback needs. +// *github.Client satisfies it; the interface exists so tests can fake it and so +// a token-less boot can leave it unset. +type AgentsMdFetcher interface { + GetFileContentRef(ctx context.Context, owner, repo, path, ref string) (string, error) +} + +const ( + // remoteAgentsMdTTL is how long one fetched AGENTS.md serves kicks before + // the scheduler asks GitHub again. The shared transport sends + // If-None-Match, so a refresh of an unchanged file is a free 304 — the + // TTL only bounds how often that round trip happens, not quota. + remoteAgentsMdTTL = 15 * time.Minute + // remoteAgentsMdFetchTimeout bounds one fetch so a slow API cannot stall + // a kick; on timeout the last-known-good copy (if any) is served. + remoteAgentsMdFetchTimeout = 10 * time.Second +) + +// remoteAgentsMdDir is where fetched AGENTS.md files are materialised, as +// "<dir>/<owner>/<repo>/AGENTS.md", so agentsmd.Parse and primeSkills read it +// exactly as they would a checkout. A var only so tests can point it at a +// temp dir. +var remoteAgentsMdDir = "/data/agentsmd-cache" + +// remoteAgentsMd is one repo's fetch state. root is "" when the last fetch +// found no AGENTS.md (negative cache: a repo without the file is not asked +// about again until the TTL lapses). +type remoteAgentsMd struct { + root string + fetched time.Time +} + +// SetAgentsMdFetcher attaches the GitHub client the scheduler falls back to +// when a hive has no local checkout of its primary repo (hivecommons/hive#17090). +// Nil leaves the fallback off, which is the pre-existing behaviour. +func (s *Scheduler) SetAgentsMdFetcher(f AgentsMdFetcher) { + s.mu.Lock() + defer s.mu.Unlock() + s.agentsMdFetcher = f +} + +func (s *Scheduler) agentsMdFetcherOrNil() AgentsMdFetcher { + s.mu.RLock() + defer s.mu.RUnlock() + return s.agentsMdFetcher +} + +// remoteAgentsRepoRoot returns a local root holding repo's AGENTS.md fetched +// from the forge at its default branch, or "" when no fetcher is wired, the +// repo has no AGENTS.md, or the fetch failed with nothing cached. +// +// Hosted spokes keep no clone of the repos they work on — agents go through +// the API — so without this the two local roots agentsRepoRoot knows are +// always empty and the repo's instructions never reach a kick. The file is +// written under remoteAgentsMdDir so the rest of the priming path (Parse, +// Render, the injection cap, primeSkills' repo-local fallback) is unchanged +// and the log line's root= says where the text came from. +func (s *Scheduler) remoteAgentsRepoRoot(repo string) string { + fetcher := s.agentsMdFetcherOrNil() + if fetcher == nil || s.cfg == nil { + return "" + } + owner, name, ok := strings.Cut(config.QualifyRepo(s.cfg.Project.Org, repo), "/") + owner, name = strings.TrimSpace(owner), strings.TrimSpace(name) + if !ok || owner == "" || name == "" || !safeRepoPathSegment(owner) || !safeRepoPathSegment(name) { + return "" + } + key := owner + "/" + name + + s.remoteAgentsMu.Lock() + defer s.remoteAgentsMu.Unlock() + if s.remoteAgents == nil { + s.remoteAgents = map[string]remoteAgentsMd{} + } + now := time.Now() + cached, have := s.remoteAgents[key] + if have && now.Sub(cached.fetched) < remoteAgentsMdTTL { + return cached.root + } + + ctx, cancel := context.WithTimeout(context.Background(), remoteAgentsMdFetchTimeout) + defer cancel() + body, err := fetcher.GetFileContentRef(ctx, owner, name, agentsmd.AgentsFileName, "") + if err != nil { + if have && cached.root != "" { + // Last-known-good: a transient API failure must not strip the + // repo's instructions from a kick. Retry on the next kick. + s.logger.Warn("agentsmd: refresh from GitHub failed, serving cached copy", + "repo", key, "root", cached.root, "error", err) + return cached.root + } + // A 404 is the normal "repo has no AGENTS.md" answer; everything else + // is still just a miss for this kick, said once per TTL. + s.logger.Info("agentsmd: no AGENTS.md fetched from GitHub", "repo", key, "error", err) + s.remoteAgents[key] = remoteAgentsMd{fetched: now} + return "" + } + + root := filepath.Join(remoteAgentsMdDir, owner, name) + if err := writeFileAtomic(filepath.Join(root, agentsmd.AgentsFileName), []byte(body)); err != nil { + s.logger.Warn("agentsmd: cannot materialise fetched AGENTS.md, skipping injection", + "repo", key, "root", root, "error", err) + if have && cached.root != "" { + return cached.root + } + return "" + } + s.logger.Info("agentsmd: fetched AGENTS.md from GitHub", "repo", key, "bytes", len(body), "root", root) + s.remoteAgents[key] = remoteAgentsMd{root: root, fetched: now} + return root +} + +// safeRepoPathSegment refuses an owner or repo name that could escape +// remoteAgentsMdDir when joined into a path. Names come from config, which +// is operator-written, so this is belt-and-braces rather than a trust gate. +func safeRepoPathSegment(seg string) bool { + return seg != "." && seg != ".." && !strings.ContainsAny(seg, `/\`) +} + +// writeFileAtomic writes data to path via a sibling temp file and rename so a +// kick reading AGENTS.md concurrently never sees a half-written file. +func writeFileAtomic(path string, data []byte) error { + if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil { + return err + } + tmp, err := os.CreateTemp(filepath.Dir(path), ".agentsmd-*") + if err != nil { + return err + } + tmpName := tmp.Name() + if _, err := tmp.Write(data); err != nil { + _ = tmp.Close() + _ = os.Remove(tmpName) + return err + } + if err := tmp.Close(); err != nil { + _ = os.Remove(tmpName) + return err + } + if err := os.Rename(tmpName, path); err != nil { + _ = os.Remove(tmpName) + return err + } + return nil +} diff --git a/src/pkg/scheduler/kick_priming.go b/src/pkg/scheduler/kick_priming.go index 4aabd0787a..47740c3a2b 100644 --- a/src/pkg/scheduler/kick_priming.go +++ b/src/pkg/scheduler/kick_priming.go @@ -8,6 +8,7 @@ import ( "github.com/hivecommons/hive/crux/agentsmd" "github.com/hivecommons/hive/crux/skillreg" + "github.com/hivecommons/hive/pkg/config" "github.com/hivecommons/hive/pkg/github" "github.com/hivecommons/hive/pkg/knowledge" ) @@ -18,7 +19,7 @@ const maxIssuesToPrime = 5 // when the hive has none — in which case primeAgentsMd is a no-op, exactly as // before this was wired. // -// Two sources, in order: +// Three sources, in order: // // 1. project.checkouts_dir — the explicit one. An operator who mounts checkouts // of the monitored repos points at the parent directory and each repo is @@ -29,8 +30,12 @@ const maxIssuesToPrime = 5 // out of it), but it is a checkout of policies.repo, so it is used ONLY when // that repo IS the repo being asked about. Otherwise it would inject the // config repo's AGENTS.md into work on an unrelated repo. +// 3. the forge — when neither local root is configured and a GitHub client is +// wired (SetAgentsMdFetcher), AGENTS.md is fetched from the repo's default +// branch and materialised under remoteAgentsMdDir (#17090). Hosted spokes +// keep no clones at all, so without this they never injected anything. // -// Neither is checked for existence here: agentsmd.Parse tolerates a missing +// Neither local root is checked for existence here: agentsmd.Parse tolerates a missing // directory or file and yields "", and primeAgentsMd logs which root came up // empty. One stat per kick to say the same thing earlier is not worth it. func (s *Scheduler) agentsRepoRoot(repo string) string { @@ -44,7 +49,7 @@ func (s *Scheduler) agentsRepoRoot(repo string) string { sameRepo(s.cfg.Policies.Repo, s.cfg.Project.Org, repo) { return local } - return "" + return s.remoteAgentsRepoRoot(repo) } // sameRepo reports whether a git source's repo field names org/repo. The source @@ -250,16 +255,40 @@ func capSkills(skills []skillreg.Skill, capBytes int) (kept []skillreg.Skill, dr return kept, dropped } +// knowledgeInjection is what one kick received from the knowledge primer +// (#17049): the rendered "# Relevant Knowledge" section and the numbers +// behind it. Primed is false when the primer did not run at all (knowledge +// disabled, no issues, no keywords), so a zero-byte result from a real query +// is distinguishable from no query. +type knowledgeInjection struct { + Section string + Bytes int + Entries int + SkippedForCap int + CapBytes int + Primed bool +} + // primeKnowledge queries the wiki layers for facts relevant to the given issues // and returns a formatted section for injection into the kick message. The // facts are restricted to agentName's knowledge.agent_scopes entry, if any. +// It logs the per-kick knowledge line itself; callers that also prepend an +// AGENTS.md or skills block use primeKnowledgeStats and log once with those +// sizes included. func (s *Scheduler) primeKnowledge(agentName string, issues []github.Issue) string { + inj := s.primeKnowledgeStats(agentName, issues) + s.logKnowledgeInjection(agentName, inj, 0, 0) + return inj.Section +} + +// primeKnowledgeStats is primeKnowledge without the summary log line. +func (s *Scheduler) primeKnowledgeStats(agentName string, issues []github.Issue) knowledgeInjection { s.mu.RLock() primer := s.primer cfg := s.cfg s.mu.RUnlock() if primer == nil || len(issues) == 0 { - return "" + return knowledgeInjection{} } limit := maxIssuesToPrime @@ -270,20 +299,28 @@ func (s *Scheduler) primeKnowledge(agentName string, issues []github.Issue) stri keywords := extractKeywords(issues[:limit]) if len(keywords) == 0 { s.logger.Debug("knowledge primer: no keywords extracted from issues", "issue_count", len(issues)) - return "" + return knowledgeInjection{} } s.logger.Info("knowledge primer: searching", "keywords", len(keywords), "sample", keywordSample(keywords)) var scope *knowledge.TOCScope if sc, ok := cfg.KnowledgeAgentScope(agentName); ok { agentScope := knowledge.AgentScope(sc.Layers, sc.Repos, sc.Types, sc.Tags, sc.IncludeStates) + if knowledge.ListsDraft(sc.IncludeStates) { + agentScope.DraftAuthors = kickDraftAuthors(cfg, agentName) + } scope = &agentScope } - primed := primer.PrimeScoped(context.Background(), scope, nil, keywords) + primed := primer.PrimeForKick(context.Background(), scope, kickContextFor(cfg, agentName, issues[:limit]), keywords) result, omitted := primed.Render() - if result != "" { - s.logger.Info("knowledge primer: injecting facts into kick", - "facts", len(primed.Facts)-omitted.Facts, "chars", len(result)) + s.primedSlugs.Store(agentName, primed.RenderedSlugs()) + inj := knowledgeInjection{ + Section: result, + Bytes: len(result), + Entries: len(primed.Facts) - omitted.Facts, + SkippedForCap: omitted.Facts, + CapBytes: primer.MaxBytes(), + Primed: true, } if omitted.Any() { // The render carries its own marker; this is the operator-side half so @@ -301,7 +338,101 @@ func (s *Scheduler) primeKnowledge(agentName string, issues []github.Issue) stri "omitted_facts", omitted.Facts, "omitted_hints", omitted.Hints, "omitted_bytes", omitted.Bytes, "cap_bytes", primed.MaxBytes) } - return result + return inj +} + +// kickDraftAuthors lists the identities whose draft knowledge a kick for +// agentName may carry once that agent's agent_scopes entry opts into drafts +// (#17076): the agent itself, its base agent for a replica, and the hive's +// owner logins, so an operator's hand-written draft reaches the agents they +// opted in. Owner entries are stored as "alice" or "github:alice"; the +// provider prefix is dropped so either form matches an author: line. +func kickDraftAuthors(cfg *config.Config, agentName string) []string { + var out []string + add := func(name string) { + name = strings.TrimSpace(name) + if name == "" { + return + } + for _, have := range out { + if strings.EqualFold(have, name) { + return + } + } + out = append(out, name) + } + add(agentName) + if cfg != nil { + add(cfg.BaseAgentName(agentName)) + for _, login := range cfg.Dashboard.OwnerLogins() { + if _, bare, ok := strings.Cut(login, ":"); ok { + login = bare + } + add(login) + } + } + return out +} + +// logKnowledgeInjection emits the one knowledge line per kick (#17049): +// +// knowledge: injected N bytes from M entries (skipped K for cap) +// +// with the primer cap and the sizes of the AGENTS.md and skills blocks that +// share the kick, so the whole knowledge payload is readable from one line +// next to "kick rendered". It is emitted even when N is 0 — a primed kick +// that found nothing is a signal, not silence — but not when the primer did +// not run (knowledge disabled or nothing to prime), which would otherwise +// print a zero line on every kick of a hive that has no knowledge store. +func (s *Scheduler) logKnowledgeInjection(agentName string, inj knowledgeInjection, agentsMdBytes, skillsBytes int) { + if s == nil || s.logger == nil || (!inj.Primed && agentsMdBytes == 0 && skillsBytes == 0) { + return + } + s.logger.Info(fmt.Sprintf("knowledge: injected %d bytes from %d entries (skipped %d for cap)", + inj.Bytes, inj.Entries, inj.SkippedForCap), + "agent", agentName, + "injected_bytes", inj.Bytes, + "entries", inj.Entries, + "skipped_for_cap", inj.SkippedForCap, + "cap_bytes", inj.CapBytes, + "primed", inj.Primed, + "agents_md_bytes", agentsMdBytes, + "skills_bytes", skillsBytes, + ) +} + +// KickPrimedSlugs returns the knowledge slugs the most recent kick message +// built for agentName actually rendered in its `# Relevant Knowledge` block. +// The mid-task advisor (#17052) uses it to never repeat what the kick carried; +// facts the byte cap dropped are not in it and so stay eligible. +func (s *Scheduler) KickPrimedSlugs(agentName string) []string { + v, ok := s.primedSlugs.Load(agentName) + if !ok { + return nil + } + slugs, _ := v.([]string) + return slugs +} + +// kickContextFor is the kick context a scoped knowledge entry is matched +// against (#17045): the base lane name (a replica resolves to the agent it +// replicates) and the union of the primed issues' labels. File paths are not +// known on the kick path, so entries scoped by paths alone wait for a caller +// that has them. +func kickContextFor(cfg *config.Config, agentName string, issues []github.Issue) knowledge.KickContext { + kc := knowledge.KickContext{Lane: cfg.BaseAgentName(agentName)} + seen := make(map[string]bool) + for _, issue := range issues { + for _, label := range issue.Labels { + lower := strings.ToLower(strings.TrimSpace(label)) + if lower == "" || seen[lower] { + continue + } + seen[lower] = true + kc.Labels = append(kc.Labels, lower) + } + } + return kc } // extractKeywords pulls searchable terms from issue labels and titles. diff --git a/src/pkg/scheduler/kick_priming_draft_test.go b/src/pkg/scheduler/kick_priming_draft_test.go new file mode 100644 index 0000000000..ceb147a19d --- /dev/null +++ b/src/pkg/scheduler/kick_priming_draft_test.go @@ -0,0 +1,131 @@ +package scheduler + +import ( + "log/slog" + "os" + "path/filepath" + "strings" + "testing" + + "github.com/hivecommons/hive/pkg/config" + "github.com/hivecommons/hive/pkg/github" + "github.com/hivecommons/hive/pkg/knowledge" +) + +// TestPrimeKnowledge_DraftsReachTheirAuthor proves the kick-path draft rule +// (#17076): a draft is primed only when the agent's agent_scopes entry lists +// draft in include_states and the draft's author is the agent, its base agent +// or an owner login; it is rendered with a "(draft)" marker; approved-only +// stays the default for every other agent. +func TestPrimeKnowledge_DraftsReachTheirAuthor(t *testing.T) { + dir := t.TempDir() + write := func(name, title, state, author string) { + t.Helper() + content := "---\ntitle: " + title + "\ntype: gotcha\nlayer: project\nstate: " + state + "\n" + if author != "" { + content += "author: " + author + "\n" + } + content += "---\nRelevant to the webhook retry path.\n" + if err := os.WriteFile(filepath.Join(dir, name), []byte(content), 0o644); err != nil { + t.Fatal(err) + } + } + write("approved.md", "Webhook retry approved fact", "approved", "") + write("dev-draft.md", "Webhook retry developer draft", "draft", "developer") + write("owner-draft.md", "Webhook retry owner draft", "draft", "alice") + write("other-draft.md", "Webhook retry scanner draft", "draft", "scanner") + write("anon-draft.md", "Webhook retry anonymous draft", "draft", "") + + logger := slog.New(slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{Level: slog.LevelError})) + store, err := knowledge.NewFileStore(dir, "vault", logger) + if err != nil { + t.Fatal(err) + } + primer := knowledge.NewPrimer(nil, knowledge.PrimerConfig{MaxFacts: 25}, logger) + primer.AddFileStore("vault", store, knowledge.LayerProject) + + s := newScheduler() + s.cfg.Dashboard.AuthorizedUsers = []string{"github:alice", "bob:viewer"} + s.cfg.Agents = map[string]config.AgentConfig{"developer-2": {ReplicaOf: "developer"}} + s.cfg.Knowledge.AgentScopes = map[string]config.KnowledgeAgentScope{ + "developer": {IncludeStates: []string{"draft"}}, + "architect": {IncludeStates: []string{"all"}}, + "quality": {Layers: []string{"project"}}, + "reviewer": {IncludeStates: []string{"deprecated"}}, + } + s.SetPrimer(primer) + issues := []github.Issue{makeIssue("org/repo", 1, "Webhook retry fails", "", 5, []string{"webhook", "retry"}, false)} + + const ( + approved = "Webhook retry approved fact" + devDraft = "Webhook retry developer draft" + ownerDraft = "Webhook retry owner draft" + otherDraft = "Webhook retry scanner draft" + anonDraft = "Webhook retry anonymous draft" + ) + tests := []struct { + name string + agent string + want []string + deny []string + }{ + {"unscoped agent: approved only", "outreach", []string{approved}, []string{devDraft, ownerDraft, otherDraft, anonDraft}}, + {"scope without include_states: approved only", "quality", []string{approved}, []string{devDraft, ownerDraft, otherDraft, anonDraft}}, + {"include_states without draft: approved only", "reviewer", []string{approved}, []string{devDraft, ownerDraft, otherDraft, anonDraft}}, + {"draft opt-in: own and owner drafts, not others", "developer", []string{approved, devDraft, ownerDraft}, []string{otherDraft, anonDraft}}, + {"replica inherits base agent identity", "developer-2", []string{approved, devDraft, ownerDraft}, []string{otherDraft, anonDraft}}, + {"all opt-in without a matching author: owner drafts only", "architect", []string{approved, ownerDraft}, []string{devDraft, otherDraft, anonDraft}}, + } + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + got := s.primeKnowledge(tc.agent, issues) + for _, w := range tc.want { + if !strings.Contains(got, w) { + t.Errorf("%s: missing %q in:\n%s", tc.agent, w, got) + } + } + for _, d := range tc.deny { + if strings.Contains(got, d) { + t.Errorf("%s: unexpected %q in:\n%s", tc.agent, d, got) + } + } + drafts := strings.Count(got, "(draft)") + wantDrafts := 0 + for _, w := range tc.want { + if w != approved { + wantDrafts++ + } + } + if drafts != wantDrafts { + t.Errorf("%s: %d \"(draft)\" markers, want %d in:\n%s", tc.agent, drafts, wantDrafts, got) + } + if strings.Contains(got, "**"+approved+"** (draft)") { + t.Errorf("%s: approved fact marked as draft", tc.agent) + } + }) + } +} + +func TestKickDraftAuthors(t *testing.T) { + cfg := &config.Config{} + cfg.Agents = map[string]config.AgentConfig{"scanner-3": {ReplicaOf: "scanner"}} + cfg.Dashboard.AuthorizedUsers = []string{"github:alice", "carol:owner", "bob:viewer"} + + tests := []struct { + agent string + want []string + }{ + {"scanner", []string{"scanner", "alice", "carol"}}, + {"scanner-3", []string{"scanner-3", "scanner", "alice", "carol"}}, + {"", []string{"alice", "carol"}}, + } + for _, tc := range tests { + got := kickDraftAuthors(cfg, tc.agent) + if strings.Join(got, ",") != strings.Join(tc.want, ",") { + t.Errorf("kickDraftAuthors(%q) = %v, want %v", tc.agent, got, tc.want) + } + } + if got := kickDraftAuthors(nil, "dev"); len(got) != 1 || got[0] != "dev" { + t.Errorf("nil config: got %v, want [dev]", got) + } +} diff --git a/src/pkg/scheduler/kick_priming_log_test.go b/src/pkg/scheduler/kick_priming_log_test.go new file mode 100644 index 0000000000..e356607254 --- /dev/null +++ b/src/pkg/scheduler/kick_priming_log_test.go @@ -0,0 +1,165 @@ +package scheduler + +import ( + "bytes" + "encoding/json" + "log/slog" + "os" + "path/filepath" + "strings" + "testing" + + "github.com/hivecommons/hive/pkg/config" + "github.com/hivecommons/hive/pkg/github" + "github.com/hivecommons/hive/pkg/knowledge" +) + +// knowledgeLogLines returns the decoded "knowledge: injected …" records a +// scheduler wrote to buf. +func knowledgeLogLines(t *testing.T, buf *bytes.Buffer) []map[string]any { + t.Helper() + var out []map[string]any + for _, line := range strings.Split(strings.TrimSpace(buf.String()), "\n") { + if line == "" { + continue + } + var rec map[string]any + if err := json.Unmarshal([]byte(line), &rec); err != nil { + t.Fatalf("bad log line %q: %v", line, err) + } + if msg, _ := rec["msg"].(string); strings.HasPrefix(msg, "knowledge: injected ") { + out = append(out, rec) + } + } + return out +} + +func TestLogKnowledgeInjection(t *testing.T) { + tests := []struct { + name string + inj knowledgeInjection + agentsMdBytes int + skillsBytes int + wantLine bool + wantMsg string + }{ + { + name: "primer did not run and nothing else injected: silent", + inj: knowledgeInjection{}, + wantLine: false, + }, + { + name: "primed with nothing found still reports a zero line", + inj: knowledgeInjection{Primed: true, CapBytes: 4096}, + wantLine: true, + wantMsg: "knowledge: injected 0 bytes from 0 entries (skipped 0 for cap)", + }, + { + name: "primed with omissions plus AGENTS.md and skills", + inj: knowledgeInjection{Primed: true, Bytes: 3900, Entries: 7, SkippedForCap: 3, CapBytes: 4096}, + agentsMdBytes: 1980, + skillsBytes: 512, + wantLine: true, + wantMsg: "knowledge: injected 3900 bytes from 7 entries (skipped 3 for cap)", + }, + { + name: "no primer but an AGENTS.md block is still a knowledge payload", + inj: knowledgeInjection{}, + agentsMdBytes: 1980, + wantLine: true, + wantMsg: "knowledge: injected 0 bytes from 0 entries (skipped 0 for cap)", + }, + } + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + var buf bytes.Buffer + s := New(&config.Config{}, slog.New(slog.NewJSONHandler(&buf, nil))) + s.logKnowledgeInjection("developer", tc.inj, tc.agentsMdBytes, tc.skillsBytes) + lines := knowledgeLogLines(t, &buf) + if !tc.wantLine { + if len(lines) != 0 { + t.Fatalf("expected no line, got %v", lines) + } + return + } + if len(lines) != 1 { + t.Fatalf("expected exactly one line, got %d: %v", len(lines), lines) + } + rec := lines[0] + if rec["msg"] != tc.wantMsg { + t.Fatalf("msg = %q, want %q", rec["msg"], tc.wantMsg) + } + want := map[string]float64{ + "injected_bytes": float64(tc.inj.Bytes), + "entries": float64(tc.inj.Entries), + "skipped_for_cap": float64(tc.inj.SkippedForCap), + "cap_bytes": float64(tc.inj.CapBytes), + "agents_md_bytes": float64(tc.agentsMdBytes), + "skills_bytes": float64(tc.skillsBytes), + } + for k, v := range want { + if got, _ := rec[k].(float64); got != v { + t.Errorf("%s = %v, want %v", k, rec[k], v) + } + } + if rec["agent"] != "developer" { + t.Errorf("agent = %v, want developer", rec["agent"]) + } + if rec["primed"] != tc.inj.Primed { + t.Errorf("primed = %v, want %v", rec["primed"], tc.inj.Primed) + } + }) + } +} + +// TestPrimeKnowledge_LogsOneLinePerKick drives the real primer against a temp +// vault with a cap small enough to drop an entry, and checks that +// primeKnowledge emits exactly one summary line whose numbers match the +// rendered section. +func TestPrimeKnowledge_LogsOneLinePerKick(t *testing.T) { + dir := t.TempDir() + long := strings.Repeat("scheduler kick detail. ", 40) + for i, name := range []string{"scheduler-a.md", "scheduler-b.md", "scheduler-c.md"} { + content := "---\ntitle: Scheduler kick fact " + string(rune('A'+i)) + "\ntype: pattern\nlayer: project\n---\n" + long + if err := os.WriteFile(filepath.Join(dir, name), []byte(content), 0o644); err != nil { + t.Fatal(err) + } + } + var buf bytes.Buffer + logger := slog.New(slog.NewJSONHandler(&buf, nil)) + store, err := knowledge.NewFileStore(dir, "vault", logger) + if err != nil { + t.Fatal(err) + } + // 512 is the primer's floor; three ~250-byte snippets cannot all fit. + p := knowledge.NewPrimer(nil, knowledge.PrimerConfig{MaxBytes: 512}, logger) + p.AddFileStore("vault", store, knowledge.LayerProject) + + s := New(&config.Config{}, logger) + s.SetPrimer(p) + issues := []github.Issue{makeIssue("org/repo", 1, "scheduler kick fact", "", 5, nil, false)} + + section := s.primeKnowledge("developer", issues) + if section == "" { + t.Fatal("expected a rendered knowledge section") + } + lines := knowledgeLogLines(t, &buf) + if len(lines) != 1 { + t.Fatalf("expected one knowledge line per kick, got %d", len(lines)) + } + rec := lines[0] + if int(rec["injected_bytes"].(float64)) != len(section) { + t.Errorf("injected_bytes = %v, want %d", rec["injected_bytes"], len(section)) + } + if int(rec["cap_bytes"].(float64)) != 512 { + t.Errorf("cap_bytes = %v, want 512", rec["cap_bytes"]) + } + entries := int(rec["entries"].(float64)) + skipped := int(rec["skipped_for_cap"].(float64)) + if entries < 1 || skipped < 1 || entries+skipped != 3 { + t.Errorf("entries=%d skipped=%d, want both ≥1 and summing to 3", entries, skipped) + } + if strings.Count(section, "- **Scheduler kick fact") != entries { + t.Errorf("section has %d entries, log says %d", strings.Count(section, "- **Scheduler kick fact"), entries) + } +} diff --git a/src/pkg/scheduler/kick_priming_scope_test.go b/src/pkg/scheduler/kick_priming_scope_test.go new file mode 100644 index 0000000000..27801be448 --- /dev/null +++ b/src/pkg/scheduler/kick_priming_scope_test.go @@ -0,0 +1,62 @@ +package scheduler + +import ( + "strings" + "testing" + + "github.com/hivecommons/hive/pkg/config" + "github.com/hivecommons/hive/pkg/github" +) + +func TestKickContextFor(t *testing.T) { + cfg := &config.Config{AgentRuntimeConfig: config.AgentRuntimeConfig{ + Agents: map[string]config.AgentConfig{ + "developer": {}, + "developer-2": {ReplicaOf: "developer"}, + }, + }} + tests := []struct { + name string + cfg *config.Config + agent string + issues []github.Issue + wantLane string + wantLabels string + }{ + { + name: "lane and de-duplicated lower-cased labels", + cfg: cfg, + agent: "developer", + issues: []github.Issue{{Labels: []string{"Area/CI", "kind/bug"}}, {Labels: []string{"area/ci", " docs "}}}, + wantLane: "developer", + wantLabels: "area/ci,kind/bug,docs", + }, + { + name: "replica resolves to its base lane", + cfg: cfg, + agent: "developer-2", + issues: nil, + wantLane: "developer", + }, + { + name: "nil config keeps the agent name", + cfg: nil, + agent: "reviewer", + wantLane: "reviewer", + }, + } + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + kc := kickContextFor(tc.cfg, tc.agent, tc.issues) + if kc.Lane != tc.wantLane { + t.Fatalf("Lane = %q, want %q", kc.Lane, tc.wantLane) + } + if got := strings.Join(kc.Labels, ","); got != tc.wantLabels { + t.Fatalf("Labels = %q, want %q", got, tc.wantLabels) + } + if len(kc.Paths) != 0 { + t.Fatalf("Paths must stay empty on the kick path, got %v", kc.Paths) + } + }) + } +} diff --git a/src/pkg/scheduler/kick_priming_test.go b/src/pkg/scheduler/kick_priming_test.go index 9a20f413d6..6a8b0121be 100644 --- a/src/pkg/scheduler/kick_priming_test.go +++ b/src/pkg/scheduler/kick_priming_test.go @@ -1,7 +1,9 @@ package scheduler import ( + "context" "encoding/json" + "errors" "log/slog" "os" "path/filepath" @@ -329,3 +331,120 @@ func TestInceptionVars_GreenfieldEmptyIdeaDoesNotFallBack(t *testing.T) { t.Errorf("idea = %q, want empty: RepoURL fallback is brownfield-only", idea) } } + +// --- remoteAgentsRepoRoot (GitHub fallback, #17090) --- + +type fakeAgentsMdFetcher struct { + body string + err error + calls int + last [4]string +} + +func (f *fakeAgentsMdFetcher) GetFileContentRef(_ context.Context, owner, repo, path, ref string) (string, error) { + f.calls++ + f.last = [4]string{owner, repo, path, ref} + return f.body, f.err +} + +func useTempRemoteAgentsMdDir(t *testing.T) { + t.Helper() + old := remoteAgentsMdDir + remoteAgentsMdDir = t.TempDir() + t.Cleanup(func() { remoteAgentsMdDir = old }) +} + +// With no local root and no fetcher wired the behaviour is unchanged: nothing. +func TestAgentsRepoRoot_NoFetcherStaysEmpty(t *testing.T) { + useTempRemoteAgentsMdDir(t) + cfg := &config.Config{} + cfg.Project.Org = "hivecommons" + s := New(cfg, slog.Default()) + if got := s.agentsRepoRoot("hive"); got != "" { + t.Errorf("agentsRepoRoot() = %q, want empty with no fetcher", got) + } +} + +// A hosted spoke with no checkout gets the primary repo's AGENTS.md from the +// forge's default branch, materialised so the existing priming path injects it, +// and one fetch serves every kick inside the TTL. +func TestAgentsRepoRoot_FetchesFromGitHubWhenNoLocalRoot(t *testing.T) { + useTempRemoteAgentsMdDir(t) + const body = "Always add a changelog.d fragment." + f := &fakeAgentsMdFetcher{body: body + "\n"} + + cfg := &config.Config{} + cfg.Project.Org = "hivecommons" + cfg.Project.PrimaryRepo = "hive" + s := New(cfg, slog.Default()) + s.SetAgentsMdFetcher(f) + + root := s.agentsRepoRoot("hive") + if want := filepath.Join(remoteAgentsMdDir, "hivecommons", "hive"); root != want { + t.Fatalf("agentsRepoRoot() = %q, want %q", root, want) + } + if f.last != [4]string{"hivecommons", "hive", "AGENTS.md", ""} { + t.Errorf("fetched %v, want owner/repo AGENTS.md at the default branch", f.last) + } + if got := s.primeAgentsMd(root); !strings.Contains(got, body) { + t.Fatalf("fetched AGENTS.md did not reach the injection; got %q", got) + } + + for i := 0; i < 3; i++ { + if again := s.agentsRepoRoot("hivecommons/hive"); again != root { + t.Fatalf("agentsRepoRoot() = %q on repeat, want cached %q", again, root) + } + } + if f.calls != 1 { + t.Errorf("fetch calls = %d, want 1 (served from cache inside the TTL)", f.calls) + } +} + +// A repo without AGENTS.md (404) yields no root and is not re-asked inside +// the TTL; a later failure keeps serving the last-known-good copy. +func TestAgentsRepoRoot_RemoteMissAndLastKnownGood(t *testing.T) { + useTempRemoteAgentsMdDir(t) + f := &fakeAgentsMdFetcher{err: errors.New("404 Not Found")} + cfg := &config.Config{} + cfg.Project.Org = "hivecommons" + s := New(cfg, slog.Default()) + s.SetAgentsMdFetcher(f) + + if got := s.agentsRepoRoot("hive"); got != "" { + t.Fatalf("agentsRepoRoot() = %q, want empty on 404", got) + } + s.agentsRepoRoot("hive") + if f.calls != 1 { + t.Errorf("fetch calls = %d, want 1 (negative result cached)", f.calls) + } + + // Expire the cache, succeed once, then fail: the good copy must survive. + s.remoteAgents = nil + f.err, f.body = nil, "rule\n" + root := s.agentsRepoRoot("hive") + if root == "" { + t.Fatal("agentsRepoRoot() empty after a successful fetch") + } + s.remoteAgents["hivecommons/hive"] = remoteAgentsMd{root: root, fetched: time.Now().Add(-2 * remoteAgentsMdTTL)} + f.err = errors.New("502 Bad Gateway") + if got := s.agentsRepoRoot("hive"); got != root { + t.Errorf("agentsRepoRoot() = %q after refresh failure, want last-known-good %q", got, root) + } +} + +// A configured local root still wins over the forge: no fetch happens. +func TestAgentsRepoRoot_LocalRootBeatsFetch(t *testing.T) { + useTempRemoteAgentsMdDir(t) + f := &fakeAgentsMdFetcher{body: "x"} + cfg := &config.Config{} + cfg.Project.Org = "hivecommons" + cfg.Project.CheckoutsDir = "/data/checkouts" + s := New(cfg, slog.Default()) + s.SetAgentsMdFetcher(f) + if got, want := s.agentsRepoRoot("hive"), filepath.Join("/data/checkouts", "hive"); got != want { + t.Errorf("agentsRepoRoot() = %q, want %q", got, want) + } + if f.calls != 0 { + t.Errorf("fetch calls = %d, want 0 when a local root exists", f.calls) + } +} diff --git a/src/pkg/scheduler/scheduler.go b/src/pkg/scheduler/scheduler.go index b3192fd0c1..4851aa9a49 100644 --- a/src/pkg/scheduler/scheduler.go +++ b/src/pkg/scheduler/scheduler.go @@ -17,14 +17,20 @@ import ( ) type Scheduler struct { - surgeDuration func() (time.Duration, bool) - cfg *config.Config - primer *knowledge.Primer - inception *knowledge.InceptionEngine - lastActionable *github.ActionableResult - logger *slog.Logger - primerCapLogged sync.Map // agent|cap_bytes -> omitted fact count last logged at INFO - promptResolver *promptsrc.Resolver + surgeDuration func() (time.Duration, bool) + cfg *config.Config + primer *knowledge.Primer + inception *knowledge.InceptionEngine + lastActionable *github.ActionableResult + logger *slog.Logger + primerCapLogged sync.Map // agent|cap_bytes -> omitted fact count last logged at INFO + primedSlugs sync.Map // agent -> []string slugs the last kick's knowledge block rendered (#17052) + promptResolver *promptsrc.Resolver + agentsMdFetcher AgentsMdFetcher + // remoteAgents caches the materialised AGENTS.md root per "owner/repo" + // for the GitHub fallback in remoteAgentsRepoRoot (#17090). + remoteAgents map[string]remoteAgentsMd + remoteAgentsMu sync.Mutex auditFunc AuditFunc advisoryFunc AdvisoryFunc classifierUnavailableFunc func(error) diff --git a/src/pkg/scheduler/templates.go b/src/pkg/scheduler/templates.go index ecaa2c87c1..3d6c1f384f 100644 --- a/src/pkg/scheduler/templates.go +++ b/src/pkg/scheduler/templates.go @@ -361,12 +361,14 @@ func (s *Scheduler) substituteTemplateWithVars(template string, actionable *gith if len(agentIssues) == 0 && actionable != nil && len(actionable.Issues.Items) > 0 { agentIssues = actionable.Issues.Items } - knowledgeSection := s.primeKnowledge(agentName, agentIssues) + knowledgeInj := s.primeKnowledgeStats(agentName, agentIssues) + knowledgeSection := knowledgeInj.Section repoRoot := s.agentsRepoRoot(primaryRepo) // Additive: prepend the repo's AGENTS.md instructions + requested skills to - // the injected knowledge, when a local checkout root is available. This is a + // the injected knowledge, when a checkout root is available — local, or the + // GitHub-fetched copy a hosted spoke falls back to (#17090). This is a // guarded, single call point — it returns "" (and never errors) when no // AGENTS.md exists, so it is a no-op for repos that don't use the convention. // @@ -380,7 +382,8 @@ func (s *Scheduler) substituteTemplateWithVars(template string, actionable *gith // agentsmd.ParseNearest for closest-wins nested AGENTS.md. That still has no // caller — nothing on the kick path knows which FILE an agent will touch — // so it stays deferred, unlike the checkout root, which is now threaded. - if agentsSection := s.primeAgentsMd(repoRoot); agentsSection != "" { + agentsSection := s.primeAgentsMd(repoRoot) + if agentsSection != "" { knowledgeSection = agentsSection + "\n" + knowledgeSection } @@ -388,9 +391,11 @@ func (s *Scheduler) substituteTemplateWithVars(template string, actionable *gith // to definitions in the primary repo's AGENTS.md or adjacent skills/ // directory. The registry remains independently useful without a checkout; // the fallback activates only when agentsRepoRoot found one above. - if skillsSection := s.primeSkills(agentName, repoRoot); skillsSection != "" { + skillsSection := s.primeSkills(agentName, repoRoot) + if skillsSection != "" { knowledgeSection = skillsSection + "\n" + knowledgeSection } + s.logKnowledgeInjection(agentName, knowledgeInj, len(agentsSection), len(skillsSection)) inceptionIdea, inceptionPhase, inceptionMode, inceptionAnswers, inceptionSlug, inceptionRepoURL := s.inceptionVars() diff --git a/src/pkg/stagelabels/stagelabels_test.go b/src/pkg/stagelabels/stagelabels_test.go index 2f2f92effd..4e87930166 100644 --- a/src/pkg/stagelabels/stagelabels_test.go +++ b/src/pkg/stagelabels/stagelabels_test.go @@ -602,6 +602,65 @@ func TestStoreMarksForgetsAndSharedLoad(t *testing.T) { } } +func TestStoreMarkNudgedReason(t *testing.T) { + now := time.Date(2026, 10, 16, 12, 0, 0, 0, time.UTC) + s := NewStore("", func() time.Time { return now }) + s.MarkNudgedReason("missing", "check-failing:unit", 1, now) // unknown key: no-op + if _, ok := s.Get("missing"); ok { + t.Fatal("MarkNudgedReason created a record") + } + key := Key("acme/widget", 7) + s.Observe(key, ReturnedToContributor, "check-failing:unit") + s.MarkNudgedReason(key, "required-check-failing:unit (lint)", 1, now) + r, _ := s.Get(key) + if r.NudgeReason != "check-failing" || r.NudgeReasonCount != 1 || !r.NudgeReasonAt.Equal(now) { + t.Fatalf("after first: %+v", r) + } + // A head-only rewrite (n == 0) for the same class keeps the count and time. + s.MarkNudgedReason(key, "check-failing:e2e", 0, now.Add(time.Hour)) + if r, _ = s.Get(key); r.NudgeReasonCount != 1 || !r.NudgeReasonAt.Equal(now) { + t.Fatalf("rewrite: %+v", r) + } + s.MarkNudgedReason(key, "check-failing:e2e", 2, now.Add(2*time.Hour)) + if r, _ = s.Get(key); r.NudgeReasonCount != 2 || !r.NudgeReasonAt.Equal(now.Add(2*time.Hour)) { + t.Fatalf("second nudge: %+v", r) + } + // A different class restarts the count. + s.MarkNudgedReason(key, "changes-requested", 1, now.Add(3*time.Hour)) + if r, _ = s.Get(key); r.NudgeReason != "changes-requested" || r.NudgeReasonCount != 1 || !r.NudgeReasonAt.Equal(now.Add(3*time.Hour)) { + t.Fatalf("new class: %+v", r) + } +} + +func TestRecordNudgeStart(t *testing.T) { + now := time.Date(2026, 10, 16, 12, 0, 0, 0, time.UTC) + if got := (Record{}).NudgeStart(); !got.IsZero() { + t.Fatalf("never nudged: %v", got) + } + if got := (Record{NudgeCount: 1, LastNudgeAt: now}).NudgeStart(); !got.Equal(now) { + t.Fatalf("legacy record falls back to LastNudgeAt: %v", got) + } + if got := (Record{NudgeCount: 2, FirstNudgeAt: now, LastNudgeAt: now.Add(time.Hour)}).NudgeStart(); !got.Equal(now) { + t.Fatalf("FirstNudgeAt wins: %v", got) + } +} + +func TestNudgeReasonSlug(t *testing.T) { + for in, want := range map[string]string{ + "": "unknown", + " ": "unknown", + "check-failing:unit (lint)": "check-failing", + "required-check-failing:unit": "check-failing", + "Changes Requested by @Reviewer": "changes-requested-by--reviewer", + "--merge_conflict.v2--": "merge_conflict.v2", + "(only parenthetical)": "unknown", + } { + if got := NudgeReasonSlug(in); got != want { + t.Errorf("NudgeReasonSlug(%q) = %q, want %q", in, got, want) + } + } +} + func TestStoreMarkNudged(t *testing.T) { now := time.Date(2026, 10, 16, 12, 0, 0, 0, time.UTC) s := NewStore("", func() time.Time { return now }) diff --git a/src/pkg/stagelabels/store.go b/src/pkg/stagelabels/store.go index eb0be3cfa0..0a6da9a035 100644 --- a/src/pkg/stagelabels/store.go +++ b/src/pkg/stagelabels/store.go @@ -83,6 +83,15 @@ type Record struct { // NudgeOnline records whether the author's relay was online at the first // nudge for NudgeHead (selects the online vs offline grace). NudgeOnline bool `json:"nudge_online,omitempty"` + // NudgeReason, NudgeReasonCount and NudgeReasonAt are the per-reason + // nudge ledger (hivecommons/hive#17067): the reason class the one + // nudge comment on the PR currently explains, how many nudges that + // class has had (cap 2, counted across heads) and when the last one + // went out. A new head red for the same class rewrites the comment + // without counting; a new class restarts the count. + NudgeReason string `json:"nudge_reason,omitempty"` + NudgeReasonCount int `json:"nudge_reason_count,omitempty"` + NudgeReasonAt time.Time `json:"nudge_reason_at,omitempty"` // AdoptedHead / AdoptedBy / AdoptedAt record the stage-074 adoption: the // contributor head the hive adopted, the superseding App PR's number // (0 while the attempt is recorded but no PR exists) and when. One @@ -1478,10 +1487,59 @@ func (s *Store) WithdrawNudge(key, head string) { } r.NudgeHead, r.NudgeCount, r.NudgeOnline = "", 0, false r.LastNudgeAt, r.FirstNudgeAt = time.Time{}, time.Time{} + // The reason class goes too, so a head still red once the incident + // closes is owed a fresh first nudge rather than a capped repeat. + r.NudgeReason, r.NudgeReasonCount, r.NudgeReasonAt = "", 0, time.Time{} s.items[key] = r s.dirty = true } +// MarkNudgedReason records that nudge number n for reason class reason was +// posted (or the one nudge comment rewritten) at now. A different class +// restarts the count at n; the same class keeps the larger of n and the +// recorded count so a head-only rewrite (n == 0) never resets it. +func (s *Store) MarkNudgedReason(key, reason string, n int, now time.Time) { + s.mu.Lock() + defer s.mu.Unlock() + r, ok := s.items[key] + if !ok { + return + } + reason = NudgeReasonSlug(reason) + if r.NudgeReason != reason { + r.NudgeReason = reason + r.NudgeReasonCount = 0 + } + if n > r.NudgeReasonCount { + r.NudgeReasonCount = n + r.NudgeReasonAt = now + } + s.items[key] = r + s.dirty = true +} + +// NudgeReasonSlug is the marker-safe reason class a contributor nudge is +// keyed by: MentionCauseClass (so every red check is one "check-failing" +// ask), lower-cased, with anything outside [a-z0-9._-] folded to '-'; +// an empty reason is "unknown". +func NudgeReasonSlug(reason string) string { + class := strings.ToLower(MentionCauseClass(reason)) + var b strings.Builder + for _, r := range class { + switch { + case r >= 'a' && r <= 'z', r >= '0' && r <= '9', r == '.', r == '_', r == '-': + b.WriteRune(r) + default: + b.WriteByte('-') + } + } + slug := strings.Trim(b.String(), "-") + if slug == "" { + return "unknown" + } + return slug +} + // Adoption modes (Record.AdoptMode). const ( AdoptModeSupersede = "supersede" diff --git a/src/pkg/tokens/agent_home_trees.go b/src/pkg/tokens/agent_home_trees.go new file mode 100644 index 0000000000..5323286b46 --- /dev/null +++ b/src/pkg/tokens/agent_home_trees.go @@ -0,0 +1,87 @@ +package tokens + +import ( + "os" + "path/filepath" + "sort" + "strings" +) + +// perAgentHomesDirName is the directory under the shared HOME root that holds +// the per-agent HOMEs (crux/agent interactiveHomeRootName): each per-UID agent +// runs with HOME=<shared-home>/agents/<name>. +const perAgentHomesDirName = "agents" + +// claudeProjectsRel is Claude Code's session+memory tree under a HOME. +const claudeProjectsRel = ".claude/projects" + +// bobHomeRel is bobshell's state tree under a HOME. +const bobHomeRel = ".bob" + +// SessionTree is one CLI session-state directory to scan plus the agent that +// owns it ("" for the legacy shared directory, where ownership is inferred +// per file). +type SessionTree struct { + Dir string + Agent string +} + +// perAgentSessionTrees returns sharedDir plus every per-agent tree beside it. +// rel is the CLI's state path under a HOME (".claude/projects"); the per-agent +// trees are derived only when sharedDir ends in rel, so an operator pointing +// the scanner at an arbitrary directory gets exactly that directory. +// +// Since hivecommons/hive#9444 (.copilot) and hivecommons/hive#17031 +// (.claude / .gemini / .bob) each per-UID agent's CLI state is a REAL +// directory under its own HOME rather than a symlink into the shared one, so +// a scan of the shared path alone would miss every new session. +func perAgentSessionTrees(sharedDir, rel string) []SessionTree { + if sharedDir == "" { + return nil + } + trees := []SessionTree{{Dir: sharedDir}} + rel = filepath.FromSlash(rel) + clean := filepath.Clean(sharedDir) + if !strings.HasSuffix(clean, string(filepath.Separator)+rel) { + return trees + } + home := filepath.Clean(strings.TrimSuffix(clean, string(filepath.Separator)+rel)) + matches, err := filepath.Glob(filepath.Join(home, perAgentHomesDirName, "*", rel)) + if err != nil { + return trees + } + sort.Strings(matches) + // The CLI's top-level state dir under the agent HOME (".claude" of + // ".claude/projects"): when it is still a legacy symlink bridge into the + // shared home, the match IS the shared tree and scanning it again would + // double-count every shared session under the wrong owner. + top := rel + if i := strings.Index(rel, string(filepath.Separator)); i >= 0 { + top = rel[:i] + } + for _, m := range matches { + agentHome := strings.TrimSuffix(m, string(filepath.Separator)+rel) + agent := filepath.Base(agentHome) + if agent == "" || agent == "." || strings.HasPrefix(agent, ".") { + continue + } + if info, err := os.Lstat(filepath.Join(agentHome, top)); err != nil || info.Mode()&os.ModeSymlink != 0 { + continue + } + trees = append(trees, SessionTree{Dir: m, Agent: agent}) + } + return trees +} + +// ClaudeSessionTrees returns the configured claude_sessions_dir plus every +// per-agent <home>/agents/<name>/.claude/projects beside it +// (hivecommons/hive#17031). +func ClaudeSessionTrees(sharedDir string) []SessionTree { + return perAgentSessionTrees(sharedDir, claudeProjectsRel) +} + +// BobSessionTrees returns the configured bob_sessions_dir plus every +// per-agent <home>/agents/<name>/.bob beside it (hivecommons/hive#17031). +func BobSessionTrees(sharedDir string) []SessionTree { + return perAgentSessionTrees(sharedDir, bobHomeRel) +} diff --git a/src/pkg/tokens/agent_home_trees_test.go b/src/pkg/tokens/agent_home_trees_test.go new file mode 100644 index 0000000000..13716cae7c --- /dev/null +++ b/src/pkg/tokens/agent_home_trees_test.go @@ -0,0 +1,177 @@ +package tokens + +import ( + "os" + "path/filepath" + "strconv" + "testing" + "time" +) + +// Since hivecommons/hive#17031 every per-UID agent's ~/.claude and ~/.bob are +// REAL directories under <home>/agents/<name>, not bridges into the shared +// home, so the dashboard's claude_sessions_dir / bob_sessions_dir scans must +// also walk the per-agent trees or every new session goes uncounted. + +func TestClaudeSessionTrees_DerivesPerAgentHomes(t *testing.T) { + home := t.TempDir() + shared := filepath.Join(home, ".claude", "projects") + for _, a := range []string{"scanner", "reviewer", ".hidden"} { + if err := os.MkdirAll(filepath.Join(home, "agents", a, ".claude", "projects"), 0o755); err != nil { + t.Fatal(err) + } + } + if err := os.MkdirAll(shared, 0o755); err != nil { + t.Fatal(err) + } + // A per-agent home still carrying the legacy whole-directory bridge + // resolves to the shared tree and must not be scanned a second time + // (and under the wrong owner); a home with no .claude must not appear. + if err := os.MkdirAll(filepath.Join(home, "agents", "legacy"), 0o755); err != nil { + t.Fatal(err) + } + if err := os.Symlink(filepath.Join(home, ".claude"), filepath.Join(home, "agents", "legacy", ".claude")); err != nil { + t.Fatal(err) + } + if err := os.MkdirAll(filepath.Join(home, "agents", "inference-only"), 0o755); err != nil { + t.Fatal(err) + } + + trees := ClaudeSessionTrees(shared) + if len(trees) != 3 { + t.Fatalf("trees = %+v, want shared + reviewer + scanner", trees) + } + if trees[0].Dir != shared || trees[0].Agent != "" { + t.Errorf("trees[0] = %+v, want shared dir with no agent", trees[0]) + } + if trees[1].Agent != "reviewer" || trees[2].Agent != "scanner" { + t.Errorf("per-agent trees = %+v", trees[1:]) + } + if trees[2].Dir != filepath.Join(home, "agents", "scanner", ".claude", "projects") { + t.Errorf("scanner dir = %q", trees[2].Dir) + } +} + +func TestClaudeSessionTrees_NonCanonicalDirIsSharedOnly(t *testing.T) { + if got := ClaudeSessionTrees(""); got != nil { + t.Errorf("empty dir → %+v, want nil", got) + } + got := ClaudeSessionTrees("/some/custom/projects") + if len(got) != 1 || got[0].Dir != "/some/custom/projects" { + t.Errorf("custom dir → %+v", got) + } +} + +func TestBobSessionTrees_DerivesPerAgentHomes(t *testing.T) { + home := t.TempDir() + shared := filepath.Join(home, ".bob") + for _, a := range []string{"quality", "scanner"} { + if err := os.MkdirAll(filepath.Join(home, "agents", a, ".bob"), 0o755); err != nil { + t.Fatal(err) + } + } + trees := BobSessionTrees(shared) + if len(trees) != 3 || trees[0].Dir != shared || trees[1].Agent != "quality" || trees[2].Agent != "scanner" { + t.Fatalf("trees = %+v", trees) + } +} + +// A Claude session in a per-agent tree is attributed to that agent even when +// its project directory name encodes no agent work dir (a worktree cwd), and +// the dashboard sees sessions from BOTH the shared and per-agent trees. +func TestCollectorScansPerAgentClaudeHomes(t *testing.T) { + metricsDir := t.TempDir() + home := t.TempDir() + shared := filepath.Join(home, ".claude", "projects") + if err := os.MkdirAll(shared, 0o755); err != nil { + t.Fatal(err) + } + now := time.Now().UTC().Format(time.RFC3339) + line := func(in, out int64) string { + return `{"type":"human","timestamp":"` + now + `","message":{"text":"please continue"}}` + "\n" + + `{"type":"assistant","timestamp":"` + now + `","message":{"model":"claude-opus-5.5","usage":{"input_tokens":` + + strconv.FormatInt(in, 10) + `,"output_tokens":` + strconv.FormatInt(out, 10) + `}}}` + "\n" + } + write := func(projectsDir, proj, session, body string) { + t.Helper() + if err := os.MkdirAll(filepath.Join(projectsDir, proj), 0o755); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(filepath.Join(projectsDir, proj, session+".jsonl"), []byte(body), 0o600); err != nil { + t.Fatal(err) + } + } + // Legacy shared tree: agent from the project-dir path hint. + write(shared, "-data-agents-coder", "c1", line(100, 10)) + // Per-agent reviewer tree, worktree cwd: no path hint and no keyword, so + // the home it sits in owns it (the shared scan would have said "unknown"). + write(filepath.Join(home, "agents", "reviewer", ".claude", "projects"), "-home-wt-pr-1", "r1", line(200, 20)) + // Per-agent scanner tree, canonical cwd: path hint and owner agree. + write(filepath.Join(home, "agents", "scanner", ".claude", "projects"), "-data-agents-scanner", "s1", line(300, 30)) + + c := NewCollector(metricsDir, testLogger()) + c.SetPersistPath(filepath.Join(metricsDir, "token-summary.json")) + c.SetClaudeSessionsDir(shared) + c.scan() + + summary := c.Summary() + if summary == nil { + t.Fatal("nil summary") + } + want := map[string]int64{"coder": 110, "reviewer": 220, "scanner": 330} + for agent, tokens := range want { + if got := summary.ByAgent[agent]; got != tokens { + t.Errorf("ByAgent[%s] = %d, want %d (ByAgent=%v)", agent, got, tokens, summary.ByAgent) + } + } +} + +// A bob recording in a per-agent ~/.bob whose project hash is not in that +// tree's trustedFolders.json is attributed to the tree owner, not "bob", and +// its error streak is reported under that agent. +func TestCollectorScansPerAgentBobHomes(t *testing.T) { + metricsDir := t.TempDir() + home := t.TempDir() + shared := filepath.Join(home, ".bob") + if err := os.MkdirAll(shared, 0o755); err != nil { + t.Fatal(err) + } + now := time.Now() + base := now.Add(-2 * time.Hour) + qualityHome := filepath.Join(home, "agents", "quality", ".bob") + if err := os.MkdirAll(qualityHome, 0o755); err != nil { + t.Fatal(err) + } + writeBobChat(t, qualityHome, "/home/wt/pr-7", "s1", map[string]any{ + "sessionId": "s1", + "startTime": ts(base, 0), + "lastUpdated": ts(base, 90), + "messages": []map[string]any{ + {"type": "user", "timestamp": ts(base, 0), "content": "kick 1"}, + {"type": "bob-shell", "timestamp": ts(base, 1), "model": "premium", + "tokens": map[string]int64{"input": 100, "output": 20}}, + {"type": "user", "timestamp": ts(base, 30), "content": "kick 2"}, + {"type": "bob-shell", "timestamp": ts(base, 31), "model": "premium", + "tokens": map[string]int64{"input": 0, "output": 0}}, + }, + }) + + c := NewCollector(metricsDir, testLogger()) + c.SetPersistPath(filepath.Join(metricsDir, "token-summary.json")) + c.SetBobSessionsDir(shared) + c.scan() + + summary := c.Summary() + if summary == nil { + t.Fatal("nil summary") + } + if got := summary.ByAgent["quality"]; got != 120 { + t.Errorf("ByAgent[quality] = %d, want 120 (ByAgent=%v)", got, summary.ByAgent) + } + if _, leaked := summary.ByAgent[bobUnknownAgent]; leaked { + t.Errorf("per-agent recording fell back to %q: %v", bobUnknownAgent, summary.ByAgent) + } + if streaks := c.AgentErrorStreaks(); streaks["quality"] != 1 { + t.Errorf("AgentErrorStreaks = %v, want quality:1", streaks) + } +} diff --git a/src/pkg/tokens/bob_scanner.go b/src/pkg/tokens/bob_scanner.go index a827270338..2fec6cfd22 100644 --- a/src/pkg/tokens/bob_scanner.go +++ b/src/pkg/tokens/bob_scanner.go @@ -95,10 +95,19 @@ const maxBobSessionAge = 30 * 24 * time.Hour // given directory (typically /data/home/.bob or ~/.bob) and returns an // AggregateSummary. It walks tmp/*/chats/*.json looking for session recordings. func ScanBobSessionsWithLogger(bobHomeDir string, logger *slog.Logger) (*AggregateSummary, error) { - return scanBobSessions(bobHomeDir, logger) + return scanBobSessions(bobHomeDir, "", logger) } -func scanBobSessions(bobHomeDir string, logger *slog.Logger) (*AggregateSummary, error) { +// ScanBobSessionTree is ScanBobSessionsWithLogger for one tree whose owner is +// already known: defaultAgent, when non-empty, is the agent whose per-agent +// HOME holds bobHomeDir (hivecommons/hive#17031) and replaces the generic +// "bob" fallback for recordings whose project hash is not in that tree's +// trustedFolders.json. +func ScanBobSessionTree(bobHomeDir, defaultAgent string, logger *slog.Logger) (*AggregateSummary, error) { + return scanBobSessions(bobHomeDir, defaultAgent, logger) +} + +func scanBobSessions(bobHomeDir, defaultAgent string, logger *slog.Logger) (*AggregateSummary, error) { agg := &AggregateSummary{ ByAgent: make(map[string]int64), ByModel: make(map[string]int64), @@ -211,7 +220,7 @@ func scanBobSessions(bobHomeDir string, logger *slog.Logger) (*AggregateSummary, if projectHash == "" { projectHash = extractBobProjectHash(path) } - agentName := bobAgentName(projectHash, agentsByHash) + agentName := bobAgentName(projectHash, agentsByHash, defaultAgent) agg.TotalTokens += total agg.TotalMessages += messageCount agg.SessionCount++ @@ -338,11 +347,18 @@ func hexLower(b []byte) string { return string(out) } -func bobAgentName(projectHash string, agentsByHash map[string]string) string { +// bobUnknownAgent is the attribution for a recording whose project hash is +// not trusted-folder-mapped and whose tree has no known owner. +const bobUnknownAgent = "bob" + +func bobAgentName(projectHash string, agentsByHash map[string]string, defaultAgent string) string { if agent := agentsByHash[strings.TrimSpace(projectHash)]; agent != "" { return agent } - return "bob" + if defaultAgent != "" { + return defaultAgent + } + return bobUnknownAgent } func extractBobProjectHash(path string) string { diff --git a/src/pkg/tokens/claude_scanner.go b/src/pkg/tokens/claude_scanner.go index b082d52c8e..c2f366ec3c 100644 --- a/src/pkg/tokens/claude_scanner.go +++ b/src/pkg/tokens/claude_scanner.go @@ -334,12 +334,33 @@ func HiveAgentDetector(filePath string) func(string) string { } } +// treeAgentDetector is HiveAgentDetector with the tree owner as the fallback +// instead of the keyword guess: the path hint still wins when present (a +// session started from another agent's work dir is attributed there). +func treeAgentDetector(filePath, defaultAgent string) func(string) string { + return func(string) string { + if agent := AgentFromTmuxEnv(filePath); agent != "" { + return agent + } + return defaultAgent + } +} + // ScanClaudeSessionsWithPathDetection reads Claude Code's native session JSONL // files from the given projects directory (typically ~/.claude/projects), // using the file path to help determine which agent owns each session. It // scans all *.jsonl files in all subdirectories (project hashes), plus any // subagent files in */subagents/*.jsonl. func ScanClaudeSessionsWithPathDetection(projectsDir string) (*AggregateSummary, error) { + return ScanClaudeSessionTree(projectsDir, "") +} + +// ScanClaudeSessionTree is ScanClaudeSessionsWithPathDetection for one tree +// whose owner is already known: defaultAgent, when non-empty, is the agent +// whose per-agent HOME holds projectsDir (hivecommons/hive#17031) and is used +// whenever the project-directory name does not itself encode an agent work +// dir, instead of the keyword guess from the first user message. +func ScanClaudeSessionTree(projectsDir, defaultAgent string) (*AggregateSummary, error) { agg := &AggregateSummary{ ByAgent: make(map[string]int64), ByModel: make(map[string]int64), @@ -375,6 +396,9 @@ func ScanClaudeSessionsWithPathDetection(projectsDir string) (*AggregateSummary, } detector := HiveAgentDetector(file) + if defaultAgent != "" { + detector = treeAgentDetector(file, defaultAgent) + } summary, err := parseClaudeSessionFile(file, detector) if err != nil || summary == nil || summary.TotalTokens == 0 { continue diff --git a/src/pkg/tokens/collector.go b/src/pkg/tokens/collector.go index d2d98d8181..3cb0a0ca7a 100644 --- a/src/pkg/tokens/collector.go +++ b/src/pkg/tokens/collector.go @@ -338,12 +338,17 @@ func (c *Collector) scan() { c.mergeClineUsage(agg) if c.claudeSessionsDir != "" { - claudeAgg, err := ScanClaudeSessionsWithPathDetection(c.claudeSessionsDir) - if err != nil { - c.logger.Warn("claude session scan failed", "error", err) - diag.LastClaudeScanError = err.Error() - } else if claudeAgg != nil && claudeAgg.SessionCount > 0 { - MergeAggregates(agg, claudeAgg) + // Shared tree plus every per-agent ~/.claude/projects: since + // hivecommons/hive#17031 each agent's transcripts live under its own + // HOME, so the shared path alone would miss every new session. + for _, tree := range ClaudeSessionTrees(c.claudeSessionsDir) { + claudeAgg, err := ScanClaudeSessionTree(tree.Dir, tree.Agent) + if err != nil { + c.logger.Warn("claude session scan failed", "dir", tree.Dir, "error", err) + diag.LastClaudeScanError = err.Error() + } else if claudeAgg != nil && claudeAgg.SessionCount > 0 { + MergeAggregates(agg, claudeAgg) + } } } @@ -369,18 +374,26 @@ func (c *Collector) scan() { } if c.bobSessionsDir != "" { - bobAgg, err := ScanBobSessionsWithLogger(c.bobSessionsDir, c.logger) - if err != nil { - c.logger.Warn("bob session scan failed", "error", err) - diag.LastBobScanError = err.Error() - } else if bobAgg != nil && bobAgg.SessionCount > 0 { - MergeAggregates(agg, bobAgg) - } // Per-agent consecutive model-call failure streaks (#5577/#5338), - // derived from the same recordings this scan just walked. Always - // stored non-nil after a scan, so AgentErrorStreaks can distinguish + // derived from the same recordings this scan walks. Always stored + // non-nil after a scan, so AgentErrorStreaks can distinguish // "measured, none failing" (empty) from "never scanned" (nil). - streaks := BobAgentErrorStreaks(c.bobSessionsDir, time.Now()) + streaks := make(map[string]int) + now := time.Now() + for _, tree := range BobSessionTrees(c.bobSessionsDir) { + bobAgg, err := ScanBobSessionTree(tree.Dir, tree.Agent, c.logger) + if err != nil { + c.logger.Warn("bob session scan failed", "dir", tree.Dir, "error", err) + diag.LastBobScanError = err.Error() + } else if bobAgg != nil && bobAgg.SessionCount > 0 { + MergeAggregates(agg, bobAgg) + } + for agent, n := range BobAgentErrorStreaksForTree(tree.Dir, tree.Agent, now) { + if n > streaks[agent] { + streaks[agent] = n + } + } + } c.mu.Lock() c.errorStreaks = streaks c.mu.Unlock() diff --git a/src/pkg/tokens/copilot_scanner.go b/src/pkg/tokens/copilot_scanner.go index 895225949b..cfef6ff557 100644 --- a/src/pkg/tokens/copilot_scanner.go +++ b/src/pkg/tokens/copilot_scanner.go @@ -5,7 +5,6 @@ import ( "encoding/json" "os" "path/filepath" - "sort" "strings" "time" ) @@ -109,16 +108,9 @@ type CopilotScanOptions struct { // copilotSessionStateRel is the Copilot CLI session-state path under a HOME. const copilotSessionStateRel = ".copilot/session-state" -// copilotPerAgentHomesDirName is the directory under the shared HOME root that -// holds the per-agent HOMEs (pkg/agent interactiveHomeRootName). -const copilotPerAgentHomesDirName = "agents" - // CopilotSessionTree is one Copilot session-state directory to scan plus the // agent that owns it ("" for the legacy shared directory). -type CopilotSessionTree struct { - Dir string - Agent string -} +type CopilotSessionTree = SessionTree // CopilotSessionTrees returns the configured shared session-state directory // plus every per-agent tree beside it. Since hivecommons/hive#9444 each @@ -129,30 +121,7 @@ type CopilotSessionTree struct { // The per-agent trees are derived only when sharedDir has the canonical // <home>/.copilot/session-state shape. func CopilotSessionTrees(sharedDir string) []CopilotSessionTree { - if sharedDir == "" { - return nil - } - trees := []CopilotSessionTree{{Dir: sharedDir}} - rel := filepath.FromSlash(copilotSessionStateRel) - if !strings.HasSuffix(filepath.Clean(sharedDir), rel) { - return trees - } - home := strings.TrimSuffix(filepath.Clean(sharedDir), rel) - home = filepath.Clean(home) - matches, err := filepath.Glob(filepath.Join(home, copilotPerAgentHomesDirName, "*", rel)) - if err != nil { - return trees - } - sort.Strings(matches) - for _, m := range matches { - agentHome := strings.TrimSuffix(m, string(filepath.Separator)+rel) - agent := filepath.Base(agentHome) - if agent == "" || agent == "." || strings.HasPrefix(agent, ".") { - continue - } - trees = append(trees, CopilotSessionTree{Dir: m, Agent: agent}) - } - return trees + return perAgentSessionTrees(sharedDir, copilotSessionStateRel) } // ScanCopilotSessions reads Copilot CLI session files from one session-state diff --git a/src/pkg/tokens/error_streak.go b/src/pkg/tokens/error_streak.go index def673e23e..9ba0728251 100644 --- a/src/pkg/tokens/error_streak.go +++ b/src/pkg/tokens/error_streak.go @@ -73,6 +73,12 @@ type bobTurn struct { // result is always non-nil (an empty map means "measured, no streaks") so // callers can tell a clean fleet from a scan that never ran. func BobAgentErrorStreaks(bobHomeDir string, now time.Time) map[string]int { + return BobAgentErrorStreaksForTree(bobHomeDir, "", now) +} + +// BobAgentErrorStreaksForTree is BobAgentErrorStreaks for one tree whose +// owner is already known (see ScanBobSessionTree). +func BobAgentErrorStreaksForTree(bobHomeDir, defaultAgent string, now time.Time) map[string]int { out := make(map[string]int) if bobHomeDir == "" { return out @@ -120,7 +126,7 @@ func BobAgentErrorStreaks(bobHomeDir string, now time.Time) map[string]int { if projectHash == "" { projectHash = extractBobProjectHash(path) } - agentName := bobAgentName(projectHash, agentsByHash) + agentName := bobAgentName(projectHash, agentsByHash, defaultAgent) rec := sessRec{agent: agentName, start: bobSessionFirstActive(sess)} for i := range sess.Messages { diff --git a/src/pkg/writeback/testdata/direct-writes-baseline.txt b/src/pkg/writeback/testdata/direct-writes-baseline.txt index 7b66f292e9..201a0d5521 100644 --- a/src/pkg/writeback/testdata/direct-writes-baseline.txt +++ b/src/pkg/writeback/testdata/direct-writes-baseline.txt @@ -9,11 +9,12 @@ raw pkg/github/automerge/automerge_bot_takeover.go 2 raw pkg/github/automerge/automerge_contributor_adopt.go 15 raw pkg/github/automerge/automerge_contributor_held_runs.go 1 raw pkg/github/automerge/automerge_contributor_lane.go 3 -raw pkg/github/automerge/automerge_contributor_nudge.go 2 +raw pkg/github/automerge/automerge_contributor_nudge.go 1 raw pkg/github/automerge/automerge_contributor_workflow_approval.go 1 raw pkg/github/automerge/automerge_held_runs.go 3 raw pkg/github/automerge/automerge_merge_commit.go 1 raw pkg/github/automerge/automerge_merge_forward.go 1 +raw pkg/github/automerge/automerge_signoff_attribution.go 1 raw pkg/github/automerge/automerge_stage_human.go 1 raw pkg/github/automerge/automerge_stage_labels.go 3 raw pkg/github/automerge/automerge_sweep_queued.go 3 diff --git a/src/proxy/package-lock.json b/src/proxy/package-lock.json index 86be927a62..f28302412e 100644 --- a/src/proxy/package-lock.json +++ b/src/proxy/package-lock.json @@ -12,7 +12,7 @@ "http-proxy-middleware": "^4.2.1" }, "devDependencies": { - "ws": "^8.21.3" + "ws": "^8.22.1" } }, "node_modules/accepts": { @@ -965,9 +965,9 @@ "license": "ISC" }, "node_modules/ws": { - "version": "8.21.3", - "resolved": "https://registry.npmjs.org/ws/-/ws-8.21.3.tgz", - "integrity": "sha512-201TZ/kPWxoPr/OKWjquZR1SWKXcvxdH+e1xrx89b3YbmzLMFCLfnaG1HFIgWzJOEWZ7MvpK++odZufgYR50Rw==", + "version": "8.22.1", + "resolved": "https://registry.npmjs.org/ws/-/ws-8.22.1.tgz", + "integrity": "sha512-oyL6OPYme/CmiFvNuGzeoxCJ4nOrZE2O1FwM9MWM1AsGri6nLXB2pg+lNA8aLeXMSav0J6eIVS1j6vUPzUtK9g==", "dev": true, "license": "MIT", "engines": { diff --git a/src/proxy/package.json b/src/proxy/package.json index 812c1cb73b..7596b682e1 100644 --- a/src/proxy/package.json +++ b/src/proxy/package.json @@ -14,6 +14,6 @@ "http-proxy-middleware": "^4.2.1" }, "devDependencies": { - "ws": "^8.21.3" + "ws": "^8.22.1" } } diff --git a/src/scripts/test-release-push-retry.sh b/src/scripts/test-release-push-retry.sh index e29a885ee0..34d203844f 100755 --- a/src/scripts/test-release-push-retry.sh +++ b/src/scripts/test-release-push-retry.sh @@ -17,12 +17,19 @@ # change. The API endpoint is evaluated against the required contexts for # that SHA instead. The step distinguishes three ways that merge can fail: # not-yet-mergeable — HTTP 405: a required check has not landed / GitHub is -# still settling: retry on a deadline, then hard-fail. -# base moved — HTTP 409 (base OR head branch modified): v4 advanced -# past the release SHA: defer GREEN with pushed=false, -# because the successor run releases the newer merge and -# retagging here would publish images built from a -# different tree. +# still settling: retry on a deadline, then hard-fail. A +# 405 whose PR is CONFLICTING (mergeable_state dirty) is +# hard-failed at once: no retry resolves a conflict. +# base moved — HTTP 409 "Base branch was modified": v5 advanced since +# GitHub computed mergeability. Since the tag names the +# RELEASE COMMIT (parented on the built SHA) rather than +# the merge commit, a moved tip is no reason to defer: the +# merge-commit PR is retried on the same deadline. (Until +# 2026-11 this deferred green, which under sustained +# merges stalled tagging for three weeks.) +# head moved — HTTP 409 "Head branch was modified": the `sha=` guard +# fired; hard-fail, nothing legitimate rewrites the +# scratch branch. # anything else — hard-fail immediately, no retry. # # Since #5356 the step first mirrors the already-verified docker.yml check-run @@ -87,7 +94,8 @@ case "$1 $2 ${3:-}" in "rev-parse HEAD ") echo "deadbeefcafe0000000000000000000000000000"; exit 0 ;; "rev-parse origin/v5 ") - echo "deadbeefcafe"; exit 0 ;; + # RPR_TIP=moved simulates v5 having advanced past the built SHA. + if [ "${RPR_TIP:-built}" = moved ]; then echo "0123456789abcdef0123456789abcdef01234567"; else echo "deadbeefcafe"; fi; exit 0 ;; "fetch origin "*) exit 0 ;; "tag "*) @@ -150,6 +158,15 @@ case "$args" in base_moved) echo "gh: Base branch was modified. Review and try the merge again. (HTTP 409)" exit 1 ;; + base_moved_then_ok) + if [ "$n" -le 2 ]; then + echo "gh: Base branch was modified. Review and try the merge again. (HTTP 409)" + exit 1 + fi + echo '{"sha":"feedfacefeedfacefeedfacefeedfacefeedface","merged":true,"message":"Pull Request successfully merged"}'; exit 0 ;; + conflict) + echo "gh: Pull Request is not mergeable (HTTP 405)" + exit 1 ;; head_moved) echo "gh: Head branch was modified. Review and try the merge again. (HTTP 409)" exit 1 ;; @@ -158,6 +175,13 @@ case "$args" in exit 1 ;; esac ;; esac +case "$args" in + *"/pulls/9999"*) + # mergeable_state probe on a 405 (conflict detection). + # The step applies --jq '.mergeable_state', so answer with the bare value. + if [ "$RPR_SCENARIO" = conflict ]; then echo dirty; else echo blocked; fi + exit 0 ;; +esac case "$1 $2" in "workflow run") echo dispatch >> "$state/timeline" @@ -165,6 +189,17 @@ case "$1 $2" in *"docker.yml --ref v5"*"release_sha=feedfacefeedfacefeedfacefeedfacefeedface"*) ;; *) echo "STUBFAIL: release dispatch did not carry exact merge SHA: $args" >&2; exit 1 ;; esac + # The merge commit may self-report the tag only when v5 was still at the + # built SHA; a merge onto a moved tip carries newer work and must not. + tip="${RPR_TIP:-built}" + # A 409 base-moved retry means v5 moved mid-flight, same as a moved tip. + [ "$RPR_SCENARIO" = base_moved_then_ok ] && tip=moved + case "${tip}:$args" in + built:*"release_version=v4.0.1"*) ;; + moved:*"release_version="*) echo "STUBFAIL: release_version passed although v5 had moved past the built SHA: $args" >&2; exit 1 ;; + moved:*) ;; + *) echo "STUBFAIL: release dispatch lacks release_version although v5 was at the built SHA: $args" >&2; exit 1 ;; + esac if [ "$RPR_SCENARIO" = dispatch_fails ]; then echo "gh: failed to create workflow dispatch event (HTTP 422)" >&2 exit 1 @@ -197,11 +232,11 @@ run_step() { # a prior case's gh_output/attempt counters into later assertions. st="$(mktemp -d "$tmp/state.XXXXXX")" : > "$st/out" - RPR_SCENARIO="$1" RPR_TAG_SCENARIO="${2:-ok}" RPR_STATE="$st" \ + RPR_SCENARIO="$1" RPR_TAG_SCENARIO="${2:-ok}" RPR_STATE="$st" RPR_TIP="${RPR_TIP:-built}" \ RELEASE_MERGE_WAIT_SECONDS="${3:-120}" RELEASE_MERGE_POLL_SECONDS=8 \ VERSION="4.0.1" SHA="deadbeefcafe" GITHUB_OUTPUT="$st/gh_output" \ - RELEASE_LINE="v5" \ ACTIONS_TOKEN="actions-token-for-test" \ + RELEASE_LINE="v5" \ GITHUB_REPOSITORY="hivecommons/hive" \ PATH="$tmp/bin:$PATH" bash "$tmp/push_line.sh" > "$st/out" 2>&1 rc=$? @@ -214,9 +249,9 @@ run_step ok [ "$rc" -eq 0 ] && note_ok "exit 0" || note_fail "exit $rc, want 0: $output" grep -q '^pushed=true$' <<<"$ghout" && note_ok "pushed=true" || note_fail "GITHUB_OUTPUT lacks pushed=true: $ghout" [ "$(cat "$st/tag" 2>/dev/null)" = 1 ] && note_ok "tag pushed once" || note_fail "tag not pushed exactly once" -[ "$(cat "$st/tag_target" 2>/dev/null)" = feedfacefeedfacefeedfacefeedfacefeedface ] \ - && note_ok "version tag targets merge API's exact release SHA" \ - || note_fail "version tag did not target merge API SHA: $(cat "$st/tag_target" 2>/dev/null)" +[ "$(cat "$st/tag_target" 2>/dev/null)" = deadbeefcafe0000000000000000000000000000 ] \ + && note_ok "version tag targets the release commit (built tree + changelog), not the merge commit" \ + || note_fail "version tag did not target the release commit: $(cat "$st/tag_target" 2>/dev/null)" [ "$(tr '\n' ' ' < "$st/timeline")" = "status pr merge dispatch status " ] \ && note_ok "gate, PR, merge, exact-SHA dispatch, and hold-clear status are ordered" \ || note_fail "unexpected status/PR/merge order: $(tr '\n' ' ' < "$st/timeline")" @@ -277,23 +312,48 @@ run_step settle_forever ok 0 grep -q '::error::' <<<"$output" && note_ok "::error:: emitted" || note_fail "no ::error:: on exhaustion: $output" [ -f "$st/tag" ] && note_fail "tag was pushed despite the merge failing" || note_ok "no tag pushed" -echo "case: base branch moved defers green with pushed=false" -run_step base_moved -[ "$rc" -eq 0 ] && note_ok "exit 0 (deferral is not a failure)" || note_fail "exit $rc, want 0: $output" -grep -q '^pushed=false$' <<<"$ghout" && note_ok "pushed=false" || note_fail "GITHUB_OUTPUT lacks pushed=false: $ghout" -# #5318: a deferral is a SKIPPED RELEASE OPPORTUNITY and must surface as a -# ::warning:: (visible in the run list and the job summary), not a ::notice:: -# that scrolls past unread. Assert the stronger annotation specifically. -grep -q '::warning::' <<<"$output" && note_ok "::warning:: makes the skipped opportunity visible" || note_fail "deferral is not surfaced as a warning: $output" -[ -f "$st/tag" ] && note_fail "tag was pushed for a release that deferred" || note_ok "no tag pushed" -[ "$(cat "$st/merge")" = 1 ] && note_ok "no pointless retry of a lost race" || note_fail "base-moved was retried; it can never succeed without a rebase" +echo "case: base branch moved is retried and the release still lands (tag names the release commit)" +run_step base_moved_then_ok +[ "$rc" -eq 0 ] && note_ok "exit 0" || note_fail "exit $rc, want 0: $output" +[ "$(cat "$st/merge")" = 3 ] && note_ok "3 merge attempts" || note_fail "$(cat "$st/merge") attempts, want 3" +grep -q '^pushed=true$' <<<"$ghout" && note_ok "pushed=true" || note_fail "GITHUB_OUTPUT lacks pushed=true: $ghout" +grep -q 'pushed=false' <<<"$ghout" && note_fail "base-moved was still deferred — that is the 2026-10/11 three-week stall" || note_ok "no deferral on a moved base" +[ "$(cat "$st/tag_target" 2>/dev/null)" = deadbeefcafe0000000000000000000000000000 ] \ + && note_ok "tag still names the release commit after a merge-commit landing" \ + || note_fail "tag target after base-moved retry: $(cat "$st/tag_target" 2>/dev/null)" + +echo "case: base branch moving past the deadline hard-fails (no silent deferral)" +run_step base_moved ok 0 +[ "$rc" -ne 0 ] && note_ok "non-zero exit" || note_fail "exhausted base-moved retries must fail, got exit 0" +grep -q 'pushed=' <<<"$ghout" && note_fail "wrote a pushed= output on exhaustion" || note_ok "no pushed= output" +[ -f "$st/tag" ] && note_fail "tag was pushed although the merge never landed" || note_ok "no tag pushed" -echo "case: head branch moved also defers green (409 sha= guard)" +echo "case: head branch moved hard-fails (409 sha= guard)" run_step head_moved -[ "$rc" -eq 0 ] && note_ok "exit 0 (deferral is not a failure)" || note_fail "exit $rc, want 0: $output" -grep -q '^pushed=false$' <<<"$ghout" && note_ok "pushed=false" || note_fail "GITHUB_OUTPUT lacks pushed=false: $ghout" -[ -f "$st/tag" ] && note_fail "tag was pushed for a release that deferred" || note_ok "no tag pushed" -[ "$(cat "$st/merge")" = 1 ] && note_ok "no pointless retry of a lost race" || note_fail "head-moved was retried; it can never succeed" +[ "$rc" -ne 0 ] && note_ok "non-zero exit" || note_fail "head-moved must fail closed, got exit $rc: $output" +grep -q '::error::' <<<"$output" && note_ok "::error:: emitted" || note_fail "no ::error:: for head-moved: $output" +[ -f "$st/tag" ] && note_fail "tag was pushed for a rewritten scratch branch" || note_ok "no tag pushed" +[ "$(cat "$st/merge")" = 1 ] && note_ok "no pointless retry" || note_fail "head-moved was retried; it can never succeed" + +echo "case: conflicting release PR hard-fails at once" +run_step conflict +[ "$rc" -ne 0 ] && note_ok "non-zero exit" || note_fail "a CONFLICTING PR must fail, got exit 0" +grep -q 'conflicts with v5' <<<"$output" && note_ok "conflict diagnosed" || note_fail "conflict diagnostic absent: $output" +[ "$(cat "$st/merge")" = 1 ] && note_ok "not retried" || note_fail "$(cat "$st/merge") attempts, want 1" +[ -f "$st/tag" ] && note_fail "tag pushed despite conflict" || note_ok "no tag pushed" + +echo "case: v5 already past the built SHA goes straight to the PR path and releases" +RPR_TIP=moved run_step ok +[ "$rc" -eq 0 ] && note_ok "exit 0" || note_fail "exit $rc, want 0: $output" +grep -q '^pushed=true$' <<<"$ghout" && note_ok "pushed=true" || note_fail "GITHUB_OUTPUT lacks pushed=true: $ghout" +grep -q 'past the built commit' <<<"$output" && note_ok "moved tip announced, not deferred" || note_fail "moved-tip path not taken: $output" +grep -q 'Trying direct v5 push' <<<"$output" && note_fail "direct push attempted although it can only be non-fast-forward" || note_ok "direct push skipped" +[ "$(tr '\n' ' ' < "$st/timeline")" = "status pr merge dispatch status " ] \ + && note_ok "PR path ordered as usual" \ + || note_fail "unexpected order on moved tip: $(tr '\n' ' ' < "$st/timeline")" +[ "$(cat "$st/tag_target" 2>/dev/null)" = deadbeefcafe0000000000000000000000000000 ] \ + && note_ok "tag names the release commit, not the merge onto the moved tip" \ + || note_fail "tag target on moved tip: $(cat "$st/tag_target" 2>/dev/null)" echo "case: unrecognized merge failure hard-fails" run_step unknown @@ -405,9 +465,9 @@ else: guard_run = guard.get("run") or "" # #6380: the exact-SHA docker.yml handoff is a workflow_dispatch run on v5, # not a push. The backstop may count that publishing run. #10866 also - # needs a backstop-primed workflow_dispatch docker run on the line to - # re-enter this workflow once the images exist; post-release handoffs are - # harmless because Unreleased is empty by then. + # needs a backstop-primed v5 workflow_dispatch docker run to re-enter this + # workflow once the images exist; post-release handoffs are harmless + # because Unreleased is empty by then. if '.event == \\"workflow_dispatch\\"' not in guard_run or '.head_branch == \\"${RELEASE_LINE}\\"' not in guard_run: bad("the backstop no longer accepts the release line's workflow_dispatch docker.yml publishing runs (#6380)") if 'gh workflow run docker.yml --ref "$RELEASE_LINE"' not in guard_run: