v0.21.0

🚀 aiHelpDesk v0.21.0 release: The Cert That Tells the Truth

✅ Attribution-aware stability certs

The headline feature of this release. Every stability cert now carries an attr= label that names the conclusion the agent reached, not just whether it passed or failed.

  fault: k8s-oomkilled    playbook: pbs_k8s_pod_crash_triage    taxonomy: 1.0
  runs:  3   pass: 3/3 (100%)   STABLE(3) attr=oom-kill (3/3)   judge: 100%/100%/100%

  fault: k8s-crashloop    playbook: pbs_k8s_pod_crash_triage    taxonomy: 1.0
  runs:  3   pass: 3/3 (100%)   STABLE(3) attr=process-error (3/3)   judge: 100%/100%/100%

Same playbook, same pass rate, different attribution. And the cert captures that. This is the difference between a system that gets the right answer and one that knows why.

The three named stabilities are all live:

┌────────────┬─────────────────────────────────────────────────────┬────────────────────────────────┐
│ Stability  │                  What it measures                   │       Where it surfaces        │
├────────────┼─────────────────────────────────────────────────────┼────────────────────────────────┤
│ Outcome    │ Did the playbook pass?                              │ vault list STABLE column       │
├────────────┼─────────────────────────────────────────────────────┼────────────────────────────────┤
│ Conclusion │ Did the agent reach the same attribution every run? │ vault list attr= label         │
├────────────┼─────────────────────────────────────────────────────┼────────────────────────────────┤
│ Evaluation │ Did the judge agree with itself?                    │ vault accuracy when spread > 0 │
└────────────┴─────────────────────────────────────────────────────┴────────────────────────────────┘

Taxonomy versioning is also enforced: vault cert-compare warns when comparing certs across a major taxonomy bump: ⚠ TAXONOMY MAJOR 1.0→2.0: attribution comparison invalid.

✅ Taxonomy / attribution classes in all playbooks

All playbooks now include an attribution_taxonomy block naming the possible conclusion classes for each fault scenario. This feeds the attr= cert label and will underpin the calibration and judge-variance features coming in v0.22.0+.

✅ faulttest: synchronous remediation with waitForChildRunComplete

faulttest --remediate can now block until a playbook run that transitioned (escalated or triggered a child run) completes. Previously, remediation results for multi-step flows came back empty because the harness exited before the child run finished. The new waitForChildRunComplete polling loop fixes this, with a configurable timeout and no dependency on --audit-url.

SysAdmin Agent is now dynamically registered at faulttest startup and faulttest has a dedicated service account in the SysAdmin Agent's allowed list.

✅ faulttest: --operator security check

faulttest now validates that --operator matches a user in the configured users file before starting a run. Previously, a typo in the operator email would silently produce runs attributed to an unknown identity.

vault judge-accuracy: RESOLVED% / ESCALATED% split

The vault judge-accuracy output splits SUCCESS% into two columns:

  FAULT                    RESOLVED%   ESCALATED%   FAIL%   RUNS
  db-tx-lock-chain-blocker   60%          20%        20%      5

gate_pending and escalated_to outcomes are counted together in ESCALATED%, giving a clearer picture of how often the agent correctly recognizes it needs help vs. resolves independently.

vault suggest-update --file two-step import

vault suggest-update --file <path> now correctly performs a two-step import: it saves the draft first, then persists it. Previously the draft was discarded if the session ended before explicit confirmation.

--auto-db container registration now includes hosting_type and container_name so the Docker escalation path triggers correctly for auto-provisioned targets.

---

Bug fixes

• verify_sql returning false (dd8037d): caused faulttest remediation to always fail when the playbook issued a verification query. The boolean parsing now accepts both t and 1.
• --auto-db stability (bfd4e57, ce74561): fixed port re-randomization under Docker Desktop (now uses fixed host port mapping); fixed judge instability when container restarts changed the connection string mid-run.
• SysAdmin Agent prompt (19cf88d, db29140): wrong initial tool suggested in the sysadmin prompt; three additional transition bugs fixed.
• --approval-mode=force (7e53b41): two edge cases where force-approval mode didn't propagate correctly through the step execution chain.
• K8s playbook narratives (9fb8c6b): seven K8s playbooks were missing the narrative section required by the evaluation judge, causing false negatives on conclusion scoring.
• vault accuracy attribution (14ab714): attribution was sometimes attributed to the wrong run when multiple runs for the same fault existed in the database.
• vault cert-compare taxonomy warning: major-bump detection was checking the wrong field in the cert response; now correctly fires on taxonomy_version major component change.
• codecov config (8c52ffc): coverage threshold was still referencing the pre-split agentutil path from v0.20.0.

