docs(vz): record stale socket drill evidence

[rmusser01]

Summary

• add a 2026-07-03 prepared-host stale-socket drill evidence packet
• record controlled inactive socket recovery, helper start/status/protocol checks, explicit stop cleanup, artifact pointers, and expected skips
• update the residual-gap table so stale-socket evidence is recorded while remaining manual-only

Verification

• /Users/macbook-dev/Documents/GitHub/tldw_server2/.venv/bin/python -m pytest tldw_Server_API/tests/Infrastructure/test_vz_linux_host_gated_workflow.py -q
• git diff --check
• Bandit skipped: committed scope is Markdown/Backlog only

Human-authored Change summary still required before merge per repo policy.

---

Summary by cubic

Add 2026-07-03 prepared-host stale-socket drill evidence for vz_linux, covering safe inactive socket recovery, helper start/status/protocol checks, explicit stop cleanup, and artifact pointers. Updates the prepared-host evidence log and residual-gap table and adds a backlog entry, fulfilling TASK-12136 with no code or CI trigger changes.

^{Written for commit 05bbe6b. Summary will update on new commits.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: fd523ebe-7703-4728-8295-2dd987590a57

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/vz-stale-socket-evidence

---

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

[gemini-code-assist]

Code Review

This pull request documents the stale-socket drill evidence on a prepared macOS host, updating the evidence tracker and adding a completed backlog task file. The feedback suggests renaming the new backlog file to avoid spaces and mixed casing, and replacing absolute local user paths with relative paths or placeholders to prevent leaking local environment details and improve reproducibility.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

The filename task-12136 - Record-VZ-stale-socket-prepared-host-evidence.md contains spaces and mixed casing. Filenames with spaces can cause issues in command-line scripts, shell utilities, and markdown link references (which require URL encoding like %20). It is highly recommended to rename this file to use a consistent kebab-case naming convention without spaces, such as task-12136-record-vz-stale-socket-prepared-host-evidence.md.

[gemini-code-assist]

Including absolute local user paths (such as /Users/macbook-dev/...) in committed backlog files leaks local environment details and is not reproducible for other team members. Consider using relative paths or placeholders (e.g., <repo-root>) instead.

Suggested change

	Worktree: /Users/macbook-dev/Documents/GitHub/tldw_server2/.worktrees/vz-stale-socket-evidence
	Branch: codex/vz-stale-socket-evidence
	Base: origin/dev c20013ecce7e3384ec5faa860434d6bdd76d5407
	Runtime artifact root: /private/tmp/tldw-vz-stale-socket-stale-socket-20260703-165828
	Worktree: <repo-root>/.worktrees/vz-stale-socket-evidence\nBranch: codex/vz-stale-socket-evidence\nBase: origin/dev c20013ecce7e3384ec5faa860434d6bdd76d5407\nRuntime artifact root: /private/tmp/tldw-vz-stale-socket-stale-socket-20260703-165828

[gemini-code-assist]

Avoid using absolute local user paths in the verification commands. Using relative paths (e.g., .venv/bin/python or <repo-root>/.venv/bin/python) is cleaner and more reproducible.

Suggested change

	Verification: /Users/macbook-dev/Documents/GitHub/tldw_server2/.venv/bin/python -m pytest tldw_Server_API/tests/Infrastructure/test_vz_linux_host_gated_workflow.py -q passed with 23 tests. git diff --check passed. Bandit skipped because the reviewable changes are Markdown/Backlog only; helper build artifacts are untracked evidence setup, not committed source.
	Verification: .venv/bin/python -m pytest tldw_Server_API/tests/Infrastructure/test_vz_linux_host_gated_workflow.py -q passed with 23 tests. git diff --check passed. Bandit skipped because the reviewable changes are Markdown/Backlog only; helper build artifacts are untracked evidence setup, not committed source.

[qodo-code-review]

PR Summary by Qodo

docs(vz): record prepared-host stale socket drill evidence (2026-07-03)

📝 Documentation 🕐 10-20 Minutes

AI Description

• Add a prepared-host stale-socket drill evidence packet with commands, results, and artifacts.
• Document sandbox-related failure mode vs successful non-sandbox run, plus explicit cleanup
 behavior.
• Update residual-gap tracking to mark stale-socket handling as evidenced but still manual-only.

Diagram

graph TD
  A(["Local operator"]) --> B["vz-helperctl.py stale-socket-drill"] --> C["macos-vz-helper binary"] --> D[("Runtime artifacts")] --> E["Prepared-host evidence doc"] --> F["Backlog task TASK-12136"]

  subgraph Legend
    direction LR
    _actor(["Actor"]) ~~~ _proc["Process/Doc"] ~~~ _fs[("Filesystem/artifacts")]
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Automate stale-socket drill in CI (self-hosted macOS runner)

• ➕ Continuous regression detection without requiring manual operator runs
• ➕ Standardizes evidence capture and retention
• ➖ Requires trusted prepared-host/self-hosted runner access and careful isolation
• ➖ Potentially disruptive/destructive behavior is harder to safely schedule
• ➖ Increases operational burden (runner maintenance, signing, entitlements)

2. Store evidence as structured JSON + summary generator

• ➕ More machine-searchable and diff-friendly than long-form prose
• ➕ Enables future automation (dashboards, trend checks) without changing the drill
• ➖ Adds tooling and format versioning overhead
• ➖ May reduce human readability for ad-hoc audits unless paired with rendering

Recommendation: Keep the current manual-only evidence approach: it matches the stated safety constraints (prepared-host, potentially disruptive socket/process lifecycle checks) while still capturing repeatable commands, artifact pointers, and explicit cleanup outcomes. Consider CI automation only if/when a hardened self-hosted runner program exists; otherwise, the operational risk outweighs the value.

Files changed (2) +141 / -1

Documentation (2) +141 / -1

vz-linux-prepared-host-evidence.mdAdd 2026-07-03 stale-socket drill packet and update residual-gap row +81/-1

Add 2026-07-03 stale-socket drill packet and update residual-gap row

• Adds a new prepared-host evidence entry documenting a manual stale-socket lifecycle drill (commands, paths, results, cleanup, artifacts, and expected skips). Updates the residual-gap table to reflect that stale-socket handling now has recorded evidence while remaining manual-only.

Docs/Sandbox/vz-linux-prepared-host-evidence.md

task-12136 - Record-VZ-stale-socket-prepared-host-evidence.mdCreate TASK-12136 backlog record for stale-socket evidence capture +60/-0

Create TASK-12136 backlog record for stale-socket evidence capture

• Introduces a completed backlog task with acceptance criteria, run notes, verification commands, and a final summary linking the prepared-host evidence entry and related references.

backlog/tasks/task-12136 - Record-VZ-stale-socket-prepared-host-evidence.md

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Great, no issues found!

Qodo reviewed your code and found no material issues that require review