Add ai-investigate shark-cli command for AI-driven leak investigation

[pyricau]

Summary

• Adds a new ai-investigate command to shark-cli designed to be driven by an AI agent exploring Android heap dumps
• Introduces LeakInvestigationSession to split the expensive BFS path-finding (runs once) from the cheap inspection+bisecting step (re-runs on each status override)
• Exposes an interactive keyword DSL with 15 commands: trace, node N, fields, instances, string, referrers, mark-leaking, mark-not-leaking, mark-unknown, select-group, select-trace, summary, help, exit
• Output is always JSON — designed exclusively for agent consumption, not human use
• Full investigation instructions are printed at session startup (agents read stdout, not --help)

Key design

Split pipeline: BFS path-finding runs exactly once per session via RealLeakTracerFactory.findLeaksWithCachedPaths(). Re-inspection calls reinspectPath() which skips BFS entirely and only re-runs the cheap ObjectInspector + bisecting stages. This makes override round-trips instantaneous.

Override precedence: Status overrides are injected as an ObjectInspector appended last in the inspector list. It clears the opposing reason set before adding its own reason, so overrides always win over standard inspectors (e.g. AndroidObjectInspectors) without any special-casing.

WIN detection: leakFound: true in the JSON when no UNKNOWN nodes remain. culpritReferenceIndex points to the bad reference — the crossing from the last NOT_LEAKING node to the first LEAKING node.

Agent workflow (printed at startup):

1. Run trace — scan nodes[] for "leakingStatus": "UNKNOWN"
2. Bisect the UNKNOWN window — pick the midpoint node
3. Read class source (local repo or cs.android.com) + run fields N for runtime evidence
4. Mark the node (mark-leaking / mark-not-leaking) with a concrete reason citing field values
5. Repeat until leakFound: true

JSON schema (trace commands)

{
  "group": 0,
  "traceInstance": 0,
  "overrides": 2,
  "suspectWindowStart": 3,
  "leakFound": false,
  "culpritReferenceIndex": -1,
  "nodes": [
    {
      "index": 0,
      "objectId": 12345,
      "className": "com.example.MyActivity",
      "leakingStatus": "NOT_LEAKING",
      "leakingStatusReason": "Activity#mDestroyed is false",
      "isSuspect": false
    }
  ]
}

Test plan

• ./gradlew :shark:shark:compileKotlin :shark:shark-cli:compileKotlin passes
• ./gradlew :shark:shark:test --tests shark.LeakInvestigationSessionTest — 11 tests pass
• Detekt: 0 code smells
• Manual smoke test with a real .hprof file
• Override round-trip: mark-not-leaking 0 "test" → verify trace updates; mark-unknown 0 → verify revert
• Verify leakFound flips to true and culpritReferenceIndex is set after all UNKNOWNs are resolved

🤖 Generated with Claude Code

[tcmulcahy]

Some important feedback inline, but it's all optional, so I'm approving.

[tcmulcahy]

I like this design, but I think the name ai-investigate is misleading, even if it is how this tool is likely to be used. I'd suggest shark-daemon start --hprof <file> and shark-daemon stop --shortcode ...

[tcmulcahy]

Do you really need POSIX compat? Ancient bash (like the version that ships with Mac) supports arrays, so you can write much simpler code:

new_args=()
for arg in "$@"; do
  [[ $arg == --no-help ]] || new_args+=("$arg")
done
set -- "${new_args[@]}"

[tcmulcahy]

Note that the daemon will still be tied to the session - if you close the window within which you ran this, the daemon will die too. You can fix this with nohup if desired.

[tcmulcahy]

I don't see any code to capture the pid of the daemon - how to shut it down after?

[tcmulcahy]

This approach has some drawbacks. The main one is that if more than one client attempts to connect to the same daemon, things will be totally broken in a way that's really hard to debug. Also, FIFOs are just annoying (e.g. you have to be careful to avoid deadlocking)

For this reason, I think a Unix Domain Socket approach would be better. This allows traditional networking patterns, but without the security implications of an actual udp/tcp server.