tooling: mechanical soup dist guards (#921/#962 class)

[heavygee]

Summary

• Cursor shell guard: hapi-production-mutation-guard.sh now blocks feat-dist → driver swaps, raw driver/web builds, hand git merges on driver, and full hapi-driver-rebuild without --build-web. Pattern library in lib/driver-dist-guard-patterns.sh; smoke tests in hapi-production-mutation-guard.test.sh.
• Hook install: hapi-install-cursor-hooks.sh wires the production-mutation guard (alongside product-code and systemctl guards).
• Verify guard: verify-soup-web-dist.mjs derives soup integrity markers from merged driver/web/src (feature namespaces, non-baseline routes, lazy chunk basenames, scratchlist lib, mermaid data/class attrs, overseer debug UI) instead of a hardcoded string list. Also checks main-bundle and precache regression vs dist.prev.
• Agent rule: scripts/tooling/cursor-rules/hapi-driver-soup-dogfood.mdc documents the dogfood contract.
• Docs: docs/tooling/driver-soup.md mechanical guards section updated.

Prevention for #921 (feat web/dist copy rollback) and #962 (hand merge + raw build half-souping).

Test plan

• bash scripts/tooling/hapi-production-mutation-guard.test.sh — deny/allow patterns pass
• bun scripts/tooling/verify-soup-web-dist.mjs ~/coding/hapi/driver — OK (565 t() keys, 23 derived soup markers)
• Operator: merge PR, run scripts/tooling/hapi-install-cursor-hooks.sh on any machine that has not already

Issues

Ref #921 — mechanical guard layer; incident class prevention, not root fix.

Made with Cursor

[heavygee]

Closed: operator-fork tooling (docs/plans/cursor guards) belongs on heavygee/hapi main via PR, not upstream.

[github-actions]

Findings

• [Major] Watch activation drops excludes before the real switch drain — the watch loop filters out the launching agent, but then exec hapi-use-driver starts hapi-use-worktree, whose patient drain counts raw WORKING sessions again. A background watch launched with --exclude-agent-session can therefore enter the second 10-minute drain on the same session and eventually restart while that session is still live, which is the deadlock/failure this tooling says it fixes. Evidence scripts/tooling/hapi-watch-activate-driver.sh:131.
• [Major] Agent excludes hide every WORKING row with a missing agent id — when $agent is set and .agentSessionId is null/missing, $aid becomes ""; $agent | startswith($aid) is always true, so the filter drops unrelated WORKING sessions that lack agent metadata. That can make the drain report zero blockers and proceed while another agent is active. Evidence scripts/tooling/lib/patient-drain.sh:38.

Questions

• None.

Summary

• Review mode: initial
• Reviewed the full PR diff, with executable focus on hub storage and the newly added operator tooling/scripts. Two patient-drain regressions found in the added watch/switch path.

Testing

• Not run (automation)

HAPI Bot

[github-actions]

[Major] Watch activation drops excludes before the real switch drain

This line hands off to hapi-use-driver without preserving the --exclude-* values, and hapi-use-driver immediately execs hapi-use-worktree, whose patient drain currently counts raw WORKING rows. So the watch can correctly reach zero after excluding the launching agent, then the actual switch waits on that same agent again and eventually proceeds after the timeout, killing the session it was supposed to exclude.

Suggested fix:

activate_driver() {
    export HAPI_STACK_SWITCH_YES=1
    export HAPI_PATIENT_EXCLUDE_SID="$EXCLUDE_SID"
    export HAPI_PATIENT_EXCLUDE_AGENT_SESSION="$EXCLUDE_AGENT"

    if hapi-use-driver; then
        exit 0
    fi

    echo "activation failed; resuming watch" >&2
}

# and in hapi-use-worktree, source lib/patient-drain.sh and use
# patient_drain_count_working_filtered/list_working_filtered instead of the raw jq count.

[github-actions]

[Major] Agent excludes hide every WORKING row with a missing agent id

With an agent exclude set, rows where .agentSessionId is null become $aid == ""; then ($agent | startswith($aid)) is true for every non-empty exclude, so this filter drops those unrelated WORKING sessions. That makes the drain undercount blockers and can activate/restart while a session without agent metadata is still active.

Suggested fix:

| select(
    ($agent | length) == 0
    or (
      (.agentSessionId // "") as $aid
      | ($aid == "")
        or (
          $aid != $agent
          and ($aid | startswith($agent) | not)
          and ($agent | startswith($aid) | not)
        )
    )
  )

Apply the same guard to the duplicate filter in hapi-watch-activate-driver.sh.