Module controls 

Explicit trace controls (Task 12, spec §5.1 raw-capture clause + §6.1 surfaces): /trace next, /trace next content, /trace status.

One-shot semantics

Arming (/trace next) enables tracing for exactly the next logical outgoing provider request — even when the telemetry config level is Off — and then auto-disarms. The armed ephemeral context carries a one-shot request gate consumed inside RequestTracer::begin: the first request wins, all of its retry attempts emit, and subsequent tool-loop requests through the same context are disabled. It never silently enables indefinite persistence: when telemetry is Off the one-shot record rides an ephemeral writer whose handle the runtime retains (in its one-shot state, off the request path) until it is replaced by a re-arm or drained by the shutdown_observability* exit epilogue — so the armed record flushes even when the session exits immediately after the request. The existing Basic/Full config rule is unchanged — arming on top of an already-enabled session only adds the (optional) content capture.

Content capture (explicit, ephemeral, redacted)

Persisted traces contain no content, so synaps trace export --include-content needs an explicit capture: /trace next content arms a one-request, bounded, redacted capture of the request body. Security decisions, deliberately conservative:

• capture is redacted at capture time (structural media scrub plus recursive credential-key / secret-pattern scrub, see trace::export::redact_value) — raw media never touches disk;

• plain text remains explicitly authorized content: a text document lowered to ordinary OpenAI text/input_text has lost its structural provenance and cannot be distinguished from a typed prompt here. Its text may be captured under this opt-in (subject to the secret scrub);

• the bundle is written with the Phase 1 private-fs helpers (0600 file, 0700 parent, symlink-refusing, atomic) under <synaps base dir>/trace/capture/;

• the bundle carries its own schema tag (synaps-trace-content-capture/1) so it can never masquerade as a synaps-request-trace/1 record;

• capture is bounded (CAPTURE_MAX_BYTES) and expires (CAPTURE_TTL): trace export --include-content consumes (deletes) it, and an expired bundle is refused and deleted instead of exported;

  Expiry semantics (documented guarantee): expiry is logical — an expired bundle can never be exported (the export path checks the embedded expires_unix_ms and deletes stale bundles). Physical deletion is a bounded, fail-soft sweep run at Runtime/session startup, in both the sync and async shutdown epilogues, and on every trace interaction (every new capture, /trace status, every synaps trace export invocation). A bundle left behind by a killed process may therefore sit (private 0600 file, already redacted) on disk past its TTL until the next session startup/shutdown or trace interaction — but it is unreadable through any supported export path from the moment it expires;

• only the request body is captured — headers, cookies, and credentials never enter the capture path by construction (they are attached by the HTTP client after the body is built).

The capture file is how the arm crosses the process boundary to a later synaps trace export invocation without weakening privacy: the on-disk artifact is already redacted, private, bounded, and short-lived.

Structs

ContentCapture

One-request content capture arm, attached to a TraceContext when the user ran /trace next content. Fires at most once.

ContentCaptureBundle

On-disk shape of the capture bundle. Clearly labeled non-request-trace schema; redacted is a hard marker checked again on export.

TraceControls

Session trace controls: one-shot arm consumed by the next request.

TraceStatusReport

Metadata-only status for /trace status: mode, persistence path, counters. Never secrets, never content.

Enums

TraceArm

Current arm state.

Constants

CAPTURE_MAX_BYTES

Upper bound on captured (post-redaction) body bytes.

CAPTURE_TTL

Retention window for a capture bundle.

CONTENT_CAPTURE_SCHEMA

Schema tag for the ephemeral content-capture bundle. Distinct from the request-trace schema by design.

Functions

capture_path

Path of the capture bundle for a request ID.

default_capture_dir

Default capture directory: <synaps base dir>/trace/capture/.