[BUG] audit --ci walks the whole target root (session transcripts under ~/.claude, ~/.codex): minutes of CPU and false content-integrity findings

[lkshrk]

Describe the bug

apm audit --ci walks the entire root of every dedicated target (.claude/, .codex/, .cursor/, ...) for the hidden-Unicode signal of content-integrity. At user scope those roots are not deploy trees: ~/.claude/ holds projects/**/*.jsonl session transcripts and history.jsonl, ~/.codex/ holds session logs. APM never deploys anything there, yet the audit regex-scans every byte of it on every run.

Two consequences on a normal developer machine (783 MB under ~/.claude, 4.9 GB under ~/.codex):

1. Time. The audit takes ~2m30s of CPU (sre_search over TextIOWrapper.read, sampled). Anything that runs apm audit --ci with a bounded deadline times out.
2. False positives. content-integrity failed with 22 "critical" findings, all in .claude/history.jsonl and .claude/projects/**/*.jsonl. None of those files is deployed, none is in the lockfile, and apm audit --strip is not a sane remedy for a session transcript. --ci exits non-zero for content the audit cannot own.

Cause: _scan_deployed_trees (src/apm_cli/security/file_scanner.py) derives its walk roots from install_governance(), which by design returns the whole root for dedicated targets ("Dedicated target roots govern their full subtree") and only partitions the shared .agents/ root by primitive subdirectory. That is the right scope for ownership tests, but SecurityGate.scan_files then os.walks the whole root with no pruning, no size cap, and no extension filter. Introduced by #2381 (fix for #2379), which widened the scan from deployed_files to the governed tree so that unrecorded deployed files are covered. The widening is correct; the boundary it picked is one level too coarse.

Still present on main (4aaa73cd): file_scanner.py and _check_content_integrity are unchanged since #2381; gate.py only gained __pycache__ exclusions. No open issue or PR covers this.

To Reproduce

1. Have a global APM workspace (~/.apm/apm.yml + lockfile) with the claude target and a few skills installed.
2. Use Claude Code or Codex for a while so ~/.claude/projects/ and ~/.codex/ hold transcripts (or seed them: mkdir -p ~/.claude/projects/x && head -c 500M /dev/urandom | base64 > ~/.claude/projects/x/s.jsonl).
3. cd ~/.apm && time apm audit --ci --format json

Observed: minutes of wall time; content-integrity reports findings under .claude/projects/... and .claude/history.jsonl.

Expected behavior

The hidden-Unicode walk covers each target's primitive deploy directories and generated files (.claude/skills/, .claude/agents/, .claude/commands/, .claude/hooks/, .claude/rules/, .codex/hooks.json, .agents/skills/, ...), exactly the way .agents/ is already partitioned. That keeps the #2379 guarantee (an unrecorded file under a deploy directory is still scanned) while leaving session data alone. Lockfile-claimed paths outside those directories (for example .claude/settings.json) stay covered by the lockfile-scoped scan, which is unioned with the tree walk today.

With that change on the same machine: 5s CPU, content-integrity passes, drift results identical.

Environment

• OS: macOS 26 (Darwin 25.6.0), arm64
• Python Version: 3.12
• APM Version: 0.29.0 (656f3d6), also verified against main 4aaa73cd

Logs

$ cd ~/.apm && time apm audit --ci --format json
...
138.26s user 6.41s system 92% cpu 2:37.16 total

$ ps -o etime,%cpu,command -p <pid>
01:52  98.8  .../apm audit --ci --format json

# sampled: sre_search <- _io_TextIOWrapper_read, no open FDs besides transcripts

Before/after on the same workspace, apm audit --ci --format json:

	wall	CPU	content-integrity
main	2m37s	138s	22 findings, all .claude/projects/**/*.jsonl + .claude/history.jsonl
bounded walk	25s (5s idle machine)	5s	0 findings

Additional context

