Feature plan: Step 1 · Step 2 · Step 3 · Step 4

Debug mode: enabled

All five stages implemented and verified on feat/startup-dependency-recovery. See acceptance evidence for the outcome matrix, exact environments and reproduction commands.

Stage 1 - Actionable recovery guidance

• Changes: shared Ubuntu 22.04/PHP 8.1 and 24.04/PHP 8.3 mapping; verified package provenance and CLI ownership for extension commands; installed/disabled modules receive CLI-specific phpenmod/configuration guidance. Unverified sources, custom runtimes and PATH problems remain manual. Direct PHP probes no longer infer package installation merely from absent capabilities.

• Verification: shell dependency and installer suites; PHP syntax; real-runtime capability/color/NO_COLOR and 20 HTTP read/write/shutdown cases passed. Disposable Ubuntu 22.04 manual CLI install, missing-extension recipe, readiness, disabled mbstring diagnosis and manual enabling all passed. Transcripts: /home/wsl/.cache/startup-dependency-recovery-planning/logs/.

• Notes: corrected the older help fixture to use the canonical Railspike command; deprecated FDP intentionally writes a warning. Host packages unchanged. Actual automatic Jammy installation remains Stage 2.

Stage 2 - Confirmed installation on both releases

• Changes: coordinator uses the shared release/CLI mapping for ownership, candidate sources, package selection, transaction allowlist and reassessment. Both explicit aliases retain exact-yes confirmation; help lists both supported releases. Cross-release APT sources are rejected.

• Verification: installer fixtures and changed-transaction confirmation passed. Real Ubuntu Base 22.04.5 and 24.04.3 chroots passed missing PHP/Git installation, separate optional selection/install, ready no-op, custom/configuration refusal, network/lock/partial failures, interruption cleanup, password-sudo install/interruption, and installed-runtime HTTP read/write/shutdown tests. Disabled installed modules refused reinstall and showed phpenmod guidance on both releases.

• Notes: concurrent chroots share the host PID view; fixed child-process assertions to scope by root filesystem. Runs resumed at the interrupted test boundary after that harness correction. Retained transcripts: /home/wsl/.cache/startup-dependency-recovery-install-{22,24}-b/logs/; final clean-image acceptance remains Stage 5. No host package changes.

Stage 3 - Recover and continue the original startup

• Changes: validate startup options before recovery; terminal-only eligible recovery with Enter/Y/y consent and separate default-off intl selection; authenticate after review; require successful package operation and fresh readiness; resume once with original arguments/caller. Restore caller signal handlers on every installer return before launcher takeover.

• Verification: all shell/installer/changed-batch fixtures and runtime capability/color/20 HTTP lifecycle regressions passed. On both disposable releases, missing PHP and missing SQLite/mbstring recovered through ordinary startup as root and password-sudo users. Tests assert one launcher, caller UID, requested port and spaced log path, thread/reply HTTP writes/reads and clean SIGTERM shutdown. Enter, Y and y exercised; intl remained absent.

• Notes: new durable harness tests/startup_dependency_recovery_integration_test.py; logs in /home/wsl/.cache/startup-recovery-{22,24}-stage3/. Initial harness assertion incorrectly rejected existing server cursor controls under NO_COLOR; corrected to test recovery output and plain logs, reset package states and reran all four journeys per release. No application-side failure was hidden by the correction. Final fresh-image rerun remains Stage 5.

Stage 4 - Refusal and failure gates

• Changes: fixed Bash read cancellation (setting a flag alone leaves read waiting); pre-execution handlers return immediately, and changed-transaction prompts also abort. Preserve active-package cleanup while handling the launch/signal window. Added real startup failure harness and startup changed-batch/INT/TERM fixtures. Reports identify OS/release independently of package mapping.

• Verification: both chroots passed n/N/invalid/EOF and pre-execution INT/TERM; malformed options; redirected input/output separately and together; custom/disabled runtime; absent/denied/cancelled sudo; package/network/lock/partial failure; active-install INT/TERM and no surviving package children; remaining PHP restriction after successful install; optional-only startup without prompting. Pre-execution application/package/metadata snapshots stayed identical; failed recoveries never opened the requested listener or log. Changed-transaction accept/decline/cancellation and active-process reassessment fixtures passed.

• Notes: corrected a process assertion that matched its own shell command. Retained failed attempts and resumed package gates under /home/wsl/.cache/startup-recovery-{22,24}-stage3/failure-logs*; final acceptance reruns the complete corrected harness. System configuration is not rewritten by recovery; no rollback promised.

Stage 5 - Complete outcome acceptance and documentation

• Changes: README/CLI/help explain both release mappings, terminal Y/n recovery, password-sudo timing, automatic continuation, explicit/manual retry and unsupported cases. Updated the remediation checklist with evidence-backed closure and retained broader open checks; preserved historical failure reports. Added durable manual-command acceptance and machine-readable evidence with source/transcript hashes.

• Verification: fresh-image startup acceptance passed both missing states as root and password-sudo on both releases; final-source password-sudo missing-runtime/extensions reruns passed. Both full explicit-installer matrices and complete corrected startup failure matrices passed. Actual displayed manual commands and disabled-module enabling restored HTTP thread/reply reads/writes and shutdown on each release. Final shell/confirmation/40 prompt-boundary cancellation tests, PHP syntax and real-runtime capability/color/20 HTTP lifecycle regressions passed. Documentation links and diff whitespace checked.

• Notes: final acceptance caught a signal arriving between prompt output and read; cancellation now exits the launcher before any package operation, with separate post-refresh interruption reporting. Added ownership-verification handling that refuses verification-command errors and modified package-owned CLI binaries, verified in both disposable targets. Final guidance audit corrected installed-Git/PATH advice and exposed the reviewed installer in verified extension guidance. Successful returns still restore caller signal handlers. No host installation, schema, deployment or service changes. Chroot evidence does not certify WSL terminal/PATH or other platforms.

Completion contract audit

• Ordinary ./v3 start reaches the approved reviewed recovery and usable-server outcome on both named release/runtime mappings; preserves caller, original address/logging and optional-off behavior.

• Decline, EOF, invalid input, signals, denied/cancelled privilege, failed transactions and remaining required restrictions block startup. Package success and readiness are separate; no automatic rollback/configuration repair/runtime replacement.

• Manual fallback commands were executed, not merely matched as text. Ordinary checks/redirected startup remain read-only; explicit aliases retain exact-yes confirmation.

• Five stage commits plus the initial approved-plans commit preserve the required cadence. Earlier unrelated staged documents remain outside this feature's commits.