docs(comments): rewrite comments across all crates to the guidelines

Sweep every first-party crate source (1956 .rs files) to the project comment
guidelines: delete redundant restatements, decorative banners, change
narration, and end-of-line comments; keep and tighten the crucial ones
(invariants, bug rationale, SAFETY blocks, ported-source attribution).

No functional code changed. Every edit is proven comment-only against the
prior tree by a comment-stripping lexer (string/char/raw-string aware) plus a
separate doctest-fence check. Where removing a comment made rustfmt or clippy
want to re-lay-out adjacent code, the minimal triggering comment is restored so
code tokens stay byte-identical.

Gates green: cargo fmt --all --check (0 diffs), cargo check and cargo clippy
--workspace --all-targets (0 warnings).

Adds scripts/check_codegen_comment_guidelines.py — the enforcement gate for
these guidelines (flags banners, end-of-line comments, change narration, and
commented-out code).

crates/codegen/ptyctl-cli/src/cli.rs

@@ -172,7 +172,7 @@ pub enum Commands {
         #[arg(long, group = "condition")]
         gone: Option<String>,
 
-        /// Wait until the screen has been unchanged for this many milliseconds
+        /// Wait until the screen has been `unchanged` for this many milliseconds
         #[arg(long, value_name = "MS", group = "condition")]
         stable_ms: Option<u64>,
 

crates/codegen/ptyctl-cli/src/commands/client.rs

@@ -3,7 +3,6 @@
 use anyhow::{Context, Result};
 use reqwest::Client;
 
-/// Send keystrokes to a session.
 pub async fn send(url: &str, keys: &str, enter: bool) -> Result<()> {
     let mut keys = keys.to_string();
     if enter {
@@ -25,7 +24,6 @@ pub async fn send(url: &str, keys: &str, enter: bool) -> Result<()> {
     Ok(())
 }
 
-/// Query screen content.
 pub async fn screen(
     url: &str,
     rows: Option<&str>,
@@ -64,7 +62,6 @@ pub async fn screen(
     if format == "html" || format == "styled" {
         println!("{body}");
     } else {
-        // Parse as JSON and print lines.
         let output: serde_json::Value = serde_json::from_str(&body)?;
         if let Some(lines) = output.get("lines").and_then(|l| l.as_array()) {
             for (i, line) in lines.iter().enumerate() {
@@ -81,7 +78,6 @@ pub async fn screen(
     Ok(())
 }
 
-/// Query cursor position.
 pub async fn cursor(url: &str) -> Result<()> {
     let client = Client::new();
     let resp = client
@@ -94,7 +90,6 @@ pub async fn cursor(url: &str) -> Result<()> {
     Ok(())
 }
 
-/// Query session status.
 pub async fn status(url: &str) -> Result<()> {
     let client = Client::new();
     let resp = client
@@ -107,7 +102,6 @@ pub async fn status(url: &str) -> Result<()> {
     Ok(())
 }
 
-/// Resize terminal.
 pub async fn resize(url: &str, size: &str) -> Result<()> {
     let (cols, rows) = size
         .split_once('x')
@@ -178,7 +172,6 @@ pub async fn wait(
         .unwrap_or(false))
 }
 
-/// Stop a session.
 pub async fn stop(url: &str) -> Result<()> {
     let client = Client::new();
     let resp = client

crates/codegen/ptyctl-cli/src/commands/run.rs

@@ -13,7 +13,6 @@ use ptyctl::session::{PtySession, SessionConfig};
 
 use crate::registry;
 
-/// Run the `ptyctl run` command.
 #[allow(clippy::too_many_arguments)]
 pub async fn run(
     command: Vec<String>,
@@ -40,7 +39,6 @@ pub async fn run(
         );
     }
 
-    // Parse env vars.
     let mut env = HashMap::new();
     for var in &env_vars {
         if let Some((k, v)) = var.split_once('=') {
@@ -65,14 +63,11 @@ pub async fn run(
         linger,
     };
 
-    // Start the session.
     let session = PtySession::start(config).await?;
     let pid = session.status_basic().1;
 
-    // Build the HTTP server.
     let router = server::build_router(session);
 
-    // Bind to the requested port.
     let addr = SocketAddr::from(([127, 0, 0, 1], port));
     let listener = TcpListener::bind(addr)
         .await
@@ -80,7 +75,6 @@ pub async fn run(
     let actual_addr = listener.local_addr()?;
     let actual_port = actual_addr.port();
 
-    // Register named session.
     if let Some(ref session_name) = name {
         let info = registry::SessionInfo {
             port: actual_port,
@@ -102,7 +96,6 @@ pub async fn run(
         println!("{actual_port}");
     }
 
-    // Serve until shutdown.
     let shutdown_result = axum::serve(listener, router)
         .await
         .context("HTTP server error");

crates/codegen/ptyctl-cli/src/registry.rs

@@ -113,7 +113,8 @@ pub fn list_sessions() -> Result<Vec<(String, SessionInfo)>> {
                 .unwrap_or("")
                 .to_string();
             if name.starts_with('.') {
-                continue; // skip temp files
+                // skip temp files
+                continue;
             }
             if let Ok(json) = fs::read_to_string(&path)
                 && let Ok(info) = serde_json::from_str::<SessionInfo>(&json)