docs(observability): correct supervisor log access and retention

[johntmyers]

Summary

The logging docs direct readers to supervisor files through sandbox exec, which runs in the separate workload filesystem, and describe temporary, best-effort files as a complete durable record. Update the three observability pages to explain supervisor access, driver-specific storage lifetimes, and external collection for retention.

Related Issue

Closes #4242

Changes

• Replace workload-shell file access with Docker/Podman supervisor file-copy examples and supervisor container-log commands.
• Document Kubernetes emptyDir, Docker/Podman tmpfs, VM host logging, rotation, possible loss, and stderr fallback when file logging cannot initialize.
• Explain that the default supervisor image lacks a shell and tar; Kubernetes file access needs operator-managed tooling.
• Distinguish main process output, supervisor logs, the volatile gateway buffer, and the separate gateway-produced OCSF JSONL sink.
• Update the filtering examples to operate on copied supervisor files.

Testing

• mise run docs: passed with zero errors and three warnings unrelated to these edits (an unchanged gateway configuration page fails MDX parsing; redirect checks require authentication; theme contrast is below the recommendation).

• Markdown lint: zero errors.

• git diff --check.

• Repository pre-commit hook: passed, including Rust workspace/perf-harness/E2E/example lint, Markdown/Mermaid checks, Python and TypeScript lint/format checks, protobuf lint, Helm lint/docs checks, lockfile checks, and license headers.

• Source inspection confirmed the logging setup and generated resources on main at 0bca9fb82. No live deployment commands were exercised.

• Rust/SDK unit tests and sandbox E2E are not applicable to these documentation-only changes.

Checklist

• Follows Conventional Commits.
• Commits are signed off (DCO).
• Architecture docs are unchanged; this corrects published instructions for existing behavior.

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-4243.docs.buildwithfern.com/openshell

[matthewgrossman]

The supervisor/workload separation and best-effort retention corrections are warranted and mostly match the post–RFC 12 implementation. I recommend the documentation changes below before merging.

Reviewed head: e06bb7a299cb5344fdc87ff29473e8e2cbb0ace9, against base 0bca9fb8280045224c910610cba005b7fa5a6a83.

1. Docker copy example — new invalid command

docs/observability/accessing-logs.mdx:88–94

Before this PR, readers were directed to the workload filesystem. The replacement targets the supervisor, but docker cp <supervisor-container>:/var/log/. ./supervisor-logs/ still cannot retrieve its live logs because /var/log is tmpfs. Docker documents this limitation, and Moby's archive implementation opens a separate filesystem view whose tmpfs contents are not shared with the running container. Users can copy an empty underlying directory instead of the logs they need.

Please remove or replace the Docker copy instruction with a tested operator-managed access method. docker logs remains valid for filtered shorthand collection. The usual docker exec ... tar workaround is unavailable in the default supervisor image.

This finding does not apply to Podman: its running-container copy implementation joins the live mount namespace, so that example is source-supported.

2. Runtime-originated OCSF — inherited documentation omission

accessing-logs.mdx:105 and the unchanged logging.mdx:235–253

Before the runtime split, these emissions shared the supervisor logging setup. In the current implementation, openshell-sandbox emits process-launch and Landlock OCSF events through its own filtered shorthand subscriber into runtime stderr/workload container logs. It has neither a JSONL sink nor a gRPC LogPushLayer; those belong to the separate supervisor process.

Please clarify that workload logs also contain runtime security events when the diagnostic filter permits them, not just main-process output and warnings. Enabling supervisor JSONL does not capture those runtime-originated records. Without this distinction, operators collecting only supervisor output can miss a separate security-event source.

This is remaining RFC 12 documentation drift, not a new regression introduced by this PR.

3. Independent three-file retention — inherited runtime bug affecting the docs promise

logging.mdx:264 and ocsf-json-export.mdx:74

Both appenders really configure daily rotation and max_log_files(3), but their prefixes overlap: openshell also matches openshell-ocsf. The locked tracing-appender 0.2.5 cleanup uses starts_with(prefix) and creation timestamps when available. Consequently, shorthand pruning can delete JSONL history on filesystems exposing those timestamps.

An isolated reproduction using the exact dependency/settings reduced three existing JSONL files to one after shorthand initialization, and two after both appenders initialized. A negative control changing only the shorthand prefix to openshell-text preserved all three.

Please qualify the independent three-most-recent-files promise. This is an existing, filesystem-dependent runtime bug—not a new PR regression and not a request to expand this documentation PR into a runtime fix.

Verified / limitations

The remaining claims checked correctly: driver-specific locations and storage lifetimes, VM host logging/stderr capture, nonblocking drops, file-init stderr fallback without JSONL, the volatile 2,000-line gateway buffer, gateway JSONL not archiving pushed supervisor logs, filtered shorthand console output, Windows sink settings, and the default image lacking shell/tar.

Fern 5.112.0 check passed with 0 errors and 3 existing unrelated warnings; navigation, Markdown lint, and git diff --check passed. Retention was locally reproduced. Docker copy behavior and runtime event routing were source/call-path validated, not deployment E2E-tested; the local Docker daemon is unavailable.