Skip to content

fix(oracle-gaps): a stopped run removes its session directory (#150) - #164

Merged
KyleAMathews merged 9 commits into
mainfrom
fix/stopped-session-dir
Nov 19, 2026
Merged

KyleAMathews merged 9 commits into
mainfrom
fix/stopped-session-dir

Conversation

@KyleAMathews

@KyleAMathews KyleAMathews commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Closes #150.

Cause

A supervised run's session directory, <package>/.oracle-gaps-<pid>/, was removed only by the session's close() (check.mjs:2697 on af156d9). Two paths skipped close():

  • A stop. The supervised child's stop handler calls process.exit at once (index.mjs:731 on af156d9), so close() never ran.
  • An abort of the check's process. The process died before close() could run.

Only the next run's session start removed the directory (check.mjs:475). A stop before the CLI's first statement, or as the CLI starts, opens no session, so it removed nothing, and the directory stayed in the package. This happened every time a drawn base put a stop run before the spawn stop.

Fix

The fix removes a state: a run that ended no longer leaves a directory behind.

  • index.mjs: once the child has ended, however it ended, the supervisor removes the child's session directory. The CLI outlives every child it supervises.
  • check.mjs: the session also removes its directory when its process exits. This covers an unsupervised run (win32) that a stop ends. A removal failure at exit is caught, because a throw in an exit listener would end the run a second time, after its done line. A directory left that way is removed by the next run.
  • paths.mjs: sessionDirOf is now the one place that names the directory.

Production diff (first round): check.mjs +19/-4, index.mjs +9/-4, paths.mjs +7/-1. The current diff is in the review-round section below.

Evidence

  • Law (v21.2): the run namespace. A run leaves nothing in the repository, and it removes its session directory when it ends. Only a run that is killed before it cleans up leaves its directory, and the next run removes it.
    • Authority: README.md l.28-33 (contract), and the maintainer decision of 2026-11-11 (G4 namespacing; the next run removes a killed run's directory). This follows the frozen constraint "working state outside the repository" (A4, R17).
    • Oracle laws: law 10 (output namespace) and law 13 (stopping) in gap-report-oracle.property.test.mjs.
    • Model change: the oracle comment said "a stopped run may leave its session directory". The README contradicts that sentence, so it is corrected to the README's contract. This is a strengthening, not a weakening (P7).
    • The state "a run after a stopped one that left its session" is now impossible under the corrected model. Under the R7 repair clause (M-16) it becomes "a run after a killed one that left its session", with its own witness: a dead pid's directory with this host's host file, which is what SIGKILL leaves. The driver writes it before each stop run that opens a session.
    • Other v21.2 items: P4/R4/G31 (filed counterexample replayed by history, M "Replay by history"), P9/R9 (oracle-first), P11/G36 (limits stated in the property's limits), I11/R56 (the new state is POSIX-only, because the hold before the first statement ends by a signal's default action, which win32 cannot deliver; M-29), C-6 (the constructed history is appended last, and constructed-order.json records it last), R54/I16 (no new history field, and no drawn field switches a hook).
  • Reach:
    • New required state a stop before the CLI starts, after a stopped check: entered by its constructed history in 1/1 fixed-seed run and in 20/20 random-base runs at the merged head (f150-m20-after-check).
    • a run after a killed one that left its session: entered by every outcome class and by every history with a stop run that opens a session.
  • RED (oracle-only commit d73694e on af156d9, production unchanged; Arca pool):
    • f150-red2-new, fixed seed 20261105: a stop before the CLI starts, after a stopped check, fails with the stopped run left 1 session directories of its own in the package (law output namespace, checkpoint stopped).
    • f150-red2-every, every outcome class and every outcome class, the abort stop, fail with the same difference.
    • Gap e2e: a drawn base of 'a stop before the CLI starts' leaves a session directory after a stopped run #150's 5 recorded histories, replayed by history as constructed histories on scratch commits: on main 9881146, f150-red-replay fails 5/5 with the issue's difference (the run after a stopped one left 1 of its session directories); on af156d9, f150-red2-replay fails 5/5 the same way.
    • Shrink: three candidates (a run stop or an abort, then a stop before the CLI starts or as it starts) all failed on 9881146 (f150-red-shrunk). The smallest, a run stop and then a stop before the CLI starts, is the constructed history.
  • GREEN:
  • Mutant:
    • M0, the original defect (production at af156d9 under the extended oracle), is the RED above.
    • M1, in which the supervisor keeps its child's directory, fails every outcome class, the abort stop: the stopped run left 1 session directories of its own (f150-mut1-abort).
    • M2, in which the next run does not remove a killed run's directory, fails every outcome class: the stopped run left 1 session directories that were in the package before it (f150-mut2-every).
    • Calibrations a stopped run leaves its own session directory and a stopped run keeps a killed run's session directory are rejected by the law.
  • Random units, 20 runs each with fresh tags, GAP_E2E_SHRINKS=0, Arca pool: at the head, 140e42e:
    • f150-m20-before, random seed: a stop before the CLI starts: 20/20 pass. In 4/20 the drawn base put a session-opening stop before the spawn stop.
    • f150-m20-asstart, random seed: a stop as the CLI starts: 20/20 pass, 5/20 with such a stop first.
    • f150-m20-after-check, random seed: a stop before the CLI starts, after a stopped check: 20/20 pass, 20/20 with such a stop first.
    • Earlier, at e1a0ee0: before 20/20 (1/20 with such a stop first), after-check 20/20 (20/20), and random seed: a stop by SIGTERM as the CLI starts 20/20 (3/20).
    • No failures from any class. Seeds are in the Arca logs.
  • CI: run 44273917386 at 140e42e completed with conclusion success: 56 jobs pass and 2 non-blocking jobs fail.
    • The 2 failures are Windows e2e 2/10 (a hang cut off for idleness not entered) and 5/10 (the win32 abort witness). Both fail the same way on main af156d9 (run 44244302037).
    • Every Linux job is under 10 min. The longest are random 4/4 at 7m47s and determinism 7/7 at 7m17s.
    • Windows 2/10 took 10m22s. It is the recorded L9 breach (P12: Windows e2e shard 2/10 (every outcome class alone) takes 10 min #118), and it took 11m43s on main.
  • Limits:
    • Killed runs are witnessed only through the driver's directory, because no history SIGKILLs the CLI's own process.
    • A killed run's own directory (the unsupervised abort, and every abort on win32) is allowed. No history follows such a run with another run.
    • A run stopped before its first statement can remove nothing. So a killed run followed by such a stop would keep the killed run's directory whatever the CLI does. No history has that order.
    • The removal at an unsupervised exit is judged only on win32 (its hookStops histories), because POSIX's one unsupervised history stops at its note. In this PR's CI, win32 every outcome class passed every law and failed only on the reach of a hang cut off for idleness.
    • Windows 2/10 (that reach state) and 5/10 (the win32 abort witness) fail the same way on main af156d9 (run 44244302037), owned by fix(oracle-gaps): no wall-clock cut decides an outcome #99 and fix(oracle-gaps): supervise the check on win32; log each CLI run in the e2e driver #79. Windows 2/10 takes about 11.5 min there too (L9, P12: Windows e2e shard 2/10 (every outcome class alone) takes 10 min #118). The Windows e2e jobs are non-blocking.
    • In the 20-run sample, the drawn base put a session-opening stop before the spawn stop only sometimes (counts above, at both heads). The after a stopped check unit always does.
    • The Arca runs are Linux.

Review round 1 (pr164-review.md): fixes at ef875d8

This pull request and its description were written by Isaac.

KyleAMathews and others added 3 commits November 18, 2026 05:31
…wn (#150)

The output-namespace law said a stopped run may leave its session
directory and the next run removes it. A run stopped before its first
statement runs no CLI code, so it removes nothing, and the directory of
the stopped run before it stayed in the package (#150). The README's
contract is stronger: a run removes its session directory when it ends,
and only a run that is killed before it cleans up leaves one.

The oracle now judges that contract:
- a stopped run, or one whose check's process aborted, leaves no session
  directory of its own, unless its own process was killed (an
  unsupervised abort);
- before each stop run that opens a session, the driver leaves a killed
  run's directory (a dead pid, this host's host file), which the run must
  remove. The state "a run after a stopped one that left its session"
  becomes "a run after a killed one that left its session";
- #150's shrunk history, a run stopped while the witness spins and then a
  stop before the CLI starts, is a constructed history, appended last,
  with its own POSIX state;
- two calibrations reject a run that leaves its own directory and one
  that keeps a killed run's.

Co-authored-by: Isaac <no-reply@databricks.com>
A supervised child that a stop ended called process.exit at once, and a
child whose process aborted never reached its cleanup, so each left
<package>/.oracle-gaps-<pid> behind. Only the next run's session start
removed it, and a run stopped before or as the CLI starts opens no
session, so the directory stayed (#150).

- The supervisor removes its child's session directory once the child
  has ended, however it ended: the CLI outlives every child it
  supervises.
- The session removes its directory when its process exits, so an
  unsupervised run (win32) that a stop ends removes it too.
- The directory's name has one home, paths.mjs (sessionDirOf).

Only a run whose own process is killed leaves its directory now, and
the next run that opens a session removes it, as the README says.

Co-authored-by: Isaac <no-reply@databricks.com>
@changeset-bot

changeset-bot Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: a20f636

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package
Name Type
@tanstack/oracles Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@coderabbitai

coderabbitai Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

Important

  • Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 62f1aa7f-5a6e-493e-8df7-a8190d86aa74
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

…is left (#150)

A throw in the exit listener would end the run a second time, after
its done line. On win32 a file that another process still holds can
make the removal fail; that directory is left for the next run.

Co-authored-by: Isaac <no-reply@databricks.com>
@pkg-pr-new

pkg-pr-new Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

Open in StackBlitz

npm i https://pkg.pr.new/TanStack/oracles/@tanstack/eslint-plugin-oracles@164
npm i https://pkg.pr.new/TanStack/oracles/@tanstack/oracles@164

commit: a20f636

KyleAMathews and others added 3 commits November 18, 2026 09:13
Conflicts in the e2e oracle: the POSIX start states, the law's limits,
and the end of the constructed list, where #147's two histories come
before #150's, which stays last (C-6). constructed-order.json records
#147's two names before #150's.

Co-authored-by: Isaac <no-reply@databricks.com>
…t CLI wrote (#164 F1, F7, F9)

Review of #164, F1: once a stopped run removes its own session
directory, no history showed the next run a directory that the CLI
wrote, so nothing judged the CLI's `host` file. A CLI that stopped
writing it would pass, and a killed run's directory would never go.

- A constructed stop `kill` (constructed only; taken back as `run`)
  SIGKILLs the CLI and its check's process group while the witness
  spins. It owes no line (L1). The driver deletes the killed CLI's
  run.pid, as the stale-claim refusal tells a user to.
- The constructed history "a run after a killed CLI" (appended last)
  follows it with a run stopped while the witness spins, which must
  remove the killed CLI's directory through its own `host` file. Its
  state "a run after a killed CLI that left its own session" is
  required on every platform.
- F7: the driver's killed-run directory uses a pid that no process can
  have (2^30 + 1).
- F9: killedSession sits above stoppedRun's comment.

Co-authored-by: Isaac <no-reply@databricks.com>
Review of #164, F2: the supervisor's removal of its child's session
directory had no guard, so a failed removal reached the supervisor's
uncaughtException handler and ended the run a second time (an error
line and exit 3 after its done line). It also removed the directory of
whatever process ran under the child's pid by then.

removeSession(pkg, pid) in paths.mjs is now the one removal: the
supervisor, the session's close and exit, and the sweep of killed
runs' directories all use it. It removes this process's own directory
or an ended process's, keeps a live pid's, and leaves a directory it
cannot remove for the next run. alive() moves there too, so the CLI
has one copy instead of two.

Co-authored-by: Isaac <no-reply@databricks.com>
KyleAMathews and others added 2 commits November 18, 2026 11:28
#168 (#164 F8)

- Law 10 cites the register's C entry of 2026-11-18, "A run that ends
  removes its session directory".
- .changeset/gap-cli-runtime.md no longer says that a stopped run's
  session directory is removed by the next run.
- The property's limits name #168 for the removal witnesses that are
  owed (F2, F4, F5, F6).

Co-authored-by: Isaac <no-reply@databricks.com>
No conflicts. #164's two constructed histories stay last.

Co-authored-by: Isaac <no-reply@databricks.com>
@KyleAMathews
KyleAMathews merged commit 6d05f05 into main Nov 19, 2026
58 of 60 checks passed
@KyleAMathews
KyleAMathews deleted the fix/stopped-session-dir branch November 19, 2026 03:53
KyleAMathews added a commit that referenced this pull request Nov 19, 2026
main's two constructed histories from #164 come first in the list, and
the failing-law history follows them.

Co-authored-by: Isaac <no-reply@databricks.com>
KyleAMathews added a commit that referenced this pull request Nov 19, 2026
#164's two constructed histories come first and #133's twelve daemon-input
histories after them (C-6, ratified); the law's limits keep both texts.

Co-authored-by: Isaac <no-reply@databricks.com>
KyleAMathews added a commit that referenced this pull request Nov 19, 2026
#164 removes a stopped run's session directory (removeSession) and adds
the kill stop. Main's constructed histories come before #99's, and its
Limits clause follows #99's rewrite of the idle paragraph.

Co-authored-by: Isaac <no-reply@databricks.com>
KyleAMathews added a commit that referenced this pull request Nov 19, 2026
…ism shard 1 (P12)

Determinism 7/7, the rest shard, took 12:03 on CI at cb1de4f (run
44462540755). Its slowest units are main's; this moves the three that
landed there last (#164's 'a run after a killed CLI' and 'a stop before
the CLI starts, after a stopped check', and #147's filed base, about 53 s
on the pool) to shard 1, which took 160 s on the pool.

Co-authored-by: Isaac <no-reply@databricks.com>
KyleAMathews added a commit that referenced this pull request Nov 19, 2026
With #164's histories and the filed base moved, determinism 7/7 still took
10:51 on CI (run 44552467396) while shard 1 took 4:11. 'a daemon pause
that cannot engage' (74 s on the pool) and 'every outcome class, the abort
stop' (15 s) move to shard 1 as well.

Co-authored-by: Isaac <no-reply@databricks.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Gap e2e: a drawn base of 'a stop before the CLI starts' leaves a session directory after a stopped run

1 participant