Profile Sculptor Backend

Profile / debug a running Sculptor backend

This skill gets Python-level visibility into a live sculptor_backend process. There are two routes; prefer Route A and fall back to Route B when you need CPU sampling or when the running build predates the in-process debug endpoints.

Why two routes: macOS blocks task_for_pid on the hardened-runtime, notarized app, so py-spy can't attach until the target is re-signed with get-task-allow (which can't ship on a notarized build — see SCU-1604). The in-process route sidesteps that entirely but only exists in builds new enough to include the endpoints. Background: docs/development/tracing.md (Route A reference) and SCU-1604.

Step 0 — Orient: where am I, and what's the target?

Am I inside Sculptor or an external claude? Check SCULPT_AGENT_ID:

if [ -n "$SCULPT_AGENT_ID" ]; then echo "INSIDE Sculptor"; else echo "EXTERNAL claude"; fi

• INSIDE Sculptor (SCULPT_AGENT_ID set): the sculptor_backend you'd profile is the one hosting this very agent. Route A is safe. For Route B you may build py-spy and attach, but never quit/restart the app or kill the backend — that terminates you. Re-sign and restart are the user's actions.
• EXTERNAL claude: you may run the privileged commands directly — codesign (per the always-ask rule in B3) and sudo py-spy when passwordless sudo is available (B5). The app restart is always the user's job (B4): an external process can't reliably relaunch the user's Sculptor.

Find the running backend (pid, port, binary path):

pgrep -fl 'sculptor_backend --port' || ps aux | grep '[s]culptor_backend --port'
# port (also in $SCULPT_API_PORT / $SCULPTOR_API_PORT when set):
ps -o command= -p "$BACKEND_PID" | grep -oE -- '--port [0-9]+' | awk '{print $2}'

Derive the bundle executable from the running pid rather than assuming a path (it differs between Sculptor.app and Sculptor Dev.app); typically /Applications/Sculptor.app/Contents/Resources/sculptor_backend/sculptor_backend.

Step 1 — Is Route A available on this build? (probe)

The in-process endpoints only exist in builds that shipped them. Probe:

PORT="${SCULPT_API_PORT:-${SCULPTOR_API_PORT:-5050}}"
curl -s -H "x-session-token: $SESSION_TOKEN" "http://localhost:$PORT/api/v1/trace/status"

• JSON like {"enabled":false,...} → Route A is available. Use it.
• HTML (<!doctype html>…) or 404 → endpoints absent in this build → use Route B (py-spy), or install a newer build if in-process tracing is desired.

Route A — sculpt debug (in-process; no privileges)

No re-sign, safe from inside Sculptor. If the running build ships the new sculpt, use the CLI; otherwise call the endpoints directly with curl. The CLI targets the backend via SCULPT_API_PORT (default 5050) and authenticates with the session token automatically.

Instant all-thread Python stacks (greenlet-safe; best for a wedged backend):

sculpt debug threads                 # to stdout
sculpt debug threads -o threads.txt  # to a file
# Direct equivalent (any build with the endpoint):
curl -s -H "x-session-token: $SESSION_TOKEN" "http://localhost:$PORT/api/v1/debug/threads"

Bounded viztracer trace → Perfetto:

sculpt debug trace start                 # arm (optionally --tracer-entries N)
# …reproduce the slow/interesting activity…
sculpt debug trace status                # running? buffered counts?
sculpt debug trace stop                  # flush; prints the output path
# Direct equivalents:
curl -s -XPOST -H "x-session-token: $SESSION_TOKEN" "http://localhost:$PORT/api/v1/trace/start"
curl -s -XPOST -H "x-session-token: $SESSION_TOKEN" "http://localhost:$PORT/api/v1/trace/stop"

Open the resulting trace-<timestamp>.json (written under the backend's {LOG_PATH}/traces/ — ~/.sculptor/internal/logs/traces/ in a normal install; the exact path is returned by stop) at https://ui.perfetto.dev.

This is the runtime side of the tracing system; see docs/development/tracing.md for the full reference (what's captured, sources/pids, clock caveat, sensitive-data handling, endpoint security). Operationally: only one trace runs at a time (start → 409 if already armed); the ring buffer holds DEFAULT_ADHOC_TRACER_ENTRIES events by default (bounded server-side; raise with --tracer-entries) and wraps when full; and a runtime-armed trace is backend-Python only — for renderer/Electron-main lanes you need a from-boot sculptor --trace-to=<path> run (see tracing.md).

Route B — py-spy (attach; CPU sampling, flamegraphs, native stacks)

B1. Get a working py-spy

Stock py-spy mis-resolves the bundled libpython image base in our PyInstaller onedir layout and fails with Unsupported version of Python: 0.0.0. The fix is upstream in benfred/py-spy#858 ("Adjust the PyInstaller MacOS image base").

py-spy source — pick the first that applies:

1. Official, once #858 ships in a release — prefer plain cargo install py-spy / a released binary. Check whether #858 has landed: gh pr view 858 --repo benfred/py-spy --json state,mergedAt.
2. Until then, build the fork branch (needs Rust/cargo) and cache it:

# Override PYSPY to point at any working build (e.g. a released py-spy once #858 lands).
PYSPY="${PYSPY:-$HOME/.cache/sculptor-pyspy/bin/py-spy}"
if ! "$PYSPY" --version >/dev/null 2>&1; then
  cargo install --git https://github.com/trisiak/py-spy \
    --branch pyinstaller-macos-image-base --root "$HOME/.cache/sculptor-pyspy"
  PYSPY="$HOME/.cache/sculptor-pyspy/bin/py-spy"
fi
"$PYSPY" --version

B2. Is a re-sign even required? (inspect first)

Check whether the running backend's binary already allows task attachment — don't re-sign blindly (it may already be signed, e.g. from a previous session):

codesign -d --entitlements - "$BACKEND_BIN" 2>&1 | grep -q get-task-allow \
  && echo "already attachable — skip B3/B4" || echo "re-sign needed (B3)"

If it already has get-task-allow, skip to B5. Dev builds (Sculptor Dev.app, from just pkg-dev) ship the sidecar already signed with get-task-allow (see forge.config.ts postPackage + entitlements.dev.plist), so this check passes and no re-sign is needed — only the notarized production app requires B3.