Skip to content

Add deterministic schema-1 real-PTY harness (Fixes #380)#402

Merged
acoliver merged 16 commits into
mainfrom
issue380
Jul 24, 2026
Merged

Add deterministic schema-1 real-PTY harness (Fixes #380)#402
acoliver merged 16 commits into
mainfrom
issue380

Conversation

@acoliver

@acoliver acoliver commented Jul 23, 2026

Copy link
Copy Markdown
Contributor

Summary

  • adds a strict schema-1-only scenario contract with closed parsing, bounded resources, typed HAR diagnostics, and prefix-only workspace interpolation
  • executes scenarios synchronously in a contained mode-0700 workspace with deterministic environment construction, no-follow identity checks, and serialization-boundary redaction
  • adds a Rust capture shim, deterministic probe, real-PTY process-group ownership, bounded waits, exact-size resize acknowledgement, restart/cleanup semantics, canonical reports, and the tmux_scenario CLI
  • adds eight schema-1 ledger fixtures plus unit, integration, containment, timeout/reaping, capture, redaction, restart, and resize evidence
  • documents the operator contract and quality rules

Scope boundary

Schema 1 is the only input accepted by the new runner. This PR adds no legacy adapter, lowering pass, compatibility shim, dual parser, or format-detection path.

Existing pre-schema scenarios and their harness remain temporarily unchanged so this foundational PR has one executable boundary. Immediate follow-up #397 migrates every shipped scenario forward to schema 1, updates all callers, proves equivalence, and deletes the superseded harness/parser. No runtime compatibility path is permitted there either.

The issue delivery exceeds the normal size guardrail (43 issue files and about 6.9k added lines before mainline integration). The user explicitly approved one cohesive PR and declined stacked PRs. The implementation is separated into focused modules and green commits.

Acceptance evidence

  • CW00-01/02: strict schema-1 parsing and missing/wrong-schema rejection
  • CW00-03: exact capture argv/env/cwd/stdin/stdout/stderr/exit records
  • CW00-04: workspace interpolation and dollar escaping tests
  • CW00-05: 100x30 and fresh 70x18 resize frames
  • CW00-06: durable-file restart and process replacement
  • CW00-07: symlink/ancestor containment rejection
  • CW00-08: synchronized hanging child/grandchild startup, timeout exit 124, and process-group reaping
  • CW00-09: longest-first redaction across reports, frames, streams, paths, env, errors, and capture names
  • CW00-10: bound and limit-plus-one validation before launch

Verification

  • make ci-check
  • focused schema-1 unit and integration suites
  • timeout fixture stress-run five consecutive times
  • two bounded pre-PR Open Code Review cycles completed and triaged
  • latest origin/main integrated with a true merge; post-merge full verification passed

Fixes #380

Summary by CodeRabbit

  • New Features
    • Added deterministic schema-1 terminal harness support for real-process scenarios with PTY execution.
    • Added new scenario execution and harness helper tools for probe and capture workflows.
  • Documentation
    • Documented the schema-1 harness contract, diagnostics, limits, and migration guidance.
    • Added testing standards and a suite of scenario fixtures (captures, containment, interpolation, limits, redaction, resizing/restart, timeouts).
  • Tests
    • Added unit tests for strict schema parsing/validation, interpolation, redaction, and workspace containment.
    • Added end-to-end PTY integration tests running the shipped scenario fixtures.

acoliver added 9 commits July 22, 2026 19:46
…axonomy (#380)

Slice S1 of the deterministic real-process TUI harness: closed contract
types, a bounded strict JSON reader (duplicate-key rejection, decimal
integers, inclusive depth/member/array/string/input limits), scalar
validators (RelPath, EnvName, capture Id, strict base64, secrets),
workspace-prefix-only interpolation grammar, cross-field semantic rules,
and the HAR-E001..E007 taxonomy with the 0/2/4/124 exit mapping.

Schema-1 is the only accepted input by explicit decision: missing or
wrong schema is HAR-E001. No legacy adapter or compatibility shim; the
shipped pre-schema scenarios migrate forward in CW-00b (#397).
Slice S2: mode-0700 unique workspace with no-follow ancestor identity
verification (HAR-E004 on symlink swap or replaced-directory races, no
check-then-follow path), fixture materialization with declared modes,
the empty-base deterministic environment rooted in the workspace, and
the longest-first secret redactor applied at the serialization boundary.
Slice S3: the jefe-capture-shim fixture locates its behavior file
beside its own executable (no env, no PATH lookup, no shell), claims a
start ordinal atomically via create_new lock files (bounding processes
per capture at 32), records raw argv, sorted env pairs, cwd, bounded
stdin, configured streams and exit, and supports hang/spawn_child_hang
for timeout and reaping tests. Registration materializes the shim into
the workspace through the contained no-follow path; assert-capture
compares every recorded field and raises HAR-E006 on mismatch.
Slice S4: PtySession owns the portable-pty launch (setsid gives the app
its own process group), input delivery, the merged output stream, an
alacritty_terminal grid for exact-size frames, resize, and escalating
TERM/KILL/verify teardown bounded at 2s per phase via fixed-path
/bin/kill (no shell, no PATH lookup, no unsafe). The runner executes
the validated plan sequentially: bounded literal waits, exact-dimension
resize acknowledgement, restart preserving durable files while
replacing/reaping the process group, capture assertion, and
failure-stop with workspace retention. A closed key-encoding table and
the jefe-harness-probe fixture app complete the slice; e2e tests cover
CW00-03/05/06/08/09 against real processes.
Slice S5: the tmux_scenario binary reads one schema-1 scenario, runs it,
prints exactly one deterministic redacted report, and returns 0/2/4/124.
Schema-1 is the only accepted input; pre-schema documents fail with
HAR-E001 (no legacy adapter — migration is issue #397). The eight CW00
ledger fixtures live under dev-docs/tmux-scenarios/v1/ and execute
through tests/harness_v1_fixtures.rs against the real runner. Capture
expectations normalize workspace-rooted recorded values to the
${workspace} token so fixtures can state exact bytes despite unique
workspace paths, and listed env pairs match by name while deterministic
base variables remain permitted. The probe sequences RUN output so
consecutive identical commands stay awaitable, and the workspace root is
canonicalized so recorded process fields share its prefix. Docs: the
schema-1 grammar, ownership map, containment algorithm, exits, limits,
and the bounded-literal-wait rule in tmux-harness.md plus the standards
index.
@coderabbitai

coderabbitai Bot commented Jul 23, 2026

Copy link
Copy Markdown

Review Change Stack

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • ▶️ Resume reviews
  • 🔍 Trigger review
📝 Walkthrough

Walkthrough

The PR adds a schema-1 deterministic real-process TUI harness with strict parsing, contained workspaces, hermetic environments, capture shims, PTY execution, redacted reports, CLI binaries, scenario fixtures, and unit/integration coverage.

Changes

Schema-1 deterministic harness

Layer / File(s) Summary
Schema contract and validation
src/harness/v1/contract.rs, src/harness/v1/json.rs, src/harness/v1/parse*.rs, src/harness/v1/validate.rs, src/harness/v1/semantic.rs, dev-docs/testing/tmux-harness.md
Adds strict schema-1 JSON parsing, typed steps, bounds, interpolation rules, diagnostics, key encoding, semantic validation, and the documented no-legacy-adapter contract.
Contained workspace and deterministic environment
src/harness/v1/workspace.rs, src/harness/v1/env.rs, src/harness/v1/interp.rs
Adds unique mode-0700 workspaces, no-follow identity checks, fixture materialization, hermetic environment construction, and workspace interpolation.
Capture and PTY execution
src/harness/v1/capture.rs, src/bin/jefe-capture-shim.rs, src/harness/v1/pty.rs, src/harness/v1/runner.rs, src/bin/jefe-harness-probe.rs
Adds invocation recording, hanging-process handling, real-PTY execution, frame and resize handling, restart, waits, assertions, and process-group cleanup.
Reports, CLI, fixtures, and verification
src/harness/v1/report.rs, src/harness/v1/redact.rs, src/bin/tmux_scenario.rs, Cargo.toml, dev-docs/tmux-scenarios/v1/*, tests/harness_v1*.rs
Adds bounded redacted reports, executable targets, schema-1 ledger fixtures, documentation, and end-to-end tests for capture, interpolation, containment, limits, resize/restart, timeout, and redaction.

Estimated code review effort: 5 (Critical) | ~120 minutes

Possibly related issues

  • #380 — Implements the deterministic schema-1 real-process TUI harness described by the issue.
  • #397 — The PR documents follow-up migration of remaining scenarios and removal of the superseded harness.
🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Linked Issues check ✅ Passed The PR implements the schema-1 parser, runner, PTY/workspace/capture/redaction features, docs, fixtures, and tests required by #380.
Out of Scope Changes check ✅ Passed The changes are centered on the schema-1 harness, docs, fixtures, tests, and supporting binaries; no unrelated code paths stand out.
Docstring Coverage ✅ Passed Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title accurately summarizes the main change: adding a deterministic schema-1 real-PTY harness for issue #380.
📋 Issue Planner

Let us write the prompt for your AI agent so you can ship faster (with fewer bugs).

View plan for ticket: #380

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch issue380

Comment @coderabbitai help to get the list of available commands.

@github-actions

github-actions Bot commented Jul 23, 2026

Copy link
Copy Markdown

OpenCodeReview — PR #402

  • Reviewed head SHA: 96e646d809b5c4f286bedc30132b239b25dbe79a
  • Merge base: 40254186061171577a56590890fc0c41206a8b38
  • OCR version: open-code-review v1.7.9 (a32f852) linux/amd64 built at: 2026-07-14T03:41:57Z https://github.com/alibaba/open-code-review
  • Phase: review
  • Exit code: 1
  • Run: https://github.com/vybestack/llxprt-jefe/actions/runs/30027681469
  • OCR failed to run or parse output.
  • Artifacts: ocr-review-output contains raw JSON, stdout, stderr, preview, phase, and exit-code diagnostics.

OCR stderr excerpt

(empty)

OCR preview stderr excerpt

(empty)

@acoliver acoliver added the review-ready Opt in to CodeRabbit review after exact-head verification label Jul 23, 2026
Comment thread src/bin/jefe-capture-shim.rs
Comment thread src/bin/jefe-capture-shim.rs
Comment thread src/bin/jefe-harness-probe.rs Outdated
Comment thread src/bin/jefe-harness-probe.rs Outdated
Comment thread src/bin/jefe-harness-probe.rs
Comment thread src/harness/v1/semantic.rs
Comment thread src/harness/v1/workspace_tests.rs
Comment thread tests/harness_v1.rs
Comment thread tests/harness_v1_fixtures.rs
Comment thread tests/harness_v1_fixtures.rs

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 4

🧹 Nitpick comments (1)
src/harness/v1/workspace_tests.rs (1)

120-139: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Consider a symlink-at-target test for remove(), mirroring the write_file attack test.

symlink_target_write_is_containment_error proves write_file won't follow a symlink at the target path, but remove()'s equivalent branch (symlink_metadata + remove_file when the target itself is a symlink) has no analogous test here. Given the file's stated purpose (CW00-07 containment coverage), a mirrored test would directly prove remove() never follows a symlink at the removal target and leaves anything outside the workspace untouched.

Also applies to: 197-213

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/harness/v1/workspace_tests.rs` around lines 120 - 139, Add a containment
test alongside symlink_target_write_is_containment_error for remove(), creating
an outside victim, placing a workspace symlink at the removal target, and
calling remove() on it. Assert the operation returns the expected containment
error and verify the outside victim remains unchanged, covering the
symlink_metadata/remove_file branch.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/harness/v1/parse_step.rs`:
- Around line 129-169: Validate the parsed Step::Key in parse_key or
semantic::validate by calling keys::encode for the key and modifiers before
execution begins. Propagate encoding errors as HarnessError syntax/validation
errors, while preserving the existing duplicate and unknown-modifier checks, so
unsupported keys and modifier combinations fail before runner.rs performs side
effects.
- Around line 315-331: Update parse_byte_pairs to use the shared parse_env_list
validator for CaptureExpectation.env instead of manually parsing entries. Remove
the custom name/value loop and preserve the existing Result<Vec<EnvVar>,
HarnessError> behavior so MAX_ENV and Env validation are consistently enforced.

In `@src/harness/v1/semantic.rs`:
- Around line 25-36: Extend semantic validation around the path collection in
the workspace validation flow to reject any configured path nested beneath a
previously configured file path, including file/descendant and file/directory
collisions. Preserve exact-duplicate detection and file-size checks, and keep
validation deterministic without moving materialization side effects into
src/**/*.rs.

In `@src/harness/v1/workspace.rs`:
- Around line 292-328: Update open_dir_nofollow to classify only ELOOP failures
as HarnessError::containment and route all other I/O errors through the existing
process-error classification used by classify_open_error. Preserve the no-follow
directory-open behavior and the existing verify_ancestor callers.

---

Nitpick comments:
In `@src/harness/v1/workspace_tests.rs`:
- Around line 120-139: Add a containment test alongside
symlink_target_write_is_containment_error for remove(), creating an outside
victim, placing a workspace symlink at the removal target, and calling remove()
on it. Assert the operation returns the expected containment error and verify
the outside victim remains unchanged, covering the symlink_metadata/remove_file
branch.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: d6668b34-6b85-4577-ab5a-fb379673869d

📥 Commits

Reviewing files that changed from the base of the PR and between 4025418 and 349b591.

📒 Files selected for processing (43)
  • Cargo.toml
  • dev-docs/standards/testing-and-quality.md
  • dev-docs/testing/tmux-harness.md
  • dev-docs/tmux-scenarios/v1/harness-capture.json
  • dev-docs/tmux-scenarios/v1/harness-containment.json
  • dev-docs/tmux-scenarios/v1/harness-interpolation.json
  • dev-docs/tmux-scenarios/v1/harness-limits.json
  • dev-docs/tmux-scenarios/v1/harness-redaction.json
  • dev-docs/tmux-scenarios/v1/harness-resize-restart.json
  • dev-docs/tmux-scenarios/v1/harness-schema-all-ops.json
  • dev-docs/tmux-scenarios/v1/harness-timeout.json
  • project-plans/issue380-plan.md
  • src/bin/jefe-capture-shim.rs
  • src/bin/jefe-harness-probe.rs
  • src/bin/tmux_scenario.rs
  • src/harness/mod.rs
  • src/harness/v1/capture.rs
  • src/harness/v1/capture_tests.rs
  • src/harness/v1/contract.rs
  • src/harness/v1/env.rs
  • src/harness/v1/error.rs
  • src/harness/v1/fields.rs
  • src/harness/v1/interp.rs
  • src/harness/v1/interp_tests.rs
  • src/harness/v1/json.rs
  • src/harness/v1/json_tests.rs
  • src/harness/v1/keys.rs
  • src/harness/v1/limits.rs
  • src/harness/v1/mod.rs
  • src/harness/v1/parse.rs
  • src/harness/v1/parse_step.rs
  • src/harness/v1/parse_tests.rs
  • src/harness/v1/pty.rs
  • src/harness/v1/redact.rs
  • src/harness/v1/report.rs
  • src/harness/v1/runner.rs
  • src/harness/v1/semantic.rs
  • src/harness/v1/validate.rs
  • src/harness/v1/validate_tests.rs
  • src/harness/v1/workspace.rs
  • src/harness/v1/workspace_tests.rs
  • tests/harness_v1.rs
  • tests/harness_v1_fixtures.rs
📜 Review details
⏰ Context from checks skipped due to timeout. (1)
  • GitHub Check: OpenCodeReview
🧰 Additional context used
📓 Path-based instructions (3)
**/*.rs

⚙️ CodeRabbit configuration file

**/*.rs: Apply Jefe's Rust standards. Prefer explicit domain types; use Option for
absence and Result with typed errors for fallible operations. Require no
unwrap or expect in production paths and no unsafe code. Check Unix,
macOS, and native Windows behavior where process, path, terminal, or
runtime boundaries are changed.

Files:

  • src/harness/mod.rs
  • src/harness/v1/interp_tests.rs
  • src/harness/v1/keys.rs
  • src/harness/v1/interp.rs
  • src/harness/v1/redact.rs
  • src/harness/v1/env.rs
  • src/harness/v1/mod.rs
  • src/harness/v1/capture_tests.rs
  • src/harness/v1/error.rs
  • src/harness/v1/json_tests.rs
  • src/harness/v1/workspace_tests.rs
  • src/harness/v1/fields.rs
  • src/bin/tmux_scenario.rs
  • src/harness/v1/validate_tests.rs
  • src/bin/jefe-capture-shim.rs
  • src/harness/v1/json.rs
  • src/harness/v1/semantic.rs
  • src/harness/v1/report.rs
  • src/harness/v1/contract.rs
  • tests/harness_v1.rs
  • tests/harness_v1_fixtures.rs
  • src/harness/v1/parse_step.rs
  • src/harness/v1/parse_tests.rs
  • src/harness/v1/validate.rs
  • src/harness/v1/capture.rs
  • src/bin/jefe-harness-probe.rs
  • src/harness/v1/limits.rs
  • src/harness/v1/pty.rs
  • src/harness/v1/runner.rs
  • src/harness/v1/parse.rs
  • src/harness/v1/workspace.rs
src/**/*.rs

⚙️ CodeRabbit configuration file

src/**/*.rs: Preserve the documented ownership boundaries and unidirectional data
flow. Keep state transitions deterministic and side effects at runtime,
persistence, GitHub, or other boundary modules. Check cancellation,
stale-result, cleanup, and durability behavior for external work.

Files:

  • src/harness/mod.rs
  • src/harness/v1/interp_tests.rs
  • src/harness/v1/keys.rs
  • src/harness/v1/interp.rs
  • src/harness/v1/redact.rs
  • src/harness/v1/env.rs
  • src/harness/v1/mod.rs
  • src/harness/v1/capture_tests.rs
  • src/harness/v1/error.rs
  • src/harness/v1/json_tests.rs
  • src/harness/v1/workspace_tests.rs
  • src/harness/v1/fields.rs
  • src/bin/tmux_scenario.rs
  • src/harness/v1/validate_tests.rs
  • src/bin/jefe-capture-shim.rs
  • src/harness/v1/json.rs
  • src/harness/v1/semantic.rs
  • src/harness/v1/report.rs
  • src/harness/v1/contract.rs
  • src/harness/v1/parse_step.rs
  • src/harness/v1/parse_tests.rs
  • src/harness/v1/validate.rs
  • src/harness/v1/capture.rs
  • src/bin/jefe-harness-probe.rs
  • src/harness/v1/limits.rs
  • src/harness/v1/pty.rs
  • src/harness/v1/runner.rs
  • src/harness/v1/parse.rs
  • src/harness/v1/workspace.rs
tests/**/*.rs

⚙️ CodeRabbit configuration file

tests/**/*.rs: Review changed tests and behavioral coverage as first-class code. Tests
should prove observable success and failure behavior without relying on
arbitrary sleeps, mock call counts, host load, or panic-driven setup.

Files:

  • tests/harness_v1.rs
  • tests/harness_v1_fixtures.rs
🧠 Learnings (2)
📚 Learning: 2026-04-04T21:05:37.792Z
Learnt from: acoliver
Repo: vybestack/llxprt-jefe PR: 36
File: src/github/mod.rs:537-542
Timestamp: 2026-04-04T21:05:37.792Z
Learning: In Rust, it’s acceptable for function parameters to be intentionally unused when their names start with an underscore (e.g., `_cursor: Option<&str>`). If the parameter name is underscore-prefixed, treat it as a deliberate forward-compatibility/API-consistency choice and do not raise an “unused parameter”/dead code warning during code review.

Applied to files:

  • src/harness/mod.rs
  • src/harness/v1/interp_tests.rs
  • src/harness/v1/keys.rs
  • src/harness/v1/interp.rs
  • src/harness/v1/redact.rs
  • src/harness/v1/env.rs
  • src/harness/v1/mod.rs
  • src/harness/v1/capture_tests.rs
  • src/harness/v1/error.rs
  • src/harness/v1/json_tests.rs
  • src/harness/v1/workspace_tests.rs
  • src/harness/v1/fields.rs
  • src/bin/tmux_scenario.rs
  • src/harness/v1/validate_tests.rs
  • src/bin/jefe-capture-shim.rs
  • src/harness/v1/json.rs
  • src/harness/v1/semantic.rs
  • src/harness/v1/report.rs
  • src/harness/v1/contract.rs
  • tests/harness_v1.rs
  • tests/harness_v1_fixtures.rs
  • src/harness/v1/parse_step.rs
  • src/harness/v1/parse_tests.rs
  • src/harness/v1/validate.rs
  • src/harness/v1/capture.rs
  • src/bin/jefe-harness-probe.rs
  • src/harness/v1/limits.rs
  • src/harness/v1/pty.rs
  • src/harness/v1/runner.rs
  • src/harness/v1/parse.rs
  • src/harness/v1/workspace.rs
📚 Learning: 2026-06-22T22:25:52.693Z
Learnt from: acoliver
Repo: vybestack/llxprt-jefe PR: 81
File: src/app_init.rs:11-13
Timestamp: 2026-06-22T22:25:52.693Z
Learning: In Rust, when you call a method that is defined on a trait (e.g., `spawn_session` from `jefe::runtime::RuntimeManager`) on a concrete type (e.g., `TmuxRuntimeManager`), ensure the defining trait is imported into scope (`use ...::RuntimeManager`) if it is not already in scope. Otherwise the call may fail with a “method not found” error because Rust’s method-call resolution requires the trait to be in scope.

Applied to files:

  • src/harness/mod.rs
  • src/harness/v1/interp_tests.rs
  • src/harness/v1/keys.rs
  • src/harness/v1/interp.rs
  • src/harness/v1/redact.rs
  • src/harness/v1/env.rs
  • src/harness/v1/mod.rs
  • src/harness/v1/capture_tests.rs
  • src/harness/v1/error.rs
  • src/harness/v1/json_tests.rs
  • src/harness/v1/workspace_tests.rs
  • src/harness/v1/fields.rs
  • src/bin/tmux_scenario.rs
  • src/harness/v1/validate_tests.rs
  • src/bin/jefe-capture-shim.rs
  • src/harness/v1/json.rs
  • src/harness/v1/semantic.rs
  • src/harness/v1/report.rs
  • src/harness/v1/contract.rs
  • tests/harness_v1.rs
  • tests/harness_v1_fixtures.rs
  • src/harness/v1/parse_step.rs
  • src/harness/v1/parse_tests.rs
  • src/harness/v1/validate.rs
  • src/harness/v1/capture.rs
  • src/bin/jefe-harness-probe.rs
  • src/harness/v1/limits.rs
  • src/harness/v1/pty.rs
  • src/harness/v1/runner.rs
  • src/harness/v1/parse.rs
  • src/harness/v1/workspace.rs
🪛 LanguageTool
project-plans/issue380-plan.md

[style] ~57-~57: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...tring splitting, or host PATH lookup. - No network helpers, no async runtime, no n...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)


[style] ~58-~58: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...o async runtime, no new dependencies. - No changes to .github/workflows, quality...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)


[uncategorized] ~58-~58: The official name of this software platform is spelled with a capital “H”.
Context: ...e, no new dependencies. - No changes to .github/workflows, quality gates, or threshold...

(GITHUB)


[style] ~59-~59: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...flows, quality gates, or thresholds. - No edits to shipped dev-docs/tmux-scenari...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)

🔇 Additional comments (45)
src/harness/v1/capture.rs (2)

144-153: 🩺 Stability & Availability

Records loading stops at the first ordinal gap.

load_records breaks as soon as neither {n}.json nor {n}.start.json exists. This is correct only under the invariant that every claimed ordinal writes a start record before the shim can hang or be reaped. If a shim is killed in the window between claiming its .lock and writing .start.json, that slot leaves a gap and all higher-ordinal records are silently dropped from the report. Worth confirming the claim→start write is guaranteed to be non-interruptible by the harness escalation path.


181-182: 🎯 Functional Correctness

invocation is already constrained to 1+ before reaching this code.
src/harness/v1/parse_step.rs parses CaptureExpectation.invocation with (1, u64::MAX), so expectation.invocation - 1 cannot underflow on the normal path.

			> Likely an incorrect or invalid review comment.
src/bin/jefe-capture-shim.rs (1)

35-67: LGTM!

src/harness/v1/capture_tests.rs (1)

52-147: LGTM!

src/harness/v1/runner.rs (1)

49-90: LGTM!

src/bin/jefe-harness-probe.rs (1)

20-136: LGTM!

tests/harness_v1.rs (1)

206-249: LGTM!

src/bin/tmux_scenario.rs (1)

37-167: LGTM!

dev-docs/tmux-scenarios/v1/harness-timeout.json (1)

1-39: LGTM!

tests/harness_v1_fixtures.rs (1)

119-160: LGTM!

src/harness/v1/pty.rs (2)

416-442: 🩺 Stability & Availability

kill -- -<pgid> is valid on macOS, so this portability concern doesn’t hold.

			> Likely an incorrect or invalid review comment.

18-23: 🩺 Stability & Availability

No change needed here.

src/harness/v1/redact.rs (1)

1-121: LGTM!

src/harness/v1/report.rs (1)

1-199: LGTM!

src/harness/mod.rs (1)

32-32: LGTM!

dev-docs/tmux-scenarios/v1/harness-capture.json (1)

1-63: LGTM!

dev-docs/tmux-scenarios/v1/harness-containment.json (1)

1-33: LGTM!

dev-docs/tmux-scenarios/v1/harness-interpolation.json (1)

1-43: LGTM!

dev-docs/tmux-scenarios/v1/harness-limits.json (1)

1-9: LGTM!

dev-docs/tmux-scenarios/v1/harness-redaction.json (1)

1-25: LGTM!

dev-docs/tmux-scenarios/v1/harness-resize-restart.json (1)

1-40: LGTM!

dev-docs/tmux-scenarios/v1/harness-schema-all-ops.json (1)

1-84: LGTM!

Cargo.toml (1)

76-87: LGTM!

project-plans/issue380-plan.md (1)

1-135: LGTM!

src/harness/v1/contract.rs (2)

1-95: LGTM!

Also applies to: 122-249


113-121: 🎯 Functional Correctness

RelPath::derived is fine under the current gating RelPath::derived is only called from #[cfg(unix)] code paths in src/harness/v1, so the cfg(unix) constructor does not create a non-Unix build break.

			> Likely an incorrect or invalid review comment.
src/harness/v1/error.rs (1)

1-135: LGTM!

src/harness/v1/fields.rs (1)

1-158: LGTM!

src/harness/v1/json.rs (1)

1-349: LGTM!

src/harness/v1/json_tests.rs (1)

1-137: LGTM!

src/harness/v1/parse.rs (1)

1-268: LGTM!

src/harness/v1/parse_tests.rs (1)

1-308: LGTM!

src/harness/v1/validate.rs (1)

1-182: LGTM!

src/harness/v1/validate_tests.rs (1)

1-136: LGTM!

dev-docs/testing/tmux-harness.md (1)

343-484: LGTM!

src/harness/v1/keys.rs (1)

1-157: LGTM!

src/harness/v1/limits.rs (1)

1-46: LGTM!

src/harness/v1/interp.rs (1)

1-78: LGTM!

src/harness/v1/interp_tests.rs (1)

1-77: LGTM!

src/harness/v1/parse_step.rs (1)

1-128: LGTM!

Also applies to: 171-314, 333-345

dev-docs/standards/testing-and-quality.md (1)

41-50: LGTM!

src/harness/v1/env.rs (1)

1-116: LGTM!

src/harness/v1/workspace.rs (1)

1-361: LGTM! Rest of the containment/materialization logic (resolve/mkdir/write_file/remove/read_file/exists/identity tracking) is correctly implemented and matches the documented invariants.

src/harness/v1/workspace_tests.rs (1)

1-236: LGTM!

src/harness/v1/mod.rs (1)

10-30: 🎯 Functional Correctness

capture does not need a module-level #[cfg(unix)]
register and ensure_records_dirs are already Unix-gated; the rest of capture.rs is cross-platform.

			> Likely an incorrect or invalid review comment.

Comment thread src/harness/v1/parse_step.rs
Comment thread src/harness/v1/parse_step.rs
Comment thread src/harness/v1/semantic.rs
Comment thread src/harness/v1/workspace.rs

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/harness/v1/capture.rs`:
- Around line 109-152: In record_terminated_signals, re-check whether the
ordinal’s done record exists immediately before write_record_atomic updates the
start record. Skip the write when done has appeared, preserving the existing
signal and process checks while preventing stale start records from being marked
after normal completion.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: e91d09c0-2231-48d8-bc48-41d87a69abdc

📥 Commits

Reviewing files that changed from the base of the PR and between 349b591 and 1f20fb4.

📒 Files selected for processing (12)
  • src/bin/jefe-capture-shim.rs
  • src/bin/jefe-harness-probe.rs
  • src/bin/tmux_scenario.rs
  • src/harness/v1/capture.rs
  • src/harness/v1/capture_tests.rs
  • src/harness/v1/parse_tests.rs
  • src/harness/v1/pty.rs
  • src/harness/v1/redact.rs
  • src/harness/v1/runner.rs
  • src/harness/v1/semantic.rs
  • src/harness/v1/workspace.rs
  • tests/harness_v1.rs
🚧 Files skipped from review as they are similar to previous changes (11)
  • src/bin/jefe-capture-shim.rs
  • src/harness/v1/redact.rs
  • src/harness/v1/capture_tests.rs
  • tests/harness_v1.rs
  • src/bin/tmux_scenario.rs
  • src/harness/v1/workspace.rs
  • src/harness/v1/pty.rs
  • src/harness/v1/parse_tests.rs
  • src/harness/v1/semantic.rs
  • src/harness/v1/runner.rs
  • src/bin/jefe-harness-probe.rs
📜 Review details
⏰ Context from checks skipped due to timeout. (3)
  • GitHub Check: Native Windows (MSVC + psmux)
  • GitHub Check: Coverage gate
  • GitHub Check: OpenCodeReview
🧰 Additional context used
📓 Path-based instructions (2)
**/*.rs

⚙️ CodeRabbit configuration file

**/*.rs: Apply Jefe's Rust standards. Prefer explicit domain types; use Option for
absence and Result with typed errors for fallible operations. Require no
unwrap or expect in production paths and no unsafe code. Check Unix,
macOS, and native Windows behavior where process, path, terminal, or
runtime boundaries are changed.

Files:

  • src/harness/v1/capture.rs
src/**/*.rs

⚙️ CodeRabbit configuration file

src/**/*.rs: Preserve the documented ownership boundaries and unidirectional data
flow. Keep state transitions deterministic and side effects at runtime,
persistence, GitHub, or other boundary modules. Check cancellation,
stale-result, cleanup, and durability behavior for external work.

Files:

  • src/harness/v1/capture.rs
🧠 Learnings (2)
📚 Learning: 2026-04-04T21:05:37.792Z
Learnt from: acoliver
Repo: vybestack/llxprt-jefe PR: 36
File: src/github/mod.rs:537-542
Timestamp: 2026-04-04T21:05:37.792Z
Learning: In Rust, it’s acceptable for function parameters to be intentionally unused when their names start with an underscore (e.g., `_cursor: Option<&str>`). If the parameter name is underscore-prefixed, treat it as a deliberate forward-compatibility/API-consistency choice and do not raise an “unused parameter”/dead code warning during code review.

Applied to files:

  • src/harness/v1/capture.rs
📚 Learning: 2026-06-22T22:25:52.693Z
Learnt from: acoliver
Repo: vybestack/llxprt-jefe PR: 81
File: src/app_init.rs:11-13
Timestamp: 2026-06-22T22:25:52.693Z
Learning: In Rust, when you call a method that is defined on a trait (e.g., `spawn_session` from `jefe::runtime::RuntimeManager`) on a concrete type (e.g., `TmuxRuntimeManager`), ensure the defining trait is imported into scope (`use ...::RuntimeManager`) if it is not already in scope. Otherwise the call may fail with a “method not found” error because Rust’s method-call resolution requires the trait to be in scope.

Applied to files:

  • src/harness/v1/capture.rs
🔇 Additional comments (3)
src/harness/v1/capture.rs (3)

11-13: LGTM!

Also applies to: 51-66, 68-107


413-441: 🎯 Functional Correctness

No change needed for the let-chain syntax. Cargo.toml already uses edition 2024, and CI runs on the stable Rust toolchain, so if let ... && ... is valid here.

			> Likely an incorrect or invalid review comment.

154-175: 🩺 Stability & Availability

Unix-only capture path is intentionalsrc/harness/v1/contract.rs only models Platform::Macos and Platform::Linux, so this helper does not need a Windows fallback here.

			> Likely an incorrect or invalid review comment.

Comment thread src/harness/v1/capture.rs
@acoliver

Copy link
Copy Markdown
Contributor Author

OCR finding disposition

Reviewed all 45 OCR findings against the accepted schema-1 contract and source.

Fixed

  • Atomic capture-record publication; exact captured signal semantics; retained workspace path after materialization failure; capture-path/sidecar collision checks; secret-safe Redactor debug output; probe output error propagation; fixed-path stty invocation without a precheck; platform spelling; exact 1,024-step boundary coverage; and the inaccurate launch-order test comment.
  • The timeout integration test now proves the exact TERM signal and absence of a normal exit code.

Rejected as incorrect, contradicted by contract, or already covered

  • Lock-file cleanup: lock files are durable ordinal claims, not transient mutexes; removing them would reuse invocation ordinals.
  • Install-source restriction: install paths are explicit trusted CLI inputs, not scenario-controlled host lookup.
  • Reassigning HAR-E006: the fixed taxonomy reserves E006 for assertions and E005 for process/platform failures.
  • Environment root double slash: the runner supplies a canonical workspace root.
  • FileExpectation/HarnessError public API redesign and ObjectReader indexing/access refactors: no demonstrated acceptance defect; these would expand the public model after accepted behavior is proven.
  • Extra exit-code assertions: mapping is centrally covered.
  • JSON parser HashSet/preallocation/push-order changes: inputs are tightly bounded and limit-plus-one is rejected before launch; no material resource-bound violation exists.
  • Module-resolution findings: the cited imports compile and resolve correctly.
  • Rejecting empty assert-frame strings, removing the third cleanup phase, combining first-failure errors, ambient PATH lookup for kill, and narrowing expected signal values: each conflicts with the closed issue contract or hermeticity rules.
  • Unix gating and unsupported FreeBSD/OpenBSD findings: the modules are already gated and accepted scope is macOS/Linux.
  • Other style-only or speculative hardening findings were rejected under the issue scope ledger.

CodeRabbit follow-up

CodeRabbit independently found four valid parser/containment issues. They were fixed in 5861f8f, each thread received a source-grounded response, and all four threads were resolved. Its symlink-remove test suggestion was adapted to the actual safety contract: remove unlinks the workspace symlink and proves the outside victim is untouched.

@acoliver

Copy link
Copy Markdown
Contributor Author

Temporarily closing to refresh stale GitHub head metadata; branch and commits are unchanged.

@acoliver acoliver closed this Jul 23, 2026
@acoliver acoliver reopened this Jul 23, 2026
@acoliver

Copy link
Copy Markdown
Contributor Author

Refreshing stale GitHub head metadata after the final reviewed commit; branch history is unchanged.

@acoliver acoliver closed this Jul 23, 2026
@acoliver acoliver reopened this Jul 23, 2026
Comment thread src/bin/jefe-capture-shim.rs
Comment thread src/bin/jefe-capture-shim.rs
Comment thread src/bin/tmux_scenario.rs Outdated
Comment thread src/harness/v1/capture.rs
Comment thread src/harness/v1/capture_tests.rs Outdated
Comment thread tests/harness_v1.rs
Comment thread tests/harness_v1_fixtures.rs
Comment thread tests/harness_v1_fixtures.rs
Comment thread tests/harness_v1_fixtures.rs
Comment thread tests/harness_v1_fixtures.rs
@acoliver

Copy link
Copy Markdown
Contributor Author

Final OCR cycle disposition (reviewed against the closed issue contract and exact source):

Fixed in 96e646d:

  • report/stdout and capture-shim stdout/stderr write failures now propagate, flush, and produce a non-zero process outcome;
  • HarnessError fields are private with read-only accessors, preserving timeout/code invariants;
  • ObjectReader enforces its documented exact-once field-consumption invariant;
  • secret count is bounded before allocation/iteration in the typed parser, with parser-level coverage;
  • capture-loading-only failures always receive a failed load-captures StepResult;
  • Drop avoids waiting twice after the child status was cached;
  • duplicate capture paths receive an accurate diagnostic;
  • small safe diagnostics/API cleanups were applied (EnvVar import and Debug derives).

Rejected as contradicted by the contract/source:

  • lock files intentionally preserve cumulative start ordinals, including failed starts; removing them would reuse/overwrite invocation slots;
  • raw argv includes argv[0] by contract and existing exact capture evidence;
  • each harness run owns a unique workspace and one synchronous capture observer, so the proposed cross-run record locking addresses a nonexistent shared-workspace execution model;
  • CaptureExpectation.cwd is ByteString by the closed grammar, not RelativePath and is never used for filesystem access;
  • Base64 names the source content discriminant while storing validated decoded bytes;
  • negative numeric range violations are HAR-E002 under the inclusive-bound contract;
  • signal is an exact i32 expectation, not a platform signal command restricted to 1..31;
  • assert-frame arrays contain strings, not NonEmpty values;
  • fixed-path kill lookup is required by the hermetic no-ambient-PATH contract;
  • path normalization concerns are already rejected by RelativePath validation; directory foo plus file foo/bar is valid materialization, not a conflict;
  • JSON test module resolution, named production limits, required constructors, and final cleanup phase claims were factually incorrect.

Rejected/deferred as bounded optional work rather than correctness defects:

  • parser/redactor/render allocation optimizations remain bounded by strict limits and require no new dependency or data structure;
  • broader typed EnvName/Id public abstractions, interpolation API restructuring, executable preflight, platform expansion, escaped-process tracing, test cleanup logging, fixture serializer rewrites, and Cargo binary-discovery changes are outside CW-00 acceptance;
  • cosmetic test wording/message assertions and clone micro-optimizations do not justify expanding this final remediation cycle.

No further OCR review/remediation cycle will be started. Remaining suggestions are explicitly rejected or deferred under the bounded issue workflow.

@acoliver
acoliver merged commit 5a44d9e into main Jul 24, 2026
20 of 23 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

review-ready Opt in to CodeRabbit review after exact-head verification

Projects

None yet

Development

Successfully merging this pull request may close these issues.

CW-00: Deterministic real-process TUI harness

1 participant