Document CLI I/O timeout behavior

[rtbenfield]

Draft PR for visibility only. This contains the CLI I/O timeout spec and implementation plan; it is not intended to be merged.

@luanvdw tagging you for awareness.

Changes

• Timeout spec: Adds .agents/projects/cli-io-timeouts.spec.md, defining the intended CLI behavior for stalled Prisma-controlled I/O, including OPERATION_TIMEOUT, cancellation separation, generous defaults, and out-of-scope boundaries.
• Implementation plan: Adds .agents/projects/cli-io-timeouts.plan.md, sequencing the work through a shared timeout contract, Prisma API/SDK request boundaries, long-lived inactivity boundaries, and product-doc alignment.
• Command inventory: Adds pseudocode callstacks for each current command showing where request, wait, stream-inactivity, existing SDK, or no timeout should sit in the execution hierarchy.

Why

The spec chooses step-scoped and inactivity-scoped timeouts instead of a root command-wide timeout. That keeps long-running workflows such as app logs, app domain wait, auth login, deploys, and local app runs usable while still preventing Prisma-controlled API, SDK, polling, and stream boundaries from hanging forever.

[coderabbitai]

Important

Review skipped

Draft detected.

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: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 16abae42-d82a-401b-bedb-a995f13cfb51

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 docs/cli-io-timeouts-spec

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch docs/cli-io-timeouts-spec

---

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

[wmadden-electric]

Closing as stale: this documents the I/O timeout behaviour of the commander shell, which was deleted in #139 — the behaviours it describes (controller-level fetch timeouts, the old streaming paths) no longer exist as written. The engine has its own timeout story (for example the bounded identity enrichment in auth whoami), and documenting it belongs to the engine docs when the streaming transport lands. The research in the .agents notes remains readable from this PR's branch if anyone picks that up.