Beautiful, AI-native markdown IDE and LLM wiki
Windows PTY OS observation
Run the standalone collector with Node 24 from the Open Knowledge workspace:
node packages/desktop/tests/support/windows-os-state-cli.test-helper.ts --pid 12345 --parent-pid 6789 --budget-ms 5000
--pid accepts one to eight positive process IDs; repeat the flag for more than one target. One collection starts one PowerShell helper for all requested IDs. The top-level requestedPid and shell describe the first --pid only; read each ID's row in targets. --parent-pid is optional and only selects the console query: the helper lists conhost.exe and OpenConsole.exe processes whose parent is that ID. Without it no console query runs, and console is unavailable with reason console-identity-unavailable. --budget-ms must be positive and no greater than 5000. Invalid arguments return exit 2 and the fixed {"version":1,"status":"unavailable","reason":"invalid-shape"} record; the rejected value is not echoed. The collector queries only on Windows; elsewhere it returns reason unsupported-platform and exit 1. The entire stdout record is capped at 32 KiB.
The exit code and the top-level status answer different questions. Exit 0 means the machine section and every requested target's shell were captured; exit 1 means at least one of them was not. status is captured only when shell, machine and console are captured, no console candidate failed and worker is captured. The CLI owns no Worker, so its best possible record is exit 0 with "status":"partial"; that is the expected good standalone result. The top-level reason names a single cause: the collection-level reason when collection failed or ended early, otherwise the first unavailable section in the order shell, machine, console, failed console candidates, worker. Check each section's own status rather than reading the top-level reason as the only degraded section.
The test harness invokes this collector only after a scenario fails. A passing scenario, ordinary cleanup or budget refusal does no query. The collector's deadline is the earlier of its 5000 ms ceiling and the existing report allowance. It accepts no more than 64 KiB of raw helper stdout and stderr together. The result contains at most four console candidates and sixteen thread rows per process, with omitted counts. It validates each field and constructs a fresh record; raw output and errors are discarded.
Use requestedPid, targets, trace ID, attempt, and collection interval to correlate a record with a failure. A PID row describes collection time. Matching creation times across the two process samples support continuity during that short interval; they do not prove that the sampled process is the one that existed when the earlier silence began. The machine timestamps use the Node owner's monotonic clock. Process creation uses wall time, so subtract neither from the other.
The shell section gives creation time, two user/kernel CPU samples, thread count and bounded thread states. Its parentPid is the sampled process's own parent from a best-effort CIM lookup, unrelated to the --parent-pid input; only the first target gets one, and it is null when that lookup fails or has not finished. The two process samples are taken back to back, so their CPU difference is normally zero under every hypothesis and is not evidence for either; they support identity continuity only. Read the cumulative user/kernel CPU since creation together with the sampled thread states instead. Windows advances process CPU time in ticks of about 15.6 ms, so a small cumulative value is a count of ticks: 31.25 is two. A waiting thread's reason applies only to that sampled wait; other thread states have not-applicable. The machine section gives two aggregate CPU-time samples and logical CPU count, taken at the start and end of the whole collection. Compute its busy fraction as (ΔuserMs + ΔsystemMs) / (ΔuserMs + ΔsystemMs + ΔidleMs), and only when that denominator is positive. Keep irqMs separate rather than adding it to that total: the pinned Node 24.21.0 Windows implementation derives system time from kernel time minus idle time. Machine activity includes the query helper's own work; it is not a baseline measurement with the collector absent. Low cumulative shell CPU together with sampled wait threads can support investigation of a startup wait. High machine activity with shell threads in ready or running can support investigation of scheduling contention in the sampled interval. Neither pattern establishes what happened during the earlier silence or names a competing process.
console lists candidates under candidate-parent-relation; no candidate is claimed as the precise ConPTY host. candidateCount: 0 is an observed empty query result. When candidateCount is positive, unavailableCandidates retains fixed reasons and counts for candidates that could not be sampled, while omittedCandidates counts rows beyond the cap. An empty candidates list alone does not mean the query was empty. worker contains nodeThreadId and opportunistic Worker.cpuUsage() counters when that owned Worker object exists, has a positive threadId and replies with finite counters before collection ends. nodeThreadId is a Node worker ID, not a Windows thread ID. Missing worker response is not zero CPU. The standalone CLI has no owned Worker object.
Read existing native byte and forwarding counters beside the OS record. Each os-snapshot record carries transport, that attempt's counters read when the failure was detected and before collection started, or null when the attempt has no native snapshot; the failure snapshot is taken after collection, so a difference between the two shows bytes that arrived while the OS state was collected. Advancing counts locate progress at their named transport boundaries. CPU activity without advancing native reads is compatible with several behaviors, including computation without output. This collector does not hold a pipe read handle and cannot establish that bytes waited unread in the kernel.
Each section uses captured or an explicit unavailable reason. The reasons are deadline, no-budget, unsupported-platform, query-start-failed, query-exited, invalid-json, invalid-shape, output-limit, owner-loss, process-absent, access-unavailable, identity-changed, worker-request-deadline, worker-unavailable and console-identity-unavailable. console-identity-unavailable means no parent process ID was supplied, so no console query ran. For worker, worker-unavailable means there was no owned Worker object, its threadId was not positive so no request was sent (Node sets an exited Worker's threadId to -1), or the cpuUsage() request failed; worker-request-deadline means the request was sent but no reply arrived before collection ended, and invalid-shape means the reply carried counters that are not finite. process-absent means no process with that ID was running when its sample began, or the process exited while it was being sampled; it applies to targets rows and to failed console candidates alike. Every other reason is a failed observation. In the harness the top-level partial result preserves available sections and is not healthy state. The original harness failure remains the verdict when collection fails.
The helper writes three line frames on stdout: READY once its guard is armed, SHELL with the process samples taken before any CIM query, then RESULT with the full record including the CIM-derived parentPid and console. When collection ends at its deadline, on owner loss, or because the helper exited with a nonzero code after a valid SHELL frame, the record keeps those process samples with the ending reason, an unavailable console and a null parentPid; it reads partial when the first target was captured. A malformed or mismatched SHELL frame, or any unexpected line, discards them.
The collector directly owns one disposable PowerShell helper. Only deadline, output limit or owner loss can request termination through that original handle. The helper starts with a process-scoped -ExecutionPolicy Bypass; no persistent policy changes. helper.delivery=accepted records a request accepted by Node, not proof of exit. helper.exit records independently observed exit: observed-before-request and observed-after-request place an exit relative to a termination request, cooperative-owner-loss (exit 86) and cooperative-deadline (exit 87) are the helper ending itself on lost ownership or its own deadline without a request, and not-observed leaves it unknown. Missing helper PID or an observed exit prevents another termination call. The helper uses in-process runspaces and an ownership pipe. Once its guard is armed, EOF or its own deadline can end it without a descendant process. Uncatchable owner death before guard initialization has no proven cleanup guarantee.
The Windows spent-budget case owns a silent process and Worker and collects one OS observation. It prints the record as WINDOWS_OS_PROOF followed by its JSON, or, when that JSON exceeds 32 KiB, only WINDOWS_OS_PROOF_OVERSIZE bytes= with the byte count, and then validates the bounded record. It accepts every record not listed below, including the timing outcomes: reason deadline, reason query-start-failed with helper.reason deadline, and reason query-exited with helper.exit cooperative-deadline. It rejects a record of any status whose reason shows that the helper or its invocation failed: reason invalid-json, output-limit or unsupported-platform; reason query-start-failed when helper.reason is not deadline; reason query-exited when helper.exit is observed-before-request or cooperative-owner-loss; and, on an unavailable record, reason invalid-shape. A deadline record passes, so a green run does not show that the CIM query completed. The standalone CLI remains available through the command above. Local recording tests cover record acceptance and lifecycle behavior. No Windows case requires the helper's own exits 86 and 87 to occur: recorded tests cover how the collector classifies them, and a Windows record shows cooperative-owner-loss or cooperative-deadline only when the helper ends itself that way, unrequested, before collection settles.