I have the fix ready (small: a bounded= keyword on install_governance() that applies the existing .agents/ partitioning to every root, used only by _scan_deployed_trees; ownership/prune callers unchanged; tests + docs). Will open the PR against this issue. Happy to adjust the boundary if maintainers prefer a different one (for example an explicit skip list per target instead of primitive partitioning).

[github-actions]

Triage recommendation

accept

Recommendation only, not scope approval. A responsible human maintainer
must approve the scope and review contact before implementation. Labels,
automated advice, and silence are not approval or a release commitment.

Proposed classification

type/bug, area/cli, area/audit-policy

Proposed scope brief

• Scope: apm audit --ci should scope its filesystem walk to the actual
  project/target directory (and its declared dependencies), not the whole
  target root, so it does not descend into unrelated user directories like
  ~/.claude or ~/.codex and produce slow runs and false-positive
  findings from content outside the project.
• Done when: apm audit --ci run against a project directory only
  scans files within that project's scope (plus explicitly resolved
  dependency content); a regression test confirms audit does not walk into
  sibling home-directory tool configs; scan time is no longer proportional
  to unrelated directory size.
• Exclusions: Intentional --file/explicit-path scanning behavior,
  which should remain user-directed and out of this fix's scope.
• Review needs: A maintainer to confirm the correct scoping boundary
  (project root vs. explicit manifest-declared paths) and review the
  existing open PR fix(audit): bound the deploy-tree hidden-Unicode walk to primitive directories #2962 against that boundary.

Suggested next action

Note that PR #2962 is already open addressing this; a maintainer should
review that PR's scoping approach directly rather than treating this as a
fresh, unclaimed issue -- confirm the PR's boundary matches the intended
scope before merge.

Suggested issue comment

Thanks for the clear repro -- an audit that walks the entire target root
instead of the project scope is a legitimate correctness bug, especially
since it produces false positives from unrelated tool configs and slows
CI down.

We see PR #2962 already proposes a fix for this. A maintainer will review
that PR's scoping approach and confirm it matches the intended audit
boundary before merge. This note is automated triage advice, not an
acceptance of the specific PR's approach -- the maintainer's review of
#2962 is the operative next step here.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

Directly affects the "built-in protection is automatic, zero-config"
promise for apm audit/CI gating: false positives and slow scans from
scope creep undermine trust in CI results (an unexpected failure with no
clear "what failed, why" story, since the flagged file isn't even part of
the project). Clear, reproducible capability gap. Contributor association
is CONTRIBUTOR, so an already-invested community member surfaced this
with actionable detail.

Supply Chain Security Expert -- Risk-Surface Reviewer

This is directly in the audit/policy enforcement surface
(enterprise/security.md, policy-reference.md). Over-broad scanning is
a correctness bug, not by itself a vulnerability, but false positives from
scanning unrelated user directories could train users to ignore or
suppress audit findings ("alert fatigue"), which IS a security-relevant
downstream risk. The scoping fix should be reviewed to ensure it doesn't
under-scope and miss legitimately in-scope dependency content while
excluding home-directory noise -- flagging this balance for whoever
reviews PR #2962.

OSS Growth Hacker -- Contributor-Tone Reviewer

Not activated -- author is an existing CONTRIBUTOR who already opened a
fix PR; standard collaborative tone in the suggested reply is sufficient,
no special first-time-contributor tone calibration needed.

Python Architect -- Architecture Reviewer

Worth a light touch here: audit's walk-scope decision should have one
canonical definition of "in scope" (project root + resolved deps) reused
by both apm audit standalone and apm audit --ci, rather than the CI
path drifting from the standalone path's boundary. Recommend whoever
reviews #2962 confirm the fix centralizes this scope decision rather than
patching only the --ci code path.

Doc Writer -- Documentation Reviewer

Not activated -- no evidence yet that enterprise/security.md or
policy-reference.md documents the intended scan boundary explicitly; if
the fix changes documented scanning behavior, the PR review should confirm
whether a doc update is needed at that time.

APM CEO -- Triage Arbiter

