[Xuepoo]

Priority: P1 | Area: area:architecture | Labels: feat,P1,area:architecture | Milestone: 0.0.25 | RFC: W-132 / bitty-terminal/bitty#2249 | Task: CTX-0008

Supporting change for bitty-terminal/bitty#2249, which routes Core tool/plugin spawns through this crate's JobRegistry.

Why

Two host-integration gaps blocked a faithful Core routing:

1. Confined spawn. The supervisor builds and spawns its own Command, so Core could no longer attach the CTX-1151 Landlock EXECUTE ruleset (bitty-sandbox::confine_command_to_execs, a pre_exec hook). Removing the hook would be a security regression.
2. IPC type identity. This crate pinned bitty-ipc e9714e7; Core pins e6a2c0c, so the JobSpec::EnvPolicy type could not be constructed by Core.

Change

• Add the host-owned SpawnPreparer trait and JobRegistry::with_spawn_preparer. It runs exactly once per pipe job, after the closed-environment command is built and before Command::spawn; its returned guard stays alive across the spawn (the pre_exec descriptor contract), and a refusal fails the job closed as SpawnFailed with no process created. PTY jobs are excluded.
• Bump the bitty-ipc pin to e6a2c0c (the Core workspace revision), updating Cargo.lock.
• Document the seam in README.md and the crate docs; add tests/job_spawn_preparer.rs.

Verification

• cargo test --workspace: 237 tests passed.
• RUSTFLAGS="-D warnings" cargo clippy --workspace --all-targets: clean.
• cargo fmt --all -- --check: clean.
• just check: clean (prettier, markdownlint, metadata, hygiene, portable paths).

No PTY behavior changes, no new external crates, no plugin-visible surface. SpawnPreparer is host authority only.

[coderabbitai]

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 53 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: f42ee82c-3163-4017-84f5-50714b1a9988

📥 Commits

Reviewing files that changed from the base of the PR and between 1d088f2 and 57714f7.

⛔ Files ignored due to path filters: 1

• Cargo.lock is excluded by !**/*.lock

📒 Files selected for processing: 5

• Cargo.toml
• README.md
• src/lib.rs
• src/registry.rs
• tests/job_spawn_preparer.rs

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: dad4bfcf-ca49-4ea9-88af-d53392e0671d

📥 Commits

Reviewing files that changed from the base of the PR and between 1c51609 and 1d088f2.

⛔ Files ignored due to path filters: 1

• Cargo.lock is excluded by !**/*.lock

📒 Files selected for processing: 5

• Cargo.toml
• README.md
• src/lib.rs
• src/registry.rs
• tests/job_spawn_preparer.rs

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

📝 Walkthrough

The registry now supports a host-owned preparer for pipe-job commands. The preparer runs before process creation, and its guard remains alive through spawning. Preparation errors produce SpawnFailed. PTY jobs do not use the hook. The bitty-ipc Git revision also changes.

Changes: Pipe Job Spawn Preparation

Layer / File(s)	Summary
Preparer contract and registry configuration src/registry.rs, src/lib.rs	Adds the public SpawnPreparer contract and the JobRegistry::with_spawn_preparer builder. The registry stores the shared preparer and re-exports the contract.
Pipe startup preparation src/registry.rs	Passes the configured preparer through supervisor and backend startup. Pipe startup calls it before spawning and retains its guard through the spawn call. PTY startup does not receive the preparer.
Preparation tests and lifecycle documentation tests/job_spawn_preparer.rs, README.md	Tests successful preparation, refusal before process creation, and startup without a preparer. Documents the hook lifecycle and PTY exclusion.

IPC Dependency Revision

Layer / File(s)	Summary
Dependency revision Cargo.toml	Updates the bitty-ipc Git revision from e9714e7 to aa7259d.

Priority: ⚪ Pending latest changes

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant JobRegistry
  participant Supervisor
  participant PipeBackend
  participant SpawnPreparer
  participant Command
  JobRegistry->>Supervisor: provide configured preparer
  Supervisor->>PipeBackend: pass preparer to startup
  PipeBackend->>SpawnPreparer: prepare job command
  SpawnPreparer-->>PipeBackend: return guard or preparation error
  PipeBackend->>Command: spawn with prepared command

Loading

Merge Risk: ⚪ Minimal · up to 1d088

No confirmed issue blocks merging after normal checks.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 47.06% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 17 functions across 3 files. (2 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly identifies both primary changes: the host spawn preparer hook and the Core IPC revision pin.
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 47.06% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 17 functions across 3 files. (2 skipped: 2 unsupported.)

Resolution

Write docstrings for the functions missing them to satisfy the coverage threshold.

✨ Finishing Touches: 💡 1

📝 Generate docstrings: 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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