Skip to content

Resource-lifetime conventions: dir-handle closure, native memory collector, reliability gates #17033

Closed

Description

@espetro

Context

While investigating the memory reports in #12728, #15241, #16211, #16905 and #9530, we found the same meta-pattern: the repo already ships the right primitives (process-tree-termination, run-process, bounded-map, process-table-snapshot, ratchet scripts, custom oxlint plugins), but adoption is partial and there are no resource-lifetime guardrails, so the same bug classes get re-fixed point by point.

Two concrete examples:

  1. Directory handles. grok-session-paths.ts correctly closes its opendir handle in finally, but ~11 production call sites exist and several rely on implicit close. Two actually leak today:

  2. Windows process queries. AGENTS.md says to read the process table through windows-process-table.ts, never fork powershell.exe, but the memory resource collector still spawns powershell.exe Get-CimInstance every ~2s ([Bug]: Windows relocated terminal daemon spawns powershell.exe every ~2s (native process-tree addon missing from daemon host) #16905) because perf(windows): read the process table natively instead of forking PowerShell #15749 migrated only the identity probes.

Proposal

  1. Shared scoped-opendir helper (src/shared/fs-opendir-scope.ts): a withDir(path, fn, { signal }) callback helper implemented internally with await using / AsyncDisposable (TS 7 supports this natively), plus migration of the leaking/implicit-close sites. Follow-up: an oxlint plugin (no-raw-opendir) with an allowlist so new raw opendir sites fail lint.
  2. Native memory collector (fixes the [Bug]: Windows relocated terminal daemon spawns powershell.exe every ~2s (native process-tree addon missing from daemon host) #16905 remainder): migrate windows-process-resource-collector.ts to readWindowsProcessTable() and delete the PowerShell/typeperf spawn path. Known gap worth recording: the native row type does not expose commit/pagefile bytes, so privateMemory stays absent on Windows; extending the native addon with GetProcessMemoryInfo would be a follow-up.
  3. Reliability gates: register a fs-resource-lifetime.dir-handle-closure gate in config/reliability-gates.jsonc (existing schema: protection partial -> active when the migration lands), with the same pattern later for child-process-tree-termination and bounded retention. This is what turns point fixes into class fixes.

Questions

Happy to split/adjust scope however you prefer. Design notes and measurement plans are written up and can be pasted into this issue or the PRs.

Activity

  1. AmethystLiang commented on Aug 28, 2026

    @AmethystLiang
    Contributor

    thanks for reporting. looking into it

  2. AmethystLiang commented on Aug 28, 2026

    @AmethystLiang
    Contributor

    thanks for reporting. looking into it

  3. nwparker commented on Sep 3, 2026

    @nwparker
    Contributor

    I took over the two PRs from this issue (#17035, #17034) and closed both. Correcting the record here so nobody re-derives the same conclusion.

    Proposal 1 (scoped-opendir helper) is not needed. The premise — that for await over an fs.Dir leaks the handle on break/throw/early exit — is wrong. for await calls the iterator's return(), and Dir's return() closes. Verified on Node 24, including transitively through an async generator with a consumer break, and through a nested recursive frame throwing while the parent is suspended mid-loop:

    BREAK / THROW / FULL / GEN-BREAK  ->  all ERR_DIR_CLOSED
    nested-abort: parent AND child    ->  both ERR_DIR_CLOSED
    

    So the two sites named in this issue:

    I swept every opendir/opendirSync in src/. All safe: either a for await, or a manual .read() loop already in try/finally (skill-package-identity.ts:215-227). There is no ~11-site adoption gap. A no-raw-opendir lint rule would be enforcing a non-rule.

    Also worth knowing: Dir is already natively AsyncDisposable (@types/node/fs.d.ts:310), and config/tsconfig.node.json resolves to target: esnext — so await using dir = await opendir(p) works today without any helper, if a future site ever needs one.

    Proposal 3 (the gate) followed from proposal 1, so it goes with it.

    Proposal 2 (Windows process queries) is untouched by any of this and still stands on its own — windows-process-resource-collector.ts still spawning powershell.exe Get-CimInstance is a separate, real issue. Worth splitting into its own ticket rather than leaving it buried under a refuted premise.

    Two genuine findings this turned up, both worth their own issues:

    1. config/scripts/check-reliability-gates.mjs only shape-validates evidence. assertionRefs are checked to be non-empty strings whose file is in testFiles (:228-241); the file is never opened. evidenceRuns need one result: "passed" entry (:211-226) but are never executed. A gate asserting coverage that does not exist passes cleanly — which is exactly how chore(gates): register dir-handle-closure reliability gate #17034 got a green check. Worth deciding whether that's acceptable by design (the refs are prose, not literal it() names, so exact matching won't work) or whether it needs a real linkage.

    2. The GC warning in [Bug]: Remote SSH workspace sync unavailable — long-running relay degrades (Handshake OK, no data stream, 2–4 s close loop); manual reconnect redeploys relay and heals #12895's relay log is real and still unexplained. Given the above it is not coming from these opendir sites, so it's worth re-deriving from the relay process itself. That's the thread actually worth pulling.

    @espetro — thanks for the writeup; the meta-pattern framing (point fixes vs. class fixes) is the right instinct even though this particular class turned out to be already-safe. Detailed refutation with repros is in the PR comments.

  4. nwparker commented on Sep 3, 2026

    @nwparker
    Contributor

    Correction to my comment above — one point I got wrong, and it matters for anyone acting on it.

    I wrote that Dir is natively AsyncDisposable so await using dir = await opendir(p) "works today without any helper." That is true for main / preload / renderer code, which runs on Electron 43's bundled Node 24. It is not true for src/shared/ or src/relay/ code, and that's exactly where these opendir sites live.

    Two independent runtime floors break it:

    1. Dir's disposal methods are @since v24.1.0 (@types/node/fs.d.ts:305-316). Below that, a Dir has no [Symbol.asyncDispose] at all.
    2. The relay bundles at esbuild target: 'node18' (config/scripts/build-relay.mjs:117) and the SSH toolchain floor is MIN_NODE_MAJOR = 18 (ssh-remote-node-toolchain-probe.ts:5). src/relay/pty-handler.ts:293 already documents working around this ("the relay still targets Node 18, which lacks Array.prototype.toReversed").

    And this code path is relay-bound: src/relay/fs-handler-readdir-fallback.ts:17 → shared/quick-open-readdir-walk → shared/quick-open-directory-reader.

    esbuild lowers await using into a __using helper that resolves the symbol at runtime, but leaves a class's computed [Symbol.asyncDispose] key un-lowered. When the symbol is missing the two disagree and it throws. Simulated against a real target: node18 bundle with Symbol.asyncDispose/Symbol.dispose removed:

    THREW: TypeError: Object not disposable
    

    In the relay that surfaces as: every readdir-fallback directory read throws → swallowed to [] → Quick Open silently empty on that SSH host.

    So the honest scoreboard on this axis, which I had backwards:

    approach breaks below
    await using on a raw Dir (what I suggested) Node 24.1 — i.e. effectively every supported SSH host
    a wrapper class defining its own [Symbol.asyncDispose] (what #17035 did) Node 18.18 / 20.4
    plain try { … } finally { await dir.close().catch(() => {}) } nothing

    My suggestion was worse than the PR's on remote-host compatibility. Credit where due — #17035's wrapper, whatever else was wrong with it, degraded over a narrower range than the "just use the native one" advice I gave.

    None of this revives either PR: the leaks still don't exist, main still needs no change, and the sites in question are all safe by for await's auto-close. But the rule for this repo is: no await using in src/shared/ or src/relay/ until the relay's Node floor moves. Plain try/finally is the portable form, and it's what every existing site already uses.

    Thanks to the reviewer who caught the relay target — I'd checked config/tsconfig.node.json (target: esnext) and the electron-vite bundle and stopped there, missing that the relay has its own esbuild build with a much older floor.

  5. added
    bugSomething isn't working
    os:linuxIssues affecting Linux
    on Sep 19, 2026
  6. added theissue type on Sep 19, 2026
  7. nwparker commented on Sep 27, 2026

    @nwparker
    Contributor

    Closing this umbrella after checking the remaining scope. The directory-handle premise and its proposed gate were refuted in the review of #17035/#17034; the sole real quick-open leak was fixed by #17159. The separate Windows process-query remainder is now resolved by #22872, and #16905 was closed with that evidence. The reliability-gate validation concern and the still-unexplained #12895 relay warning are distinct follow-up investigations, not remaining work in this proposal. Reopen if any original scope is still outstanding.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

bugSomething isn't workingos:linuxIssues affecting Linux

Type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions