External Attach Diagnostic

External Attach Diagnostic

Use this only for an authorized, live macOS incident investigation when an external observer needs bounded process stacks. It is a reusable script, not an in-process debug mode and not a timing profiler: its samples are stacks, not semantic stage timings.

The script is at scripts/external_attach_diagnostic.py. Run it from a Python environment that can import the target LingTai runtime. It requires exact --agent-dir and --pid, plus an absent absolute --artifact-dir:

python3 scripts/external_attach_diagnostic.py \
  --agent-dir /absolute/path/to/agent \
  --pid 12345 \
  --artifact-dir /absolute/empty-parent/attach-20260824

Preconditions and refusal rules

1. It is macOS-only and requires executable /usr/bin/sample. Unsupported host/tool failure happens before it creates the artifact directory or mutates the agent directory.
2. --agent-dir and the artifact parent must be canonical absolute directories; the artifact target itself must not exist. The script creates only that new evidence directory (mode 0700).
3. The supplied PID is verified through the existing process-table adapter and canonical match_agent_run, then bound to a stable existing process_identity before and after each capture. It never trusts PID alone or a command substring.
4. Default mode is observational with respect to the agent: it writes only the requested evidence directory and refuses any notification mutation unless the explicit controlled-burst flag is present.

Artifacts contain bounded /usr/bin/sample stack files and an evidence.json record with a hashed start-identity token, kernel identity, heartbeat age, and safe file counts. They do not read or record prompt, notification, tool, or secret bodies. Stack capture does not infer semantic stages or timings.

Optional related PIDs are operator-supplied only and must each have a stable incarnation identity:

python3 scripts/external_attach_diagnostic.py \
  --agent-dir /absolute/path/to/agent --pid 12345 \
  --related-pid 12361 --related-pid 12372 \
  --sample-seconds 3 --artifact-dir /absolute/empty-parent/attach-20260824

--sample-seconds is bounded to 1–10 seconds; at most eight related PIDs are accepted. The script suppresses /usr/bin/sample stdout/stderr from the artifact record and stores only stack outputs.

Controlled external producer burst (exceptional)

This is a separate, explicitly opt-in simulation of an external producer; it does not call the Store and therefore does not exercise Store locking. After all read-only preflight and stack capture succeeds, it atomically creates exactly one unique, content-free file:

python3 scripts/external_attach_diagnostic.py \
  --agent-dir /absolute/path/to/agent --pid 12345 \
  --artifact-dir /absolute/empty-parent/attach-control \
  --controlled-burst --burst-run-id incident-20260824-a

The target is exactly .notification/mcp.external-attach-diagnostic.<run-id>.json. Its exclusive creation refuses an existing target rather than overwriting or merging any notification. The payload is only a control marker/run ID; it contains no prompt, notification, or tool body. The script never creates .notification/ for this purpose: a canonical existing directory is required.

If cleanup is authorized after observing the burst, use the same exact run ID:

python3 scripts/external_attach_diagnostic.py \
  --agent-dir /absolute/path/to/agent --pid 12345 \
  --artifact-dir /absolute/empty-parent/attach-cleanup \
  --cleanup-controlled-burst --burst-run-id incident-20260824-a

Cleanup is deliberately narrow: it revalidates the exact filename and its own content-free marker before deleting it. It cannot enumerate, clear, or touch any other notification file, and it refuses an absent, malformed, altered, or foreign target.

Limits

• No in-process debug mode, cache, notification cap, database, refresh, restart, or daemon-manager operation is involved.
• It cannot establish causality from stacks. Preserve external timing/incident context separately if authorized.
• A changed PID incarnation during preflight or sampling makes the invocation fail rather than attributing output to a recycled PID.
• Do not use this script as a notification Store concurrency test. The focused cross-process Store tests own real native lock-path coverage.