[Task]: expose a read-only Turn journal inspection surface

[ObVious55]

Task ID or area

turn / effect program

Intent

I need design feedback before implementation

Summary

PR #3189 introduced the read-only interpret_turn_journal lens, which projects an existing fenced Turn journal into the canonical EffectTurn shape. It reports exact goal, owner, and Turn-key identity consistency, ordered transaction-phase prefixes, terminal tombstone retention, replay legality, and stable typed violations.

The lens currently has a Python API, focused tests, and reference documentation, but no developer-facing command for inspecting an existing journal. Diagnosing a journal therefore requires reading raw JSON or writing an ad hoc Python caller, which can duplicate interpretation rules and expose more journal data than necessary.

I would like design feedback on a small read-only consumer:

loopx turn inspect-journal \
  --goal-id <goal-id> \
  --agent-id <agent-id> \
  --turn-key <sha256:...> \
  --format json

The command would locate an existing journal through the canonical Turn journal path, reuse the existing schema and locking boundary, call interpret_turn_journal, and render a compact JSON or Markdown inspection result.
PR #3193 owns fail-closed enforcement in the actual settlement replay path. This proposal does not change or duplicate that execution responsibility: it will not participate in resume or settlement, and its result will not be used as execution authority. It only exposes the read-only interpretation already provided by #3189.

Proposed scope

In scope:

• Add one read-only loopx turn inspect-journal subcommand.
• Accept exact goal_id, agent_id, and turn_key inputs.
• Resolve the journal through the canonical runtime root and Turn journal path.
• Reuse the existing journal schema check and file-locking read boundary.
• Call interpret_turn_journal as the only source of identity, phase-order, terminal-status, replay-legality, and violation semantics.
• Render compact JSON and Markdown through the existing CLI output mechanism.
• Expose only public-safe interpretation fields:
  • journal status;
  • replay legality;
  • goal, owner, and Turn-key match results;
  • ordered phase-prefix result;
  • completed phases;
  • tombstone retention;
  • typed violations;
  • empty next_effect.
• Treat replay_blocked as a successfully inspected state.
• Return a non-zero result only when inspection cannot be completed, such as a missing journal, malformed JSON, unsupported schema, or invalid command identity.
• Add focused synthetic tests proving that inspection does not mutate the journal or invoke any effect.

Out of scope:

• No arbitrary --journal-path input.
• No raw journal, stored plan, host result, receipt body, prompt, transcript, credential, private evidence, or local path output.
• No new replay or journal ledger.
• No changes to interpret_turn_journal violation semantics in the first slice.
• No resume or retry decision.
• No call to execute_turn_driver_settlement.
• No changes to PR fix(turn): fail closed on key/owner-mismatched settlement replay (GH-C83 M7.1 parity) #3193 settlement identity enforcement.
• No receipt generation or re-attribution.
• No state writeback, quota spend, scheduler action, or model/host invocation.
• No status, dashboard, or attention-queue integration.

Design questions:

1. Should interpret_turn_journal gain a public read-only CLI consumer, or remain a Python-only refactor/test lens?
2. Should the JSON output expose the canonical four EffectTurn slots directly, or use a smaller inspection projection?
3. Should successful inspection with replay_legal=false exit zero, keeping replay legality as diagnostic data?

My preference is to serialize the existing EffectTurn slots, return zero whenever inspection succeeds, and reserve non-zero exits for failures to load or interpret the requested journal.

Relevant files or commands

Likely files:

• loopx/cli_commands/turn.py
• loopx/control_plane/effect_program.py
• loopx/control_plane/turn_driver/executor.py, or the maintainer-preferred bounded home for the existing journal reader
• tests/control_plane/test_effect_turn_turn_journal.py
• a focused CLI test such as tests/test_loopx_turn_journal_inspection.py
• docs/reference/effect-interpreter-packet.md
• docs/reference/protocols/loopx-turn-v0.md

Existing reference behavior:

• interpret_turn_journal
• turn_journal_path
• _load_journal
• load_loopx_turn_plan_from_journal
• loopx turn plan
• loopx turn run-once

Validation plan

Focused lens and CLI tests:

python -m pytest -q \
  tests/control_plane/test_effect_turn_turn_journal.py \
  tests/test_loopx_turn_journal_inspection.py

Existing Turn regression coverage:

