fix(gc): live-worker teardown guard — no deinit under a running worker (ADR-0176)

Smell-audited: 3: ADR-0176 landed in the preceding commit (DA fork embedded); its error-unwind finding drove the deinit/env chokepoint guards on top of the exit barriers; joinAllNonDaemon renamed exitBarrier (the old name lied about its three duties); fpd ncpu gate removed with the canaries as the standing guard

root_set.live_workers counts spawner-increment → worker-final-decrement
across the whole thread lifetime (pre-register and post-unregister spans
included). thread.exitBarrier half 3 waits a bounded 50ms for epilogue
quiescence (the common case proceeds to a real graceful teardown), hard-
exiting daemon-style only for a genuinely running thunk (AD-056: cljw
exits immediately where the JVM waits). Runtime.deinit/Env.deinit guard
the error-unwind paths (broken pipe mid-print etc.) by skipping all
freeing when workers are live. CLJW_TORTURE_TEARDOWN_DELAY_MS widens the
window for the deterministic e2e canaries. Verified: pre-fix 6/32 glibc
aborts → post-fix 0/96 on the same 8x-parallel Linux harness; gc_torture
drain 0/150 regression-clean; Mac smoke green.

Author: chaploud

src/app/builder.zig

@@ -395,6 +395,9 @@ fn buildArtifact(io: std.Io, gpa: std.mem.Allocator, arena: std.mem.Allocator, o
     var ow = out.writer(io, &wbuf);
     try ow.interface.writeAll(artifact);
     try ow.interface.flush();
+    // Exit barrier (ADR-0176): build-time eval may have spawned workers;
+    // hard-exit if any is live rather than tear down under it (D-548(a)).
+    @import("../runtime/thread.zig").exitBarrier(&rt);
 }
 
 /// `cljw build <in.clj> -o <out>` (script mode): compile the source to a
@@ -485,6 +488,10 @@ pub fn tryRunEmbedded(io: std.Io, gpa: std.mem.Allocator, arena: std.mem.Allocat
         }
     }
 
+    // Exit barrier (ADR-0176): the embedded program is a full user program —
+    // join its non-daemon Threads and hard-exit if any worker is still live
+    // (the defers would free the heap under it, the D-548(a) teardown race).
+    @import("../runtime/thread.zig").exitBarrier(&rt);
     try stdout.flush();
     return true;
 }

src/app/cli.zig

