PER-10496 feat: emit machine identity for slow-build diagnostics

[Shivanshu-07]

Summary

CLI side of Build-processing diagnostics (slow builds) — PER-10496. Pairs with percy-api https://github.com/percy/percy-api/pull/6715, which validates and consumes everything sent here for per-machine liveness on parallel builds (naming the dead CI machine when one stops sending snapshots).

• env.machine getter (@percy/env): { id, hostname, runUrl } — sanitized-hostname id suffixed with the CI node index where the provider exposes one (CIRCLE_NODE_INDEX, BUILDKITE_PARALLEL_JOB), and the CI run URL for circle/buildkite/github/gitlab. Deliberately excluded from the env getter debug logging (like token) — those debug logs are uploaded with build logs, and hostnames should not ride along.
• Build create (@percy/client): machine-id / machine-hostname / machine-ci-run-url attributes (only when an id exists).
• X-Percy-Machine-Id header on snapshot-create and build-finalize calls, attached per-call via machineHeaders() — never in headers(), so it cannot leak to off-domain requests (validateDomain).

Server-side: percy-api enforces charset/length limits and an https + CI-host allowlist on the URL, and treats all of it as advisory. Old CLI versions degrade gracefully (the feature falls back to non-machine-specific messaging).

Testing

• @percy/env: 5 new specs (sanitized id, node-index suffix + run URL on circle, composed GitHub Actions run URL, null run URL fallback, debug-logging exclusion). Suite green (128/128).
• @percy/client: header specs for snapshot + finalize, machine attributes on build create; existing exact-payload expectations updated. Suite green under node 14 except one pre-existing environmental failure (proxy getProxy should return undefined if no proxy is set) that also fails on a clean checkout on this machine (local proxy present) — unrelated to this change.

Post-Deploy Monitoring & Validation

• What to monitor: percy-api warn logs "machine identity ingest skipped" (should stay ≈0); Redis key growth percy:api:build-machines:* (bounded by active builds, 25h TTL).
• Validation: run a parallel build with this CLI against an org with the slow-build-diagnostics flag ON → build show JSON carries machine facts in diagnosis; kill one shard → machine named in the receiving-state alert.
• Expected healthy behavior: zero change for orgs with the flag off; no additional CLI network calls (attributes/header ride existing requests).
• Failure signal / rollback: any snapshot POST regression correlated with the header → revert this PR; the API ignores absent identity entirely.
• Window & owner: first minor release post-merge, @shivanshusingh.

🤖 Generated with Claude Code

[Shivanshu-07]

CI is green (30/30). For the record on the two reds seen along the way:

• Test @percy/env and Test @percy/client were mine: both packages enforce 100% line and branch coverage via test:coverage (a different command from test, which is what I'd run locally), and the new machine getter left the buildkite/gitlab cases, the hostname-failure path, and the no-machine-identity fallbacks uncovered. Fixed in ee8b24d and 3c6ceff — both packages now report 100/100/100/100.
• Test @percy/core (Windows leg only) failed on should retry by default on the snapshot discovery upto 3 times, which observed 2 retry log lines instead of 3. That is a timing assertion in packages/core; this PR touches only packages/env and packages/client, and the Linux core leg passed on the same commit. Re-ran the job and it passed, so it was flaky rather than related.

[Shivanshu-07]

Summary

CLI side of Build-processing diagnostics (slow builds) — PER-10496. Pairs with percy-api https://github.com/percy/percy-api/pull/6715, which validates and consumes everything sent here for per-machine liveness on parallel builds (naming the dead CI machine when one stops sending snapshots).

• env.machine getter (@percy/env): { id, hostname, runUrl } — sanitized-hostname id suffixed with the CI node index where the provider exposes one (CIRCLE_NODE_INDEX, BUILDKITE_PARALLEL_JOB), and the CI run URL for circle/buildkite/github/gitlab. Deliberately excluded from the env getter debug logging (like token) — those debug logs are uploaded with build logs, and hostnames should not ride along.
• Build create (@percy/client): machine-id / machine-hostname / machine-ci-run-url attributes (only when an id exists).
• X-Percy-Machine-Id header on snapshot-create and build-finalize calls, attached per-call via machineHeaders() — never in headers(), so it cannot leak to off-domain requests (validateDomain).

Server-side: percy-api enforces charset/length limits and an https + CI-host allowlist on the URL, and treats all of it as advisory. Old CLI versions degrade gracefully (the feature falls back to non-machine-specific messaging).

Testing

• @percy/env: 5 new specs (sanitized id, node-index suffix + run URL on circle, composed GitHub Actions run URL, null run URL fallback, debug-logging exclusion). Suite green (128/128).
• @percy/client: header specs for snapshot + finalize, machine attributes on build create; existing exact-payload expectations updated. Suite green under node 14 except one pre-existing environmental failure (proxy getProxy should return undefined if no proxy is set) that also fails on a clean checkout on this machine (local proxy present) — unrelated to this change.

Post-Deploy Monitoring & Validation

• What to monitor: percy-api warn logs "machine identity ingest skipped" (should stay ≈0); Redis key growth percy:api:build-machines:* (bounded by active builds, 25h TTL).
• Validation: run a parallel build with this CLI against an org with the slow-build-diagnostics flag ON → build show JSON carries machine facts in diagnosis; kill one shard → machine named in the receiving-state alert.
• Expected healthy behavior: zero change for orgs with the flag off; no additional CLI network calls (attributes/header ride existing requests).
• Failure signal / rollback: any snapshot POST regression correlated with the header → revert this PR; the API ignores absent identity entirely.
• Window & owner: first minor release post-merge, @shivanshusingh.

🤖 Generated with Claude Code

[Shivanshu-07]

CI is green (30/30). For the record on the two reds seen along the way:

• Test @percy/env and Test @percy/client were mine: both packages enforce 100% line and branch coverage via test:coverage (a different command from test, which is what I'd run locally), and the new machine getter left the buildkite/gitlab cases, the hostname-failure path, and the no-machine-identity fallbacks uncovered. Fixed in ee8b24d and 3c6ceff — both packages now report 100/100/100/100.
• Test @percy/core (Windows leg only) failed on should retry by default on the snapshot discovery upto 3 times, which observed 2 retry log lines instead of 3. That is a timing assertion in packages/core; this PR touches only packages/env and packages/client, and the Linux core leg passed on the same commit. Re-ran the job and it passed, so it was flaky rather than related.

[Shivanshu-07]

Summary

CLI side of Build-processing diagnostics (slow builds) — PER-10496. Pairs with percy-api https://github.com/percy/percy-api/pull/6715, which validates and consumes everything sent here for per-machine liveness on parallel builds (naming the dead CI machine when one stops sending snapshots).

• env.machine getter (@percy/env): { id, hostname, runUrl } — sanitized-hostname id suffixed with the CI node index where the provider exposes one (CIRCLE_NODE_INDEX, BUILDKITE_PARALLEL_JOB), and the CI run URL for circle/buildkite/github/gitlab. Deliberately excluded from the env getter debug logging (like token) — those debug logs are uploaded with build logs, and hostnames should not ride along.
• Build create (@percy/client): machine-id / machine-hostname / machine-ci-run-url attributes (only when an id exists).
• X-Percy-Machine-Id header on snapshot-create and build-finalize calls, attached per-call via machineHeaders() — never in headers(), so it cannot leak to off-domain requests (validateDomain).

Server-side: percy-api enforces charset/length limits and an https + CI-host allowlist on the URL, and treats all of it as advisory. Old CLI versions degrade gracefully (the feature falls back to non-machine-specific messaging).

Testing

• @percy/env: 5 new specs (sanitized id, node-index suffix + run URL on circle, composed GitHub Actions run URL, null run URL fallback, debug-logging exclusion). Suite green (128/128).
• @percy/client: header specs for snapshot + finalize, machine attributes on build create; existing exact-payload expectations updated. Suite green under node 14 except one pre-existing environmental failure (proxy getProxy should return undefined if no proxy is set) that also fails on a clean checkout on this machine (local proxy present) — unrelated to this change.

Post-Deploy Monitoring & Validation

• What to monitor: percy-api warn logs "machine identity ingest skipped" (should stay ≈0); Redis key growth percy:api:build-machines:* (bounded by active builds, 25h TTL).
• Validation: run a parallel build with this CLI against an org with the slow-build-diagnostics flag ON → build show JSON carries machine facts in diagnosis; kill one shard → machine named in the receiving-state alert.
• Expected healthy behavior: zero change for orgs with the flag off; no additional CLI network calls (attributes/header ride existing requests).
• Failure signal / rollback: any snapshot POST regression correlated with the header → revert this PR; the API ignores absent identity entirely.
• Window & owner: first minor release post-merge, @shivanshusingh.

🤖 Generated with Claude Code

[Shivanshu-07]

CI is green (30/30). For the record on the two reds seen along the way:

• Test @percy/env and Test @percy/client were mine: both packages enforce 100% line and branch coverage via test:coverage (a different command from test, which is what I'd run locally), and the new machine getter left the buildkite/gitlab cases, the hostname-failure path, and the no-machine-identity fallbacks uncovered. Fixed in ee8b24d and 3c6ceff — both packages now report 100/100/100/100.
• Test @percy/core (Windows leg only) failed on should retry by default on the snapshot discovery upto 3 times, which observed 2 retry log lines instead of 3. That is a timing assertion in packages/core; this PR touches only packages/env and packages/client, and the Linux core leg passed on the same commit. Re-ran the job and it passed, so it was flaky rather than related.

[Shivanshu-07]

Summary

CLI side of Build-processing diagnostics (slow builds) — PER-10496. Pairs with percy-api https://github.com/percy/percy-api/pull/6715, which validates and consumes everything sent here for per-machine liveness on parallel builds (naming the dead CI machine when one stops sending snapshots).

• env.machine getter (@percy/env): { id, hostname, runUrl } — sanitized-hostname id suffixed with the CI node index where the provider exposes one (CIRCLE_NODE_INDEX, BUILDKITE_PARALLEL_JOB), and the CI run URL for circle/buildkite/github/gitlab. Deliberately excluded from the env getter debug logging (like token) — those debug logs are uploaded with build logs, and hostnames should not ride along.
• Build create (@percy/client): machine-id / machine-hostname / machine-ci-run-url attributes (only when an id exists).
• X-Percy-Machine-Id header on snapshot-create and build-finalize calls, attached per-call via machineHeaders() — never in headers(), so it cannot leak to off-domain requests (validateDomain).

Server-side: percy-api enforces charset/length limits and an https + CI-host allowlist on the URL, and treats all of it as advisory. Old CLI versions degrade gracefully (the feature falls back to non-machine-specific messaging).

Testing

• @percy/env: 5 new specs (sanitized id, node-index suffix + run URL on circle, composed GitHub Actions run URL, null run URL fallback, debug-logging exclusion). Suite green (128/128).
• @percy/client: header specs for snapshot + finalize, machine attributes on build create; existing exact-payload expectations updated. Suite green under node 14 except one pre-existing environmental failure (proxy getProxy should return undefined if no proxy is set) that also fails on a clean checkout on this machine (local proxy present) — unrelated to this change.

Post-Deploy Monitoring & Validation

• What to monitor: percy-api warn logs "machine identity ingest skipped" (should stay ≈0); Redis key growth percy:api:build-machines:* (bounded by active builds, 25h TTL).
• Validation: run a parallel build with this CLI against an org with the slow-build-diagnostics flag ON → build show JSON carries machine facts in diagnosis; kill one shard → machine named in the receiving-state alert.
• Expected healthy behavior: zero change for orgs with the flag off; no additional CLI network calls (attributes/header ride existing requests).
• Failure signal / rollback: any snapshot POST regression correlated with the header → revert this PR; the API ignores absent identity entirely.
• Window & owner: first minor release post-merge, @shivanshusingh.

🤖 Generated with Claude Code

[Shivanshu-07]

CI is green (30/30). For the record on the two reds seen along the way:

• Test @percy/env and Test @percy/client were mine: both packages enforce 100% line and branch coverage via test:coverage (a different command from test, which is what I'd run locally), and the new machine getter left the buildkite/gitlab cases, the hostname-failure path, and the no-machine-identity fallbacks uncovered. Fixed in ee8b24d and 3c6ceff — both packages now report 100/100/100/100.
• Test @percy/core (Windows leg only) failed on should retry by default on the snapshot discovery upto 3 times, which observed 2 retry log lines instead of 3. That is a timing assertion in packages/core; this PR touches only packages/env and packages/client, and the Linux core leg passed on the same commit. Re-ran the job and it passed, so it was flaky rather than related.

[Shivanshu-07]

Summary

CLI side of Build-processing diagnostics (slow builds) — PER-10496. Pairs with percy-api https://github.com/percy/percy-api/pull/6715, which validates and consumes everything sent here for per-machine liveness on parallel builds (naming the dead CI machine when one stops sending snapshots).

• env.machine getter (@percy/env): { id, hostname, runUrl } — sanitized-hostname id suffixed with the CI node index where the provider exposes one (CIRCLE_NODE_INDEX, BUILDKITE_PARALLEL_JOB), and the CI run URL for circle/buildkite/github/gitlab. Deliberately excluded from the env getter debug logging (like token) — those debug logs are uploaded with build logs, and hostnames should not ride along.
• Build create (@percy/client): machine-id / machine-hostname / machine-ci-run-url attributes (only when an id exists).
• X-Percy-Machine-Id header on snapshot-create and build-finalize calls, attached per-call via machineHeaders() — never in headers(), so it cannot leak to off-domain requests (validateDomain).

Server-side: percy-api enforces charset/length limits and an https + CI-host allowlist on the URL, and treats all of it as advisory. Old CLI versions degrade gracefully (the feature falls back to non-machine-specific messaging).

Testing

• @percy/env: 5 new specs (sanitized id, node-index suffix + run URL on circle, composed GitHub Actions run URL, null run URL fallback, debug-logging exclusion). Suite green (128/128).
• @percy/client: header specs for snapshot + finalize, machine attributes on build create; existing exact-payload expectations updated. Suite green under node 14 except one pre-existing environmental failure (proxy getProxy should return undefined if no proxy is set) that also fails on a clean checkout on this machine (local proxy present) — unrelated to this change.

Post-Deploy Monitoring & Validation

• What to monitor: percy-api warn logs "machine identity ingest skipped" (should stay ≈0); Redis key growth percy:api:build-machines:* (bounded by active builds, 25h TTL).
• Validation: run a parallel build with this CLI against an org with the slow-build-diagnostics flag ON → build show JSON carries machine facts in diagnosis; kill one shard → machine named in the receiving-state alert.
• Expected healthy behavior: zero change for orgs with the flag off; no additional CLI network calls (attributes/header ride existing requests).
• Failure signal / rollback: any snapshot POST regression correlated with the header → revert this PR; the API ignores absent identity entirely.
• Window & owner: first minor release post-merge, @shivanshusingh.

🤖 Generated with Claude Code

[Shivanshu-07]

CI is green (30/30). For the record on the two reds seen along the way:

• Test @percy/env and Test @percy/client were mine: both packages enforce 100% line and branch coverage via test:coverage (a different command from test, which is what I'd run locally), and the new machine getter left the buildkite/gitlab cases, the hostname-failure path, and the no-machine-identity fallbacks uncovered. Fixed in ee8b24d and 3c6ceff — both packages now report 100/100/100/100.
• Test @percy/core (Windows leg only) failed on should retry by default on the snapshot discovery upto 3 times, which observed 2 retry log lines instead of 3. That is a timing assertion in packages/core; this PR touches only packages/env and packages/client, and the Linux core leg passed on the same commit. Re-ran the job and it passed, so it was flaky rather than related.

[Shivanshu-07]

Summary

CLI side of Build-processing diagnostics (slow builds) — PER-10496. Pairs with percy-api https://github.com/percy/percy-api/pull/6715, which validates and consumes everything sent here for per-machine liveness on parallel builds (naming the dead CI machine when one stops sending snapshots).

• env.machine getter (@percy/env): { id, hostname, runUrl } — sanitized-hostname id suffixed with the CI node index where the provider exposes one (CIRCLE_NODE_INDEX, BUILDKITE_PARALLEL_JOB), and the CI run URL for circle/buildkite/github/gitlab. Deliberately excluded from the env getter debug logging (like token) — those debug logs are uploaded with build logs, and hostnames should not ride along.
• Build create (@percy/client): machine-id / machine-hostname / machine-ci-run-url attributes (only when an id exists).
• X-Percy-Machine-Id header on snapshot-create and build-finalize calls, attached per-call via machineHeaders() — never in headers(), so it cannot leak to off-domain requests (validateDomain).

Server-side: percy-api enforces charset/length limits and an https + CI-host allowlist on the URL, and treats all of it as advisory. Old CLI versions degrade gracefully (the feature falls back to non-machine-specific messaging).

Testing

• @percy/env: 5 new specs (sanitized id, node-index suffix + run URL on circle, composed GitHub Actions run URL, null run URL fallback, debug-logging exclusion). Suite green (128/128).
• @percy/client: header specs for snapshot + finalize, machine attributes on build create; existing exact-payload expectations updated. Suite green under node 14 except one pre-existing environmental failure (proxy getProxy should return undefined if no proxy is set) that also fails on a clean checkout on this machine (local proxy present) — unrelated to this change.

Post-Deploy Monitoring & Validation

• What to monitor: percy-api warn logs "machine identity ingest skipped" (should stay ≈0); Redis key growth percy:api:build-machines:* (bounded by active builds, 25h TTL).
• Validation: run a parallel build with this CLI against an org with the slow-build-diagnostics flag ON → build show JSON carries machine facts in diagnosis; kill one shard → machine named in the receiving-state alert.
• Expected healthy behavior: zero change for orgs with the flag off; no additional CLI network calls (attributes/header ride existing requests).
• Failure signal / rollback: any snapshot POST regression correlated with the header → revert this PR; the API ignores absent identity entirely.
• Window & owner: first minor release post-merge, @shivanshusingh.

🤖 Generated with Claude Code

[Shivanshu-07]

CI is green (30/30). For the record on the two reds seen along the way:

• Test @percy/env and Test @percy/client were mine: both packages enforce 100% line and branch coverage via test:coverage (a different command from test, which is what I'd run locally), and the new machine getter left the buildkite/gitlab cases, the hostname-failure path, and the no-machine-identity fallbacks uncovered. Fixed in ee8b24d and 3c6ceff — both packages now report 100/100/100/100.
• Test @percy/core (Windows leg only) failed on should retry by default on the snapshot discovery upto 3 times, which observed 2 retry log lines instead of 3. That is a timing assertion in packages/core; this PR touches only packages/env and packages/client, and the Linux core leg passed on the same commit. Re-ran the job and it passed, so it was flaky rather than related.

[Shivanshu-07]

Summary

CLI side of Build-processing diagnostics (slow builds) — PER-10496. Pairs with percy-api https://github.com/percy/percy-api/pull/6715, which validates and consumes everything sent here for per-machine liveness on parallel builds (naming the dead CI machine when one stops sending snapshots).

• env.machine getter (@percy/env): { id, hostname, runUrl } — sanitized-hostname id suffixed with the CI node index where the provider exposes one (CIRCLE_NODE_INDEX, BUILDKITE_PARALLEL_JOB), and the CI run URL for circle/buildkite/github/gitlab. Deliberately excluded from the env getter debug logging (like token) — those debug logs are uploaded with build logs, and hostnames should not ride along.
• Build create (@percy/client): machine-id / machine-hostname / machine-ci-run-url attributes (only when an id exists).
• X-Percy-Machine-Id header on snapshot-create and build-finalize calls, attached per-call via machineHeaders() — never in headers(), so it cannot leak to off-domain requests (validateDomain).

Server-side: percy-api enforces charset/length limits and an https + CI-host allowlist on the URL, and treats all of it as advisory. Old CLI versions degrade gracefully (the feature falls back to non-machine-specific messaging).

Testing

• @percy/env: 5 new specs (sanitized id, node-index suffix + run URL on circle, composed GitHub Actions run URL, null run URL fallback, debug-logging exclusion). Suite green (128/128).
• @percy/client: header specs for snapshot + finalize, machine attributes on build create; existing exact-payload expectations updated. Suite green under node 14 except one pre-existing environmental failure (proxy getProxy should return undefined if no proxy is set) that also fails on a clean checkout on this machine (local proxy present) — unrelated to this change.

Post-Deploy Monitoring & Validation

• What to monitor: percy-api warn logs "machine identity ingest skipped" (should stay ≈0); Redis key growth percy:api:build-machines:* (bounded by active builds, 25h TTL).
• Validation: run a parallel build with this CLI against an org with the slow-build-diagnostics flag ON → build show JSON carries machine facts in diagnosis; kill one shard → machine named in the receiving-state alert.
• Expected healthy behavior: zero change for orgs with the flag off; no additional CLI network calls (attributes/header ride existing requests).
• Failure signal / rollback: any snapshot POST regression correlated with the header → revert this PR; the API ignores absent identity entirely.
• Window & owner: first minor release post-merge, @shivanshusingh.

🤖 Generated with Claude Code

[Shivanshu-07]

CI is green (30/30). For the record on the two reds seen along the way:

• Test @percy/env and Test @percy/client were mine: both packages enforce 100% line and branch coverage via test:coverage (a different command from test, which is what I'd run locally), and the new machine getter left the buildkite/gitlab cases, the hostname-failure path, and the no-machine-identity fallbacks uncovered. Fixed in ee8b24d and 3c6ceff — both packages now report 100/100/100/100.
• Test @percy/core (Windows leg only) failed on should retry by default on the snapshot discovery upto 3 times, which observed 2 retry log lines instead of 3. That is a timing assertion in packages/core; this PR touches only packages/env and packages/client, and the Linux core leg passed on the same commit. Re-ran the job and it passed, so it was flaky rather than related.

[Shivanshu-07]

Summary

CLI side of Build-processing diagnostics (slow builds) — PER-10496. Pairs with percy-api https://github.com/percy/percy-api/pull/6715, which validates and consumes everything sent here for per-machine liveness on parallel builds (naming the dead CI machine when one stops sending snapshots).

• env.machine getter (@percy/env): { id, hostname, runUrl } — sanitized-hostname id suffixed with the CI node index where the provider exposes one (CIRCLE_NODE_INDEX, BUILDKITE_PARALLEL_JOB), and the CI run URL for circle/buildkite/github/gitlab. Deliberately excluded from the env getter debug logging (like token) — those debug logs are uploaded with build logs, and hostnames should not ride along.
• Build create (@percy/client): machine-id / machine-hostname / machine-ci-run-url attributes (only when an id exists).
• X-Percy-Machine-Id header on snapshot-create and build-finalize calls, attached per-call via machineHeaders() — never in headers(), so it cannot leak to off-domain requests (validateDomain).

Server-side: percy-api enforces charset/length limits and an https + CI-host allowlist on the URL, and treats all of it as advisory. Old CLI versions degrade gracefully (the feature falls back to non-machine-specific messaging).

Testing

• @percy/env: 5 new specs (sanitized id, node-index suffix + run URL on circle, composed GitHub Actions run URL, null run URL fallback, debug-logging exclusion). Suite green (128/128).
• @percy/client: header specs for snapshot + finalize, machine attributes on build create; existing exact-payload expectations updated. Suite green under node 14 except one pre-existing environmental failure (proxy getProxy should return undefined if no proxy is set) that also fails on a clean checkout on this machine (local proxy present) — unrelated to this change.

Post-Deploy Monitoring & Validation

• What to monitor: percy-api warn logs "machine identity ingest skipped" (should stay ≈0); Redis key growth percy:api:build-machines:* (bounded by active builds, 25h TTL).
• Validation: run a parallel build with this CLI against an org with the slow-build-diagnostics flag ON → build show JSON carries machine facts in diagnosis; kill one shard → machine named in the receiving-state alert.
• Expected healthy behavior: zero change for orgs with the flag off; no additional CLI network calls (attributes/header ride existing requests).
• Failure signal / rollback: any snapshot POST regression correlated with the header → revert this PR; the API ignores absent identity entirely.
• Window & owner: first minor release post-merge, @shivanshusingh.

🤖 Generated with Claude Code

[Shivanshu-07]

CI is green (30/30). For the record on the two reds seen along the way:

• Test @percy/env and Test @percy/client were mine: both packages enforce 100% line and branch coverage via test:coverage (a different command from test, which is what I'd run locally), and the new machine getter left the buildkite/gitlab cases, the hostname-failure path, and the no-machine-identity fallbacks uncovered. Fixed in ee8b24d and 3c6ceff — both packages now report 100/100/100/100.
• Test @percy/core (Windows leg only) failed on should retry by default on the snapshot discovery upto 3 times, which observed 2 retry log lines instead of 3. That is a timing assertion in packages/core; this PR touches only packages/env and packages/client, and the Linux core leg passed on the same commit. Re-ran the job and it passed, so it was flaky rather than related.