Clear, evidenced bug from an existing contributor, with a fix already
proposed in PR #2962. Recommend accept for scope confirmation, with the
explicit note that the maintainer's actual next step is reviewing #2962
rather than commissioning fresh work -- avoids duplicate effort.

{
  "schema_version": 2,
  "advisory_only": true,
  "recommendation": "accept",
  "recommendation_detail": "Clear audit-scope bug with an existing open PR (#2962) proposing a fix; maintainer should review that PR directly.",
  "classification": {
    "theme": null,
    "areas": ["area/cli", "area/audit-policy"],
    "type": "type/bug"
  },
  "proposed_brief": {
    "scope": "Scope apm audit --ci to the project/target directory and its resolved dependencies, not the entire target root.",
    "done_when": "apm audit --ci does not walk into unrelated home-directory tool configs; regression test confirms scoping; PR #2962 reviewed against this boundary.",
    "exclusions": "Explicit --file/path-directed scanning, which stays user-directed.",
    "review_needs": "Maintainer review of PR #2962's scoping approach against the intended audit boundary."
  },
  "next_action": "Maintainer reviews open PR #2962 directly rather than treating this as unclaimed work.",
  "comment_markdown": "Thanks for the clear repro -- an audit that walks the entire target root instead of the project scope is a legitimate correctness bug, especially since it produces false positives from unrelated tool configs and slows CI down.\n\nWe see PR #2962 already proposes a fix for this. A maintainer will review that PR's scoping approach and confirm it matches the intended audit boundary before merge. This note is automated triage advice, not an acceptance of the specific PR's approach -- the maintainer's review of #2962 is the operative next step here."
}

Generated by Triage Panel · copilot · auto · 131.4 AIC · ⌖ 15.3 AIC · ⊞ 11.7K · ◷

[lkshrk]

Continuing this in #2962, which I have rewritten to the current PR template. status/accepted is on the issue, but there is no apm-scope:v1 record yet. When a maintainer has capacity, a scope record with a review contact would let the PR proceed under the new rules.

One point needs a maintainer call for the "done when": should the user-owned part of .claude/settings.json stay inside the audit tree walk, or be treated like other user-owned content and left out? The bounded walk in #2962 currently leaves it out (measured in #2962 (comment)). Either answer is a small change on the PR; I will follow the recorded scope.

[danielmeppiel]

Decision: approve
Area: project
Scope: Define and implement an explicit, target-aware boundary for automatic deployed-content auditing, separating discovery of recognized deployed primitives from the checks applicable to their content. Discover known primitive files and hook entries, including untracked entries inside shared native configuration such as .claude/settings.json, without walking entire tool roots or treating every discovered string as prompt text.
Done when: A documented and regression-tested per-target contract specifies the known filenames or patterns, primitive kinds, and applicable structured fields, reusing the existing target and hook registries as the authority; discovery respects project and user target scope and does not depend solely on lockfile membership; recognized instruction, rule, agent, skill, prompt, and context documents receive hidden-Unicode prompt checks on their prompt-bearing content; hook configuration is parsed through its documented containers and only documented prompt-bearing fields receive that check, not command strings, executable scripts, or unrelated settings; discovered untracked hooks remain visible as discovered/untracked without implying unsafe content, APM ownership, or hash verification; existing ownership, hash, and drift checks retain their evidence requirements, while lockfile membership alone does not classify code as prompt text; unrelated transcripts, history, and caches are excluded from automatic primitive discovery; unknown or unreadable recognized formats are reported rather than represented as successfully checked; regression coverage and maintained docs demonstrate these boundaries for tracked and untracked primitives, shared hook configuration, project/user scopes, and exclusion of unrelated data.
Out of scope: Executing hooks or scripts, predicting their runtime output, generic code-vulnerability scanning, recursively following arbitrary command paths or discovering unrelated files, broad schema or ownership redesign, inventing hash baselines for manual content, and new automatic deletion, rewriting, or remediation authority. Existing path-containment and symlink protections must not be weakened.
Review contact: Daniel Meppiel (@danielmeppiel)