feat: add general-purpose lifecycle hooks framework (#1529)

[sergio-sisternes-epam]

feat: add general-purpose lifecycle hooks framework (#1529)

Adds a three-tier lifecycle hooks system that fires shell commands or HTTPS webhooks at pre/post-install/update/uninstall events. Scripts are embedded in apm.yml under a lifecycle: key and gated behind apm lifecycle trust so no script runs without explicit consent.

What this does

• Run validated scripts on install/update/run with zero separate config files -- everything lives in apm.yml.
• Three-tier hierarchy: project (apm.yml), user (~/.apm/apm.yml), admin (/etc/apm/policy.d/*.json).
• Trust gate: apm lifecycle trust records a SHA-256 fingerprint of the canonical lifecycle: subtree. Editing other apm.yml keys (e.g. dependencies:) does not revoke trust.
• Two executor types: command (shell subprocess, synchronous, can delay operation) and http (HTTPS POST, daemon thread, fire-and-forget).
• Credential safety: environment variables with TOKEN/SECRET/PAT/KEY/PASSWORD/CREDENTIAL/AUTHTOKEN suffixes are blocked from HTTP header expansion by default; opt-in via allowedEnvVars. APM's own auth tokens (GITHUB_APM_PAT, GITHUB_TOKEN, GH_TOKEN, ADO_APM_PAT) are never expandable regardless of opt-in.
• cwd containment: relative cwd: entries that escape project root via .. are clamped to the project root.
• Org override: executables.deny_all: true in apm-policy.yml suppresses all lifecycle scripts as a one-directional enterprise ceiling. APM_NO_SCRIPTS=1 skips scripts for a single run.
• apm lifecycle CLI (renamed from apm scripts to avoid collision with apm run):
  • init -- scaffold lifecycle: block in apm.yml
  • validate -- check all discovered scripts for schema errors
  • test [event] [--execute] -- dry-run preview (or live fire) a synthetic event; shows trust status
  • trust / untrust -- manage project lifecycle trust

How to try it

cd my-project
apm lifecycle init            # scaffolds lifecycle: in apm.yml
# edit apm.yml, add your scripts
apm lifecycle validate        # check for schema errors
apm lifecycle test post-install               # dry-run: see what would fire
apm lifecycle test post-install --execute     # actually fire the event
apm lifecycle trust           # trust current lifecycle: subtree
apm install                   # scripts now fire on install

Tests

• tests/unit/core/test_lifecycle_scripts.py -- discovery, filtering, runner
• tests/unit/core/test_script_trust.py -- trust gate, fingerprinting
• tests/unit/core/test_script_executors.py -- command/HTTP executors, cwd containment, env filtering
• tests/unit/commands/test_lifecycle.py -- all 6 CLI subcommands, trust-status display, --execute regression trap
• tests/unit/install/test_lifecycle_trust_gate.py -- integration: untrusted clone does NOT fire scripts, trusted one does

Closes #1529

Co-authored-by: Sergio Sisternes sergio.sisternes@epam.com

---

apm-spec-waiver: install-path lifecycle firing is trust-gated and discovery-bounded; reviewed and folded under this PR with the security-model amendment documented in docs/enterprise/security.md. No OpenAPM-normative contract change beyond that amendment; the install critical-path spec citation is tracked as a follow-up in #1919.

[Copilot]

Pull request overview

Adds a lifecycle hooks framework to APM so installs/updates/uninstalls can emit structured events to user/admin-defined “command” and “http” hooks, plus a new apm hooks CLI group and accompanying enterprise documentation.

Changes:

• Introduces hook discovery + event models + runner (lifecycle_hooks.py) and executors with stdout/stderr logging (hook_executors.py).
• Fires lifecycle events from install/update/uninstall flows and registers the new CLI command group.
• Adds unit tests covering parsing/discovery/execution and documentation for enterprise usage.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 12 comments.

Show a summary per file

File	Description
tests/unit/core/test_lifecycle_hooks.py	New unit tests for hook models, discovery, and runner behavior.
tests/unit/core/test_hook_executors.py	New unit tests for HTTP/command executors, env expansion, cwd, and hooks log output.
tests/unit/commands/test_hooks.py	New unit tests for apm hooks list/init/test/validate commands.
src/apm_cli/install/service.py	Fires pre-install/post-install hooks around the install pipeline and adds helper builders.
src/apm_cli/core/lifecycle_hooks.py	Adds lifecycle event schema, hook entry model, JSON parsing, and discovery across policy/user/project.
src/apm_cli/core/hook_executors.py	Implements command + HTTP hook execution and appends results to hooks.log.
src/apm_cli/commands/update.py	Fires pre-update/post-update hooks around the update pipeline.
src/apm_cli/commands/uninstall/cli.py	Fires pre-uninstall/post-uninstall hooks around uninstall.
src/apm_cli/commands/hooks.py	New apm hooks command group (list/init/test/validate).
src/apm_cli/cli.py	Registers the new hooks command group.
docs/src/content/docs/enterprise/lifecycle-hooks.md	Adds enterprise documentation for hook format, discovery, security, logging, and CLI usage.

[danielmeppiel]

APM Review Panel: ship_with_followups

Lifecycle scripts framework is architecturally sound and security-hardened; five blocking-severity doc/UX gaps need folding before merge.

cc @sergio-sisternes-epam @danielmeppiel -- a fresh advisory pass is ready for your review.

This PR delivers APM's first enterprise-differentiation primitive -- lifecycle scripts with a SHA-256 content-hash trust gate, credential isolation, and org-level deny_all. The security model is complete and the supply-chain-security expert found no exploitable flaws. CI is green across all gates. The architectural decomposition is clean (python-architect confirms good separation), and the performance expert identifies no regressions in the common case.

The five blocking-severity findings cluster into two classes that I weight equally: (A) security-relevant events invisible at default verbosity -- credential variable blocking produces silent empty headers, and untrusted-script skip notices vanish unless --verbose is passed. These are the same design defect: when APM makes a security decision on the user's behalf, that decision MUST surface at default verbosity. This is not cosmetic; it is the difference between "secure by default" and "confusing by default". (B) Documentation drift from the hooks-to-scripts rename -- security.md still says "Hooks exception", commands.md omits trust/untrust, and the CLI reference page pattern (established for 30+ commands) is missing for scripts. These are trivial individually but collectively erode the "one source of truth" promise.

All five are foldable in a single commit without architectural risk. The trust gate filtering test gap (test-coverage-expert) is the most strategically important recommended finding because it guards the supply-chain security promise -- but it is not blocking because the trust gate itself works (passing CI proves the happy path), and the gap is "missing guardrail against future regression" rather than "broken behavior today". The performance reorder (check discover_scripts emptiness before policy fetch) is a three-line change that eliminates a network call in the no-scripts common case -- high value, zero risk, should fold. The daemon thread abandonment is real but bounded in blast radius (post-uninstall only); a 2s join cap is the right fix and can fold or follow up without blocking.

Dissent. cli-logging-expert and devx-ux-expert both flagged skip-notice invisibility as blocking; supply-chain-security-expert did not flag it because the security model itself is sound regardless of UX. I side with cli-logging and devx: a security gate that users cannot observe is an adoption hazard -- the first GitHub issue will be "my scripts don't run and APM says nothing". This is a blocking-tier UX defect even though it is not a security vulnerability. The doc-writer and devx-ux-expert both flagged the missing CLI reference page; python-architect did not mention it. I side with doc-writer/devx: the pattern is load-bearing for discoverability and omitting it for a new top-level command is a doc regression.

Aligned with: secure_by_default (strong -- SHA-256 trust gate, env denylist, credential redaction, APM_NO_SCRIPTS, org deny_all; no exploitable gaps found); governed_by_policy (strong -- org-level deny_all, project-level trust store, per-event control); portability_by_manifest (adequate -- scripts declared in apm.yml, trust store is path-resolved); community_trust (at risk if UX visibility gaps ship -- silent security decisions erode trust faster than missing features).

Growth signal. The oss-growth-hacker correctly identifies this as APM's first enterprise-differentiation feature. The SHA-256 trust gate is not just security -- it is a positioning wedge: no incumbent package manager offers content-hash trust for lifecycle scripts with org-level deny. Lead with this in release notes. The analytics use case (post-install/update telemetry) is the 60-second proof that converts evaluators; ensure post-update is documented before merge so the proof actually works end-to-end.

Panel summary

Persona	B	R	N	Takeaway
Python Architect	0	2	2	Well-structured module decomposition. HTTP daemon threads abandoned in install flows; ScriptEntry lacks post_init validation.
CLI Logging Expert	1	2	2	Output patterns mostly sound. Credential-var blocking silent in non-verbose; trust warning printed after action.
DevX UX Expert	2	0	4	Command surface well-designed. Missing CLI reference page; skip notice invisible at default verbosity.
Supply Chain Security	0	0	2	Sound content-hash trust model; no exploitable flaws. Symlink check and script.env denylist comment as nits.
OSS Growth Hacker	0	4	2	First enterprise-differentiation feature. Lead with outcome; analytics use case needs post-update.
Auth Expert	0	0	1	Denylist correctly covers APM auth vars. script.env bypass needs a comment.
Doc Writer	2	3	3	lifecycle-scripts.md technically accurate. "Hooks exception" label wrong; commands.md omits trust/untrust.
Test Coverage Expert	0	2	1	Trust gate filtering path lacks a test; script_trust.py has no dedicated unit tests.
Performance Expert	0	3	2	Common case cheap. Reorder discover_scripts before policy fetch for no-scripts common case.

B = blocking-severity findings, R = recommended, N = nits.
Counts are signal strength, not gates. The maintainer ships.

Top 5 follow-ups

1. [CLI Logging Expert] (blocking-severity) Surface credential-var blocking and skip notices at default verbosity -- Security decisions invisible to users erode trust and generate support issues. Same class of defect in two places -- fix both with a single INFO-level emit pattern.
2. [Doc Writer] (blocking-severity) Fix security.md "Hooks exception" label and add trust/untrust to commands.md -- Stale naming contradicts the rename already applied. Commands table is the discovery surface for new users; omitting trust/untrust makes the trust model invisible.
3. [DevX UX Expert] (blocking-severity) Add CLI reference page at docs/reference/cli/scripts.md -- Established pattern for all 30+ commands. Missing page breaks docs search and --help-to-web flow.
4. [Test Coverage Expert] Add unit test for trust gate filtering in build_runner_from_context -- Guards the supply-chain security promise against regression. The gate works today (CI green) but has no test that would catch a future refactor breaking it.
5. [Performance Expert] Reorder: check discover_scripts emptiness before policy fetch -- Eliminates a network call in the no-scripts common case (majority of projects today). Three-line change, zero risk.

Recommendation

The architecture, security model, and test suite are solid -- CI green, no exploitable gaps, clean module decomposition. However, the three blocking follow-ups (visibility at default verbosity, doc drift fixes, CLI reference page) are all foldable in a single commit and should land before merge. They are not design questions -- they are mechanical completeness gaps that take 30 minutes total. Fold them, then ship. The two non-blocking follow-ups (trust gate test, perf reorder) can land as immediate post-merge commits or in-PR if convenient.

---

Full per-persona findings

Python Architect

• [recommended] HTTP daemon threads abandoned in install/update/uninstall flows -- runner.fire() return value discarded in integration points; daemon threads may be killed on process exit (especially post-uninstall). scripts_test correctly joins threads but real integration sites don't.
  Suggested: Add a bounded 2s join at post-* event sites.

• [recommended] ScriptEntry lacks post_init validation -- invalid type or missing fields silently no-op at execution rather than failing early with a clear message.

• [nit] build_runner_from_context uses Any for logger type hint instead of CommandLogger | None.

• [nit] _emit_skip_notice uses a fragile getattr chain for logger method dispatch.

CLI Logging Expert

• [blocking] Credential variable blocking invisible in non-verbose mode -- _expand_env_vars blocks credential vars with no user feedback unless --verbose is passed. Empty auth header with no hint to the user.
  Suggested: Emit the blocking warning at INFO-level (via warning method if available) regardless of verbose flag.

• [recommended] Trust warning inverted order -- warning about arbitrary command execution emitted AFTER trust is already recorded.
  Suggested: Move the _rich_warning call before trust_project_scripts().

• [recommended] List command manually embeds STATUS_SYMBOLS in format string; use STATUS_SYMBOLS dict consistently.

• [nit] Hardcoded [!] and [i] prefixes in executor messages instead of STATUS_SYMBOLS.

• [nit] Slow-script warning lacks actionable fix suggestion (e.g. increase timeoutSec or convert to http type).

DevX UX Expert

• [blocking] No CLI reference page at docs/src/content/docs/reference/cli/scripts.md -- every other top-level command has one; missing page breaks docs search and the --help-to-web flow.

• [blocking] Skip notice (untrusted project scripts skipped) invisible in non-verbose mode -- developers cloning a repo and running apm install will see no output explaining why their scripts are not running.

• [nit] commands.md table omits trust and untrust subcommands.

• [nit] apm scripts trust should display what is being trusted before recording.

• [nit] scripts test help text does not mention that post-install is the default event.

• [nit] security.md still uses "Hooks exception" phrasing.

Supply Chain Security

• [nit] Project scripts file not checked for symlink before fingerprinting -- symlink to a trusted file could be swapped. Mitigated by content-hash model, but defense-in-depth would resolve the symlink first.

• [nit] script.env dict bypasses the credential denylist (intentional allowlisted by the user) but the code has no comment clarifying this is a best-effort convenience, not a security boundary.

OSS Growth Hacker

• [recommended] Lead with the outcome in docs, not the mechanism -- open with what enterprises gain (visibility, governance, extensibility) before explaining the JSON schema.

• [recommended] Analytics use case needs post-update event -- the example only shows post-install and post-uninstall; version drift visibility requires post-update.

• [recommended] README deserves a one-liner signaling enterprise extensibility.

• [recommended] Position the SHA-256 trust gate as a growth enabler -- frame it as "runs only what you approve" not as a restriction.

• [nit] Mention the extensibility angle for third-party script libraries.

• [nit] Cross-link from security.md update back to lifecycle-scripts.md.

Auth Expert

• [nit] script.env bypasses the denylist intentionally (the user opted in via allowedEnvVars) but the _build_script_env function lacks a comment clarifying this is best-effort convenience, not a security boundary.

Doc Writer

• [blocking] security.md uses "Hooks exception" label -- contradicts the hooks-to-scripts rename already applied at commit 008b7ab. Two occurrences need updating to "Scripts exception".

• [blocking] commands.md omits trust and untrust subcommands from the lifecycle scripts table.

• [recommended] Trust store path not documented in lifecycle-scripts.md -- users who want to audit or reset trust have no path reference.
  Suggested: Add one sentence: trust records live at ~/.apm/scripts-trust.json.

• [recommended] Analytics use case omits post-update event but the surrounding prose promises version drift visibility -- add a post-update entry to the analytics example.

• [recommended] PR body still uses old "hooks" naming throughout.

• [nit] Double backticks in heading code spans (e.g. apm scripts) -- single backtick is the Markdown convention.

• [nit] Cross-links use absolute paths (pre-existing pattern deviation).

• [nit] CHANGELOG notation "pre/post-install/update/uninstall" is ambiguous.

Test Coverage Expert

• [recommended] Trust gate filtering (untrusted project scripts skipped) has no test in build_runner_from_context.
  Evidence (missing, unit tier): tests/unit/core/test_lifecycle_scripts.py -- no test verifies that project scripts are filtered when is_project_scripts_trusted returns False.

• [recommended] script_trust.py has no dedicated unit test file for edge cases (fingerprint mismatch, unreadable store, concurrent writes).
  Evidence (missing, unit tier): tests/unit/core/test_script_trust.py -- file does not exist.

• [nit] No integration-tier test for install lifecycle scripts firing end-to-end.

Performance Expert

• [recommended] discover_policy_with_chain may issue network RPCs on cold cache inside the install hot path -- called unconditionally before discover_scripts.
  Suggested: Call discover_scripts first; if empty, return early before the policy fetch.

• [recommended] No cap on number of command scripts per event -- unbounded serial accumulation on high-script-count policy files.

• [recommended] Reorder: check discover_scripts result emptiness before expensive policy fetch.

• [nit] HTTP daemon threads have no pool cap -- many concurrent HTTP scripts could exhaust file descriptors.

• [nit] 5s slow-script warning threshold could be user-configurable.

_{This panel is advisory. It does not block merge. Re-apply the
panel-review label after addressing feedback to re-run.}

[danielmeppiel]

Shepherd-driver: fold changes applied — CI green, ready for maintainer review

All blocking panel items have been folded into commit 473cc12.

Folded (commit 473cc12)

Area	Change
Docs	`security.md`: renamed "Hooks exception" -> "Scripts exception" (doc drift from 008b7ab rename)
Docs	`commands.md`: added `trust` and `untrust` subcommand rows to lifecycle scripts table
Docs	Created `docs/reference/cli/scripts.md` — CLI reference page (every other top-level command has one)
Docs	`lifecycle-scripts.md`: trust store path, post-update analytics example, heading backtick fix
Security visibility	`script_executors.py`: credential-variable blocking warning now emits at default verbosity (not just --verbose)
UX visibility	`lifecycle_scripts.py`: skip-notice now emits at `_logger.warning` level (was `debug`; invisible by default)
UX ordering	`scripts.py`: trust warning rendered BEFORE `trust_project_scripts()` call so user sees it before action
Performance	`lifecycle_scripts.py`: `discover_scripts()` runs before policy fetch; no-scripts fast-path avoids network call
Tests	`test_lifecycle_scripts.py`: added 3 trust-gate tests (untrusted/trusted project, user bypass)
Tests	`test_script_trust.py` (new): 15 unit tests covering fingerprint, roundtrip, mismatch, malformed store
Comment	`script_executors.py`: clarifying comment that `script.env` bypass of denylist is best-effort convenience

Deferred (scope boundary — do not implement)

Item	Boundary
README one-liner	Repo doc rule 2: requires maintainer approval before README changes
ScriptEntry `post_init` validation	Design change; tracked in #1919
HTTP thread pool cap	Cross-cutting optimization across unrelated modules; future PR
Per-event script count cap	New safety feature beyond issue #1529 scope; future PR
Full install->scripts integration test	Future PR; out of current test suite scope

CI status (commit 473cc12)

All 15 checks SUCCESS: Lint, Build & Test Shard 1+2 (Linux), Coverage Combine, PR Binary Smoke, APM Self-Check, CodeQL (python + actions), Analyze (python + actions), Spec conformance gate, NOTICE Drift Check, gate, build, license/cla.

The PR is ready for maintainer approval and merge.

[danielmeppiel]

[*] shepherd-driver: apm-review-panel pass 1 (iteration 1)

Headline: Lifecycle scripts framework is architecturally sound; merge after fixing stale CHANGELOG path, ungating timeout warning, and updating PR body.

Arbitration: The panel converged on a well-designed 3-tier execution governance model with no security findings against the PR's actual changes. Supply-chain, auth-expert, cli-logging-expert, and devx-ux-expert were invalidated for referencing pre-existing code outside the PR diff. The two blocking findings (CHANGELOG naming a non-existent .apm/scripts.json, PR body still using 'hooks' terminology) were documentation accuracy errors, each fixed in commit 2e931ca. The performance-expert's timeout-warning finding was the most user-facing code issue: a 30-second silent stall at normal verbosity, resolved in the same commit.

Panel recommendation: ship_with_followups (folding all in-scope items now)

Folded in commit 2e931ca:

• [+] CHANGELOG.md: corrected project script file reference to apm-scripts.yml at repo root (doc-writer/oss-growth-hacker, blocking)
• [+] script_executors.py: ungated TimeoutExpired warning from verbose-only to always-emit (performance-expert)
• [+] script_executors.py: moved inline import time to module top (python-architect nit)
• [+] lifecycle-scripts.md: documented credential denylist and allowedEnvVars opt-in (doc-writer)
• [+] tests: added 2 Windows platform branch tests for effective_command() (test-coverage-expert)
• [+] PR body: rewrote with correct 'scripts' terminology and current file layout

Deferred to #1919 (out-of-scope per stated boundary):

• e2e/integration-with-fixtures test for install pipeline
• Per-event aggregate timeout cap
• TOCTOU file lock in trust store
• lifecycle_scripts.py module split

Principle alignment:

• secure-by-default: ALIGNED (deny-wins ladder, SHA-256 trust gate, credential denylist)
• governed-by-policy: ALIGNED (3-tier precedence with executables.deny_all ceiling)
• devx: PARTIAL-RESOLVED (timeout warning now fires without --verbose; quickstart noted but deferred)
• portability-by-manifest: ALIGNED (apm-scripts.yml committed to repo root)

CI: re-running on new head sha 2e931ca.

[danielmeppiel]

PR #1798 - Lifecycle Scripts Framework: Standalone Engineering Report

A cross-cutting review-panel report (python-architect, devx-ux-expert,
supply-chain-security-expert, cli-logging-expert), synthesized. Grounded
in the PR head at 16a0a3183. ASCII-only.

---

0. Executive Summary

PR #1798 (closes #1529) adds an event-triggered lifecycle scripts
framework to APM: a project / user / admin can register command or
http actions that fire on package-manager events (post-install,
pre-uninstall, ...). It is the third leg of an intentionally separated
noun taxonomy:

Concept	Manifest key	Command	Status
Agent hooks (harness wiring)	.apm/hooks/	(primitive)	pre-existing
On-demand tasks / inference	scripts:	apm run <name>	reserved
Event-triggered, trust-gated	lifecycle:	apm lifecycle	THIS PR

Grounded footprint (120 files, ~11,693 insertions):

Area	Files	Lines	Notes
src/ feature+wiring	41	+4407 / -198	6 core modules + install wiring
tests/red_team/	54	+4350	curated regression suite (279 tests); now runs in CI
tests/unit+integ	19	+2440	the CI-collected suite
docs/	4	+482	enterprise + reference + skill

Verdict (consolidated): SHIP. The feature is architecturally clean,
the trust model is correct, and the security floor (trust gate, SSRF
guard, bounded YAML loader, subprocess containment) is load-bearing and
genuinely safe. The 32-round hardening campaign was net positive but
ran ~3x longer than it should have before the maintainer's scope
correction removed an out-of-scope third-party-secret scanner. The
former review-experience debt (a 253-file diff with a 188-file
CI-unrun test corpus) has been paid down in this PR: the per-round
sweep dumps (~134 files / ~20.8k lines) were deleted and the curated
behavior-organized regression suite (49 test files / 279 tests) is now
wired into the CI shard run. No residual safety defect.

---

1. Architecture

1.1 Module map

graph TD
    subgraph CLI
        A["commands/lifecycle.py<br/>apm lifecycle list/init/validate/test/trust/untrust"]
    end
    subgraph "Discovery and Parse"
        B["core/lifecycle_scripts.py<br/>discover_scripts: project/user/admin tiers"]
        C["utils/yaml_io.py<br/>_BoundedSafeLoader: merge/alias/byte budgets"]
    end
    subgraph Trust
        D["core/script_trust.py<br/>content-hash fingerprint of lifecycle subtree"]
    end
    subgraph Execute
        E["core/script_executors.py<br/>command + http executors, redaction, containment"]
    end
    subgraph InstallWiring
        F["install/service.py<br/>build_runner_from_context, fires on event"]
    end

    A --> B
    B --> C
    B --> D
    F --> B
    F --> D
    D -->|trusted?| E
    B --> E
    E --> C
    E -->|audit| G[("~/.apm/logs/scripts.log<br/>0600, rotated, locked")]
    D --> H[("~/.apm/scripts-trust.json<br/>0600, flock, atomic")]

Loading

1.2 Execution flow: apm install on a freshly-cloned project

sequenceDiagram
    participant U as User
    participant I as install/service.py
    participant DISC as lifecycle_scripts.discover
    participant Y as yaml_io (bounded loader)
    participant T as script_trust
    participant X as script_executors
    participant L as scripts.log

    U->>I: apm install (untrusted clone)
    I->>DISC: discover_scripts(event=post-install)
    DISC->>Y: load_yaml(apm.yml)
    Y-->>DISC: lifecycle subtree, or YAMLError fails closed
    DISC->>T: is_fingerprint_trusted(parsed subtree)
    Note over T: SHA-256 of canonical lifecycle subtree<br/>vs scripts-trust.json
    alt not trusted (default for new clone)
        T-->>I: False
        I-->>U: Skipped N untrusted lifecycle scripts
    else trusted (user ran apm lifecycle trust earlier)
        T-->>X: fire
        X->>X: strip credential-NAME env vars, build child env
        X->>X: start_new_session, bounded capture, SSRF-guard http
        X->>L: append redacted audit entry
        X-->>U: result (slow-script warning over 5s)
    end

Loading

1.3 Design decisions worth noting (python-architect)

• Embed, not a sidecar file. Lifecycle actions live under a
  top-level lifecycle: key in the project's existing apm.yml
  (user tier: ~/.apm/apm.yml; admin tier: /etc/apm/policy.d/*.json).
  This was a unanimous package-manager DevUX panel decision (cargo
  [package.metadata] / Maven phases precedent) and makes the trust
  hash-domain equal to the auto-exec domain by construction.
• One bounded loader, mechanical rollout. A single
  _BoundedSafeLoader in utils/yaml_io.py replaced ~30 raw
  yaml.safe_load sites across the codebase via an import swap. This
  is the campaign's biggest architectural dividend (Section 3).
• Honest assessment: the diff was originally hard to review (a
  253-file PR, red_team 77% of insertions). Trimmed in this PR to 120
  files by deleting the per-round sweep dumps; the feature itself is a
  clean 6-module slice. Recommendation for future work: clearer
  commit-level separation (feature vs hardening sweep vs test corpus).

---

2. Developer Experience (devx-ux-expert)

2.1 Command surface

apm lifecycle with subcommands:

Subcommand	Behavior
list (bare default)	show discovered lifecycle actions across tiers
init	scaffold a lifecycle: block into apm.yml
validate	structural + URL validation, no execution
test	dry-run by default; --execute actually fires
trust / untrust	grant/revoke content-hash trust for this project

Note: the on-demand verb is reserved as apm run <name>; lifecycle
management deliberately uses a different verb (apm lifecycle),
mirroring pnpm approve-builds / bun pm trust. There is no
apm run collision.

2.2 Trust ergonomics

• Model = direnv / VS Code Workspace Trust: the consuming repo
  re-asserts intent per edit of the lifecycle: subtree.
• Fail-closed and visible: an untrusted project prints
  [!] Skipped ... (never silent).
• Escape hatches: APM_NO_SCRIPTS, apm lifecycle untrust, and the
  org-policy deny_all ceiling.

2.3 Honest UX verdict

The trust gate is unambiguously the right call -- it closes the
project-tier auto-exec gap npm never solved (pnpm/bun added it later),
and APM's content-hash granularity is finer than a per-package allow.
Friction items (all minor, deferred to #1919): first-run skip on
your own project, PR-driven re-trust churn, no interactive y/N prompt,
no apm install --trust one-shot, and the test verb is slightly
overloaded (dry-run vs --execute).

---

3. Security (supply-chain-security-expert)

3.1 Threat model (the risks this feature introduces)

• RCE at install -- apm install on an untrusted clone could
  auto-run the project's own lifecycle scripts.
• SSRF / exfiltration via http events to internal/metadata hosts,
  including DNS-rebinding.
• Parser DoS -- sub-KB YAML merge/alias bombs, reachable
  pre-trust (the manifest is parsed before the gate fires).
• Credential leakage of APM's own tokens via log or $VAR header
  expansion.
• Proxy re-routing via attacker-injected HTTP(S)_PROXY.

3.2 Defense-in-depth (all grounded in code)

Layer	Mechanism
Trust gate (script_trust.py)	SHA-256 of canonical lifecycle: subtree, keyed by resolved abs path; fail-closed None on any error; pre-canonicalization structural guard (cycle detection + node 100k / depth 64 / byte 1MB budgets); 0600 + atomic write + flock; deny_all org ceiling; TOCTOU closure (fingerprint the exact parsed content executed)
SSRF guard (script_executors.py)	blocks RFC1918 / loopback / link-local / RFC6598 CGNAT / IPv6 site-local / IPv4-mapped; metadata hostnames; integer+hex IP literal decoding; DNS-pinned connect (same resolution that passed the guard is the one connected); all-addresses-checked; corporate HTTPS_PROXY preserved while attacker proxy-env cannot redirect the pinned path
Bounded YAML loader (yaml_io.py)	merge-entry budget (100k), flatten-depth (200), byte-aware alias-expansion-weight guard (5M) memoized pre-construction; ValueError/RecursionError normalized to yaml.YAMLError; rolled out to ~30 sites; dump_yaml serializes-then-opens (no zero-truncation)
Subprocess containment	start_new_session + killpg whole-tree reap (works even on a zombie leader); bounded per-stream capture (1MB cap -> SIGKILL); NaN/inf timeout rejection; drain-grace that preserves a correctly-detached daemon (npm/yarn parity)
NAME-based credentials	denylist regex (TOKEN/SECRET/PAT/KEY/PASSWORD/...); curated blob names; _NEVER_EXPAND set (GITHUB_APM_PAT, GITHUB_TOKEN, GH_TOKEN, ADO_APM_PAT) blocked from $VAR header expansion even if allow-listed; _build_script_env strips by default; value-redaction of APM-managed names in the log

3.3 The shared-responsibility boundary (the scope correction)

• STRIPPED (round 32): a 9-function, ~240-line shape-based
  scanner that recognized third-party secrets by VALUE shape
  (JWT eyJ..., AWS AKIA..., SendGrid, Vault hvs., Slack, GitLab,
  Stripe, Shopify, PEM, connection-string passwords, SAS, webhooks).
• Why the maintainer was right: APM owns its own credential
  surface by NAME (it knows GITHUB_APM_PAT is a secret). It has no
  contract with AWS/Stripe/Slack and recognizing their shapes is an
  unbounded arms race that belongs in a dedicated secret scanner
  (gitleaks/trufflehog) the script author opts into. npm/pip/cargo do
  not scan lifecycle output for third-party keys either.

---

4. Logging / Audit (cli-logging-expert)

• ~/.apm/logs/scripts.log -- dir 0700, file 0600; 5 MiB rotation
  to .1; non-blocking flock with double-checked re-stat (no
  lost-update clobber).
• Records per dispatch: UTC timestamp, event name, executor type,
  effective target, status, exit code, plus truncated+redacted
  stdout/stderr. This is the forensic tuple for "what did that
  package's post-install do?"
• Log-injection hardening: full str.splitlines() boundary-set
  neutralization (CR/LF/VT/FF/FS/GS/RS/NEL/LS/PS) so a script cannot
  forge a column-0 status=ok record; = escaping in the target
  field so no forged key=value; per-field 4096-char truncation;
  self-healing open path against planted symlink / FIFO / directory /
  0666 nodes (unlink + O_EXCL recreate; at worst one racing write is
  dropped, never a permanent audit blackout).
• Redaction = NAME-based only post-correction: mask the VALUES of
  denylisted-NAME env vars + strip userinfo from the APM-constructed
  http event URL. No phantom "we detect all secrets" promise.
• CodeQL fix (py/clear-text-logging-sensitive-data at
  script_trust.py): the fingerprint-failure debug message was made
  fully static (no path/exception interpolation). Correct
  false-positive suppression, not a behavior change.
• Residual UX gaps (deferred): no apm lifecycle log viewer; no
  install-time [i] N scripts ran summary; single-generation rotation;
  no --log-format=jsonl for SIEM.

---

5. Honest Assessment of the 32-Round Campaign

5.1 What was genuinely won (load-bearing)

• Bounded YAML loader across ~30 sites. Before this PR, every
  yaml.safe_load of untrusted content (marketplace responses,
  registry configs, lockfiles, policy files, installed-package
  frontmatter) was vulnerable to a sub-KB merge/alias bomb in an
  uncatchable O(2^N) GIL-holding loop. This is a codebase-wide
  security improvement, not lifecycle-specific.
• SSRF guard with DNS-pinned connect -- closes the rebinding TOCTOU
  most ad-hoc guards miss; required for the http event type to be
  safe at all.
• Trust gate + structural fingerprint guard -- the critical defense
  that makes the whole feature opt-in for untrusted clones.
• Process-group containment + bounded capture -- prevents the
  command executor from being a process-bomb / OOM vector.
• NAME-based credential stripping + _NEVER_EXPAND -- protects the
  one credential surface APM actually owns.

5.2 What the campaign over-spent

• ~25 of 32 rounds were spent growing/refining the shape-based
  scanner (the "env domain"). Each round added a provider shape, each
  shape "broke" the next round's adversarial test, and the whole
  scaffold was removed in one scope correction. That effort is
  discarded.
• The tests/red_team/ corpus was 188 files / +25,148 lines and NOT
  run by CI -- a merge blocker. Resolved in this PR: the per-round
  sweep dumps (*_sweep/, ~134 files / ~20.8k lines of overlapping
  test_roundNN_* accretion, plus 3 files asserting the stripped
  scanner) were deleted, and the curated behavior-organized suite
  (49 test files / 279 tests, one concern per file: trust TOCTOU /
  kill-switch / canonicalization, SSRF IP-encodings, parser bombs,
  credential-NAME gaps, install containment) was wired into the CI
  shard run (pytest ... tests/red_team, ~6s). The corpus now reads
  54 files / +4,350 lines and every line of it executes on every PR.
• script_executors.py (1844 lines) remains large; the
  credential-NAME regex is comprehensive to the point of fragility
  (rotation/encoding/descriptive-suffix combinators). A simpler
  denylist + exact-name set would be easier to audit.

5.3 Net verdict

Net positive. The campaign produced real, load-bearing security
infrastructure (trust gate, SSRF guard, bounded loader, containment)
and a codebase-wide loader hardening dividend. Its methodology was
sound -- each round surfaced genuine bypass vectors in the kept
layers. But its scope drifted into "build a secrets scanner" for
too long; a tighter initial threat-model would have reached the same
shipped state in roughly a third of the rounds. The maintainer's
correction was timely and restored the right boundary: APM owns its
own credential names; the script author owns their third-party
secrets.

The feature is safe to ship. The former review-experience cost (a
253-file diff carrying a 188-file CI-unrun test corpus) has been paid
down in this PR -- sweeps deleted, curated suite wired into CI -- so
the remaining diff is 120 files and every test runs. Not a merge
blocker.

---

6. CI / Merge State (head 95f8c11)

• All required checks green (Lint, both Build & Test shards, Analyze x2,
  CodeQL, Spec-conformance gate, Coverage Combine, gate); 0 open
  CodeQL alerts. The curated tests/red_team suite (279 tests) is now
  part of the sharded shard run, so it is a required check at PR time.
• mergeable: MERGEABLE, mergeStateStatus: BLOCKED -- the only
  remaining gate is the protected-branch human approval. This
  autopilot does NOT auto-merge.
• Authorship preserved: every commit carries both
  Sergio Sisternes <sergio.sisternes@epam.com> and the Copilot
  co-author trailer.
• Deferred design items tracked in PR #1798 lifecycle "hooks" collides with the agent-hooks primitive -- rename to "scripts" + integrate governance #1919 (notify/run executor split,
  module split, HTTP thread cap, interactive trust prompt, log viewer).
  The red_team CI-wiring item is now done in this PR.