python -m pytest -q \
  tests/test_loopx_turn_executor.py \
  tests/test_loopx_turn_transaction.py \
  tests/test_loopx_turn_driver.py

Existing fake-host walkthrough:

python examples/loopx-turn-fake-host-walkthrough-smoke.py

Additional validation:

• Run targeted Ruff and Python compilation checks on changed files.
• Cover legal, blocked, malformed, missing, and unsupported-schema cases.
• Confirm the journal bytes remain unchanged after inspection.
• Confirm no host execution, settlement, receipt creation, writeback, quota spend, or scheduler action occurs.

Run:

loopx check \
  --scan-path loopx/cli_commands/turn.py \
  --scan-path loopx/control_plane/effect_program.py \
  --scan-path docs/reference/effect-interpreter-packet.md \
  --scan-path docs/reference/protocols/loopx-turn-v0.md

git diff --check

Run the repository risk-based premerge validation selected for the final diff.

Public/private boundary

• This issue does not include private benchmark traces, verifier output, credentials, internal document links, raw agent sessions, or local runtime state.
• I will not run or duplicate maintainer-owned benchmark cases unless a maintainer explicitly splits out a public task.

[huangruiteng]

Design verdict: yes, this is a useful narrow consumer, provided it remains a Turn-owned read surface and does not make the internal EffectTurn dataclass the public CLI wire contract.

This has more immediate value than a new observability subsystem: the production Turn path already writes the fenced journal, and interpret_turn_journal already defines the pure Effect Program read semantics. A CLI consumer would complete a real writer → reader conformance path and remove ad-hoc raw-JSON inspection.

I recommend the following contract.

1. Keep ownership in the existing Turn bounded context

• No new capability, event store, ledger, or replay authority.
• Keep interpret_turn_journal pure in control_plane.effect_program.
• Add one public Turn read seam (for example inspect_loopx_turn_journal(...)) beside the canonical journal loader. It should validate selectors, acquire the existing lock, load/schema-check one journal, call the interpreter, and return a versioned allowlisted inspection projection.
• The CLI should call that public seam; it must not import _load_journal or reconstruct interpretation fields itself.

2. Do not serialize all four internal EffectTurn slots directly

EffectTurn is a useful code lens, but exposing it wholesale would make every future field addition a CLI/API and privacy decision. Please define a compact loopx_turn_journal_inspection_v0 projection containing only:

• decision (replay_legal / replay_blocked);
• journal_status and replay_legal;
• goal/owner/Turn-key match booleans;
• ordered-prefix boolean and completed phase ids;
• tombstone-retained boolean;
• typed violation ids;
• an explicit effect-free marker such as effects: [].

JSON and Markdown should render the same projection. Do not expose recommended_action, raw request.context, journal/plan/receipt bodies, capabilities, or resolved paths.

3. Exit status should describe inspection, not replay eligibility

• Exit 0 whenever a journal was successfully loaded and interpreted, including replay_legal=false.
• Exit non-zero for invalid selector syntax, missing journal, malformed JSON, unsupported schema, or another failure to inspect.
• Distinguish selector validity from journal-content mismatch: an owner/goal/key mismatch discovered inside the loaded journal is the diagnostic result and should remain exit 0, not be collapsed into a CLI failure.

4. Two implementation gates are important

1. turn_journal_path currently validates turn_key but joins goal_id directly. The new direct CLI must run the repository's canonical goal-id path-segment validation before path construction; “no --journal-path” alone does not prevent traversal through --goal-id.
2. handle_turn_command currently enters status collection and live quota/Turn planning before dispatching plan versus run-once. inspect-journal must branch into its read path before collect_status, quota decision construction, scheduler context, scans, or any planning path. Otherwise this supposedly narrow inspection command inherits unrelated live-control-plane dependencies.

Validation expected

In addition to the proposed legal/blocked/malformed/missing/schema cases:

• reject a path-traversal goal id before filesystem access;
• trap/monkeypatch status, quota, host, settlement, spend, scheduler, and write functions so the inspection test proves none are reached;
• prove both journal bytes and directory contents (apart from the established lock-file behavior, if any) are unchanged;
• prove Markdown and JSON are derived from the same allowlisted projection;
• use a valid 64-hex Turn key in filesystem-level tests.

With those adjustments, I support implementing this as one small PR. PR #3193 remains the only replay/settlement enforcement path; this command is evidence inspection only and must never become an execution gate or authority.