feat: model finite cargo station handling and cancellation

docs/browser-qualification.mdadded+80-0

Changes to docs/browser-qualification.md

		@@ -0,0 +1,80 @@
	1	+# Browser qualification observations
	2	+
	3	+The rendered workspace and execution checks launch a fresh native Chrome process in the
	4	+existing fixture-owned process group. They retain the original launch arguments and the
	5	+400-read, 50 ms DevToolsActivePort discovery guard. No retry or browser flag bypass is added.
	6	+The full page/route/Worker scenarios must still pass. A successful native launcher fixture
	7	+does not qualify those scenarios or explain an intermittent Chrome startup failure.
	8	+
	9	+## Startup evidence
	10	+
	11	+`browser-launch.json` retains its exit/port counters and adds a `startup` observation. The
	12	+observer requests samples near launch, 1, 5, 10 and 15 seconds, then at discovery end. Samples
	13	+run asynchronously during discovery, with at most one actual task in flight and a 500 ms
	14	+cooperative cancellation budget. Cancellation stops further process/resource reads after
	15	+outstanding native calls settle. It never releases ownership of an unfinished task. A timeout
	16	+disables later Linux samples and hashing, closes captured descriptors after settlement and
	17	+emits a bounded pending-task notice. Finalization waits for that task; it cannot allow a page
	18	+visit behind it. An uninterruptible filesystem call can hold finalization until the existing
	19	+outer fixture guard fails and terminates its group. This is not a hard OS syscall deadline.
	20	+Actual start/completion epochs are retained; labels are requested milestones, not
	21	+promises that an event occurred at that exact time. A pre-page cleanup sample follows the
	22	+existing root termination/2 second wait. No process or resource sample is requested after a
	23	+page visit. Post-page stderr remains private.
	24	+
	25	+Each sample includes a native root PID existence probe. Linux adds selected `/proc` state:
	26	+parent/group/session, start/user/system ticks, thread count, RSS and kernel wait channel.
	27	+Names, argv, environment, stacks and memory contents are not exported. Main-task child
	28	+traversal and previously observed descendants are capped at 64 processes per sample; root
	29	+thread wait details are capped at 32. Start ticks flag observed PID reuse. Fork/exit/reparenting,
	30	+permissions and truncation can make this incomplete. It is not proof of whole-group cleanup.
	31	+The outer fixture owner separately terminates its isolated group before disposable removal.
	32	+
	33	+Expected discovery-file metadata, observer cgroup-v2 counters and system CPU/memory/IO pressure
	34	+help distinguish missing files, a live process and resource contention. Cgroup counters may
	35	+cover other runner work; system pressure covers other host workloads. Neither proves Chrome
	36	+causality. Unsupported platforms, missing files, permission errors and observation timeouts
	37	+are explicit outcomes. Numeric kernel fields are selected and bounded; raw status, cgroup
	38	+membership, thread names and arbitrary text are not retained.
	39	+
	40	+Startup samples pin at most four distinct actual Linux `/proc/PID/exe` file descriptors
	41	+without reading executable bytes. Only after discovery ends does it hash them under one
	42	+2 second cooperative hash budget, with a 512 MiB per-executable limit. Device/inode identity uses exact
	43	+integer strings. Byte count and file timestamps are checked before retaining a digest; all
	44	+pinned descriptors are then closed, with close errors reported. This identifies an observed
	45	+backing executable rather than assuming the configured launcher is Chrome. It neither warms
	46	+the binary before the attempt nor authenticates the code or its entire loaded graph.
	47	+
	48	+The browser version is retained only from a successful CDP version response and a closed
	49	+Chrome version format. If discovery fails, it stays null. Do not infer the failed binary's
	50	+version from another run without matching actual identity evidence. Opening descriptors,
	51	+reading process files and hashing are observation work and can affect scheduling; the
	52	+observed times and unavailable/timeout outcomes must accompany comparisons.
	53	+
	54	+## Native qualification
	55	+
	56	+```sh
	57	+bun test tests/unit/public-safety-browser-launch.test.ts tests/unit/public-safety-browser-launch-evidence.test.ts tests/unit/public-safety-browser-startup-process.test.ts
	58	+```
	59	+
	60	+One actual native fixture exits 23 before discovery. Another owns a live child until the
	61	+original cleanup request. The checks preserve all 400 failed probes, inspect actual PIDs,
	62	+verify parent/child shutdown and ensure argv/environment sentinels do not enter the report.
	63	+On Linux the live fixture also checks actual descendant/start/RSS data and the retained
	64	+executable hash against the independently read runtime binary. Optional `BROWSER_LAUNCH_EVIDENCE`
	65	+and `BROWSER_LAUNCH_LIVE_EVIDENCE` retain reports in new directories. CI publishes only the
	66	+allowlisted launch JSON and startup stderr, not scripts, credentials or private fixture files.
	67	+A held OS-adapter promise separately verifies that cancellation cannot overlap another sample,
	68	+finalize early or begin hashing while an operation remains unfinished. It does not qualify
	69	+Linux field acquisition; the actual native Linux fixture provides that evidence.
	70	+A Linux cancellation case also opens real executable descriptors and checks that they are
	71	+closed without a digest once the held native sample settles.
	72	+
	73	+Linux-only observations require Linux evidence; a macOS pass does not establish them.
	74	+[Issue #72](https://github.com/stacksjs/drone/issues/72) retains the original failed attempts and
	75	+passing controls. Its root cause and correction remain open until reproduced and verified.
	76	+These observations change evidence, not aircraft control, physical outputs or flight readiness.
	77	+
	78	+Field semantics follow the kernel's [proc reference](https://docs.kernel.org/filesystems/proc.html),
	79	+[cgroup-v2 reference](https://docs.kernel.org/admin-guide/cgroup-v2.html) and
	80	+[pressure reference](https://docs.kernel.org/accounting/psi.html).