---

Infrastructure

• Integration test timeout bumped from 120s → 300s (9e5fa7b): the audit_monitor tests carry ~60s of mandatory sleeps (polling baseline + reconnect headroom); the 2-minute budget was being consumed before
  TestIdentity_FullPolicyDecisionRoundTrip could start. Also fixed a port 19912 collision between TestAuditorFabricationMismatchAlert and TestSecbotHTTPPollingReconnect.
• CI linter fix in autodb.go (8838ca3): l.Close() error return was unchecked.
• Test coverage additions for attribution, stability certs, ListBySeriesID, ListByOutcome, ActivateSystem, nextVersion, FaultStabilityStore migration and sysadmin policy enforcement.

---

Upgrade notes

No schema migrations required. The attribution_taxonomy field in playbooks is additive. Existing playbooks without it continue to work, they just won't produce attr= labels in certs until updated.

If you are running vault cert-compare in CI as a model upgrade gate, be aware that the command takes model names as positional arguments, not fault IDs. To display two faults side-by-side, use vault list --ids k8s-oomkilled,k8s-crashloop.

List of Changes:

[boris@ ~/helpdesk]$ git log release/v0.20.0..release/v0.21.0 --oneline
9e5fa7b (origin/release/v0.21.0, release/v0.21.0) fix: integration governance test fails in CI on timeouts.
e958e15 fix: add the missing test coverage based on the codecov report.
8838ca3 fix: CI linter issue in faulttest/autodb.go on Close.
9fb8c6b fix: add 7 missing narratives to the K8s PBs.
bf26835 chore: update the tool registry doc.
19cf88d fix: Wrong initial tool in sysadmin-agent prompt (playbooks.go).
dd8037d fix: verify_sql returning false, causing remediation in faulttest to fail.
bfd4e57 fix: got the RCA, two fixes on stable port +sysadmin-docker-restart PB instructions.
db29140 fix: three more fixes for sysadmin transition.
77d9e1f feat: add security check in faulttest --operator
7353c3f fix: two minor problems with --approval-mode=force.
6aea701 feat: add a SA for faulttest in sysadmin agent + waitForChildRunComplete wo/ --audit-url + sysadmin dynamic registration.
5834225 fix: regression in faulttest_test.go for calling Remediate.
62eac74 chore: add test coverage for enhanced faulttest (now capable of sync-waiting for transitioned PBs).
594b0e0 feat: close the gaps to allow faulttest to run sync ops (for PB transitions): r.waitForChildRunComplete.
4c6031f fix: count gate_pending+escalated_to as ESCALATED% in version stats.
563aa54 fix: `faulttest vault judge-accuracy` splits SUCCESS% into RESOLVED% + ESCALATED% columns
1416b02 fix: `vault suggest-update --file` now saves draft (two-step import+persist) + auto-db registers with hosting_type/container_name.
ce74561 fix: --auto-db problem with judge instability.
043372f fix: ANTHROPIC_API_KEY or HELPDESK_API_KEY are not set, but --judge or --remediate-judge requested.
ae101a9 fix: db-connection-refused fault: make it work with --auto-db.
14ab714 fix: vault accuracy attribution fix + run-time stability report + docs update.
3475cfd chore: add non unit test coverage for v0.21
bcbcb0c chore: add test coverage for the v0.21 features, attribution, stability, etc.
a3534e8 feat: add taxonomy/class attribution in all PBs.
f6359c6 fix: add a link to the blog post in the bench sample 10 doc.
c95cb1c fix: typos in bench sample 10.
b88bb48 chore: add bench sample 10 doc.
8c52ffc fix: codecov.yml wasn't updated to reflect the agentutil split.
7e53b41 (tag: v0.20.0) Merge pull request #20 from borisdali/release/v0.20.0

Full Changelog: v0.20.0...v0.21.0