@@ -73,6 +73,10 @@ pub fn dispatch(init: std.process.Init) !void {
     // safepoint mode above; both armed together by `gc_torture.arm()`.
     if (init.environ_map.get("CLJW_GC_TORTURE_ALLOC")) |raw|
         gc_torture.configureAlloc(std.fmt.parseInt(u32, raw, 10) catch 1);
+    // ADR-0176: teardown fault injection (widens the exit-teardown window so
+    // a live-worker-guard regression aborts deterministically; test-only).
+    if (init.environ_map.get("CLJW_TORTURE_TEARDOWN_DELAY_MS")) |raw|
+        gc_torture.configureTeardownDelay(std.fmt.parseInt(u32, raw, 10) catch 50);
 
     // Publish the process env for the runtime surface (`System/getenv`).
     // `init.environ_map` is already a `*Environ.Map` owned by `init`

src/app/nrepl.zig

@@ -101,6 +101,14 @@ pub fn run(
         const stream = server.accept(io) catch |err| {
             try stderr.print("nrepl: accept failed: {s}; exiting\n", .{@errorName(err)});
             try stderr.flush();
+            // Exit barrier (ADR-0176): a session may have left live workers
+            // (fire-and-forget futures/agents); hard-exit rather than let the
+            // defers free the heap under them (the D-548(a) teardown race).
+            // The port file is cleaned BEFORE the barrier — a hard exit skips
+            // the defer, and a stale `.nrepl-port` misleads CIDER discovery
+            // (the delete is idempotent, so the defer double-clean is fine).
+            cleanupNreplPortFile(io);
+            @import("../runtime/thread.zig").exitBarrier(&rt);
             return;
         };
         defer stream.close(io);

src/app/repl.zig

@@ -155,6 +155,10 @@ pub fn run(
     } else {
         try runPiped(io, &rt, &env, &macro_table, arena, stdout, stderr, &stars);
     }
+    // Exit barrier (ADR-0176): join non-daemon Threads + hard-exit if any
+    // worker (future/agent/Thread epilogue) is still live — the defers below
+    // would free the heap under it (the D-548(a) teardown race).
+    @import("../runtime/thread.zig").exitBarrier(&rt);
 }
 
 /// Interactive loop driven by the raw-mode line editor.

src/app/runner.zig

@@ -174,7 +174,7 @@ pub fn runSource(
     // ADR-0174 D6: main waits for live non-daemon `(Thread. f)` threads,
     // JVM-exact — a fire-and-forget `(.start (Thread. f))` completes f.
     // Daemon threads die with the process (skipped: never registered).
-    @import("../runtime/thread.zig").joinAllNonDaemon(&rt);
+    @import("../runtime/thread.zig").exitBarrier(&rt);
     try stdout.flush();
 }
 
@@ -227,6 +227,9 @@ pub fn runSourceCompare(
         try print.printValue(stdout, value);
         try stdout.writeByte('\n');
         try stdout.flush();
+        // Exit barrier (ADR-0176): compared source may have spawned workers;
+        // hard-exit if any is live rather than tear down under it (D-548(a)).
+        @import("../runtime/thread.zig").exitBarrier(&rt);
         return;
     }
 

src/runtime/agent.zig

@@ -349,7 +349,10 @@ fn enqueueDirect(rt: *Runtime, agent_val: Value, action: Action) !void {
     if (need_spawn) {
         // Keep the agent alive for the drainer even if the caller drops it.
         try rt.gc.pin(agent_val);
+        // Teardown guard (ADR-0176): account the drainer BEFORE spawn.
+        root_set.noteWorkerSpawned();
         var t = std.Thread.spawn(.{}, drainer, .{a}) catch |e| {
+            root_set.noteWorkerExited();
             io_default.lockMutex(&a.cell.mutex);
             a.cell.draining = false;
             io_default.unlockMutex(&a.cell.mutex);
@@ -364,6 +367,9 @@ fn enqueueDirect(rt: *Runtime, agent_val: Value, action: Action) !void {
 /// `ThreadGcContext` so a concurrent collect parks it at a safepoint and walks
 /// its operand-stack roots (the in-flight action), like `future.worker`.
 fn drainer(a: *Agent) void {
+    // FIRST defer → runs LAST: the teardown guard may only see 0 once every
+    // heap-touching cleanup below (state stores, unpin, unregister) completed.
+    defer root_set.noteWorkerExited();
     const agent_val = Value.encodeHeapPtr(.agent, a);
     // The tx_slot publishes this drainer's STM transaction (an action may run
     // a `dosync`) so it is GC-rooted during a collect (#4a' in-txn-map rooting).
@@ -575,7 +581,10 @@ pub fn restart(rt: *Runtime, agent_val: Value, new_state: Value, clear_actions:
 
     if (need_spawn) {
         try rt.gc.pin(agent_val);
+        // Teardown guard (ADR-0176): account the drainer BEFORE spawn.
+        root_set.noteWorkerSpawned();
         var t = std.Thread.spawn(.{}, drainer, .{a}) catch |e| {
+            root_set.noteWorkerExited();
             io_default.lockMutex(&a.cell.mutex);
             a.cell.draining = false;
             io_default.unlockMutex(&a.cell.mutex);

src/runtime/env.zig

@@ -424,6 +424,12 @@ pub const Env = struct {
     }
 
     pub fn deinit(self: *Env) void {
+        // Teardown guard (ADR-0176 / D-548(a)) — see Runtime.deinit's twin
+        // guard: on an error-unwind with a live worker (whose eval reads this
+        // Env's namespaces/Vars), freeing them here is the same corruption
+        // class. This defer runs BEFORE Runtime.deinit's (LIFO), so it does
+        // the bounded epilogue wait; a timeout = a running thunk → skip.
+        if (!@import("gc/root_set.zig").awaitQuiescentWorkers(50 * 1_000_000)) return;
         // Clear any process-global slot that points INTO this Env's
         // Vars before they are freed, so the slot can never dangle.
         // Currently the sole consumer is `runtime/error/context.zig`'s

src/runtime/future.zig

@@ -122,7 +122,11 @@ pub fn alloc(rt: *Runtime, env: *Env, thunk: Value, loc: SourceLocation) !Value
     const fut_val = Value.encodeHeapPtr(.future, f);
     // Pin so the worker's write target survives even when no deref'er holds it.
     try rt.gc.pin(fut_val);
+    // Teardown guard (ADR-0176): account the worker BEFORE spawn so the exit
+    // boundary sees it even while the thread is still starting up.
+    root_set.noteWorkerSpawned();
     var t = std.Thread.spawn(.{}, worker, .{f}) catch |e| {
+        root_set.noteWorkerExited();
         _ = rt.gc.unpin(fut_val);
         return e;
     };
@@ -134,6 +138,9 @@ pub fn alloc(rt: *Runtime, env: *Env, thunk: Value, loc: SourceLocation) !Value
 /// + wake deref'ers, unpin. Runs on a fresh thread with its own threadlocal GC
 /// slots (no conveyed dynamic bindings yet — binding conveyance is a follow-up).
 fn worker(f: *Future) void {
+    // FIRST defer → runs LAST: the teardown guard may only see 0 once every
+    // heap-touching cleanup below (result store, unpin, unregister) completed.
+    defer root_set.noteWorkerExited();
     const fut_val = Value.encodeHeapPtr(.future, f);
     // The tx_slot publishes this worker's STM transaction so a `dosync` in the
     // thunk is GC-rooted during a collect (#4a' in-txn-map rooting).

src/runtime/gc/gc_torture.zig

@@ -55,6 +55,19 @@ var pending_alloc_period: u32 = 0;
 pub var alloc_period: u32 = 0;
 threadlocal var alloc_counter: u32 = 0;
 
+/// Teardown fault injection (ADR-0176 / D-548(a) red test):
+/// `CLJW_TORTURE_TEARDOWN_DELAY_MS=N` makes `Runtime.deinit` sleep N ms AFTER
+/// its live-worker guard and BEFORE freeing — so a guard regression turns the
+/// teardown-vs-worker race back into a (near-)deterministic glibc abort under
+/// a fire-and-forget allocating thunk. Inert (0) unless the env var is set;
+/// read once at CLI startup, no arming stage (it fires at most once, at exit).
+pub var teardown_delay_ns: u64 = 0;
+
+/// Record the requested teardown delay (`CLJW_TORTURE_TEARDOWN_DELAY_MS`).
+pub fn configureTeardownDelay(ms: u32) void {
+    teardown_delay_ns = @as(u64, ms) * 1_000_000;
+}
+
 /// Record the requested torture period from the parsed `CLJW_GC_TORTURE`
 /// value. Does NOT activate — `arm()` does, post-bootstrap. `n == 0` is a
 /// no-op (mode stays off).

src/runtime/gc/root_set.zig

@@ -351,6 +351,59 @@ var registered_count: std.atomic.Value(u32) = .init(0);
 /// dormant D-244 #4 path, validated separately under user awareness.
 pub threadlocal var is_registered_worker: bool = false;
 
+/// Live worker-thread accounting for the PROCESS-EXIT teardown guard
+/// (D-548(a) / ADR-0176). The spawner increments BEFORE `Thread.spawn`
+/// (decrementing on spawn failure); the worker decrements as its very LAST
+/// action (its first-declared defer), AFTER every heap-touching cleanup
+/// (result store, `gc.unpin`, `unregisterThread`). Distinct from
+/// `registered_count`: this covers the whole thread lifetime including the
+/// pre-register and post-unregister spans. While nonzero, graceful Runtime
+/// teardown is FORBIDDEN — the app exit boundary hard-exits instead
+/// (`thread.exitBarrier`): a detached worker's thunk/epilogue reads the
+/// GC heap and mutates gpa-backed structures, and `rt.deinit` freeing them
+/// underneath produced the D-548(a) glibc heap-corruption aborts
+/// (`malloc_consolidate(): unaligned fastbin chunk detected`). The worker's
+/// seq_cst decrement pairs with the boundary's seq_cst read: count==0 proves
+/// every epilogue completed, so teardown is safe.
+var live_workers: std.atomic.Value(u32) = .init(0);
+
+/// Spawner-side: account a worker about to be spawned (call BEFORE
+/// `Thread.spawn`; call `noteWorkerExited` to roll back on spawn failure).
+pub fn noteWorkerSpawned() void {
+    _ = live_workers.fetchAdd(1, .seq_cst);
+}
+
+/// Worker-side final act (or spawner-side rollback): the thread's heap access
+/// is complete. Must be the worker fn's FIRST-declared defer.
+pub fn noteWorkerExited() void {
+    _ = live_workers.fetchSub(1, .seq_cst);
+}
+
+/// Snapshot for the exit-boundary teardown guard.
+pub fn liveWorkerCount() u32 {
+    return live_workers.load(.seq_cst);
+}
+
+/// Bounded wait for worker quiescence (ADR-0176). Returns true iff
+/// `live_workers` reached 0 within `max_wait_ns` — then graceful teardown is
+/// safe. Worker EPILOGUES (result store → unpin → unregister → final
+/// decrement) never block, so a completed thunk's worker quiesces in µs; a
+/// timeout therefore means a thunk is genuinely still RUNNING, and the caller
+/// must abandon teardown (hard exit / skip-freeing) instead. Polling sleep, no
+/// condvar: this runs at most twice per process (exit barrier + deinit guard),
+/// never on a hot path.
+pub fn awaitQuiescentWorkers(max_wait_ns: u64) bool {
+    if (liveWorkerCount() == 0) return true;
+    const io_def = @import("../concurrency/io_default.zig");
+    var waited: u64 = 0;
+    while (waited < max_wait_ns) {
+        io_def.sleep(1_000_000); // 1ms
+        waited += 1_000_000;
+        if (liveWorkerCount() == 0) return true;
+    }
+    return false;
+}
+
 /// Build the CALLING thread's standard worker context: all four TLS root
 /// slots plus the caller-supplied opaque `tx_slot` (opaque because root_set
 /// must not import lock_tx — see `ThreadGcContext.tx_slot`). Must run ON the