Add chapter: subprocesses and external streams; cover Ox 1.0.6 additions

[adamw]

What

Adds guidance for the case structured concurrency is easiest to get subtly wrong: driving a long-lived subprocess (or socket / SSE) whose output is read line by line — and covers the Ox 1.0.6 additions across the skill.

• New chapter 170-subprocesses-and-external-streams.md:
  • own the work with a supervised scope; the reader's return value is the result (fork{…}.join()), not a cross-thread AtomicReference/CAS;
  • never return a live object that owns running forks to be driven later;
  • teardown: a classic java.io stream read (subprocess pipe, file, stdin) ignores interruption, and Ox releases scope-managed resources only after joining forks — so destroy the subprocess in the scope body's finally, before the join. Blocking socket reads are the exception: on Ox's virtual-thread forks they are interruptible since Java 21 (destructively — the interrupt closes the socket);
  • kill the whole process tree (a launcher's forked child inherits the pipe fds; an orphan keeps the pipe open so the reader never EOFs);
  • abandonOnInterruptReads / abandonOnInterrupt (Ox ≥ 1.0.6) for reads that closing can't unblock (stdin, FileInputStream) and per-read cancellation — the read is delegated to a detached virtual thread so the fork waits interruptibly. Body-finally destroy stays the primary subprocess teardown, since the wrapper doesn't terminate the child;
  • drain/inherit stderr so an unread pipe can't stall the child.
• Chapter 150 (150-shared-state-across-threads.md): new CPU-intensive work section — virtual threads are never preempted, so long CPU-bound work runs via computeIntensive (platform-thread pool, structured by the blocking caller) and instrumentable loops call cede(); scope context (forks, ForkLocals, MDC/OTel) deliberately does not propagate into the compute pool. Rows added to both pattern-selection tables.
• Chapter 100 (100-resource-management.md): new resourceScope section — scoped cleanup without claiming a concurrency capability (Ox's Using.Manager analogue, compile-time-guarded against lexically visible concurrency scopes), and using ResourceScope as the narrower capability for registration-only methods.
• SKILL.md: always-loaded decision triggers — the ownership/teardown rules above, a Performance bullet for CPU-bound starvation (computeIntensive/cede), the ResourceScope refinement of the factories rule — plus updated index entries.

Why

The detailed how lives in the chapters; the decision triggers live in the always-loaded SKILL.md so the agent picks the right ownership and teardown shape before writing code — the failure modes here (shutdown-time deadlock, virtual-thread starvation) don't show up until teardown or load.

Updated for Ox 1.0.6, which addresses part of the original concerns: abandonOnInterruptReads/abandonOnInterrupt (softwaremill/ox#479) make waiting on uninterruptible operations cancellable, and the interruptions docs now officially catalogue which JVM operations are (un)interruptible and state that scope-managed resources (useInScope/releaseAfterScope) are released only after all forks complete. The chapter is grounded in that documented behavior (rather than paraphrased scope internals), and the earlier claim that blocking socket reads ignore interruption was corrected — on virtual threads they are destructively interruptible since Java 21. The remaining 1.0.6 additions with pattern-level impact — computeIntensive/cede() (softwaremill/ox#483, softwaremill/ox#481) and resourceScope (softwaremill/ox#480) — are covered in chapters 150 and 100; the release's finalizer-freeze and compute-pool tuning details were deliberately left out as non-pattern material.

🤖 Generated with Claude Code