Skip to content

feat: record how long a refused report child outlives its cancel - #5771

Merged
janicduplessis merged 1 commit into
mainfrom
fix/5766-report-child-overrun
Nov 15, 2026
Merged

janicduplessis merged 1 commit into
mainfrom
fix/5766-report-child-overrun

Conversation

@janicduplessis

Copy link
Copy Markdown
Collaborator

Description

A report child whose cleanup is refused (STIM_CLAIM_UNAVAILABLE) is left running, and the daemon log shows only when stimd next found it stopped, once per tick. How long such a child outlives its cancel is not known, and that number decides whether a longer wait, a caller timeout or signalling is the right fix for #5766.

Solution

reportChild in exec.ts records, for a child it refuses, when it was spawned, when its cancel started, why, and when the handle delivered exit. When the exit is seen (immediately if it already was) it writes one daemon_report_child_exited info record through report-child-log.ts. stimd's logger and each stimd thread's logger are installed as the sink, so the record reaches daemon.ndjson. A CLI process installs none and writes nothing. No timer is added: a listener on the child's exit event does not keep the process alive, and a child that never exits writes no record.

Fields: pid, command (the bounded, redacted text of the refusal), cancelReason (timeout, overflow and exit and close from the exec call sites, report_budget when the abort reason is the report's own STIM_REPORT_TIMEOUT, abort for any other abort, unknown), timeoutMs when the call had one, spawnToCancelMs, cancelToExitMs (negative when the exit came first), exitCode, exitSignal, refusal (unverified, did_not_close, descendants), captured, captureReason.

When a refusal happens, what is signalled, retained or waited for, and every error are unchanged. stim guide logs lists the event.

Test plan

  • report-runtime.integration.test.ts: an uncaptured child that is refused and exits 3 s after it started produces one record with cancelReason: abort, refusal: unverified, captured: false, timeoutMs, exit code 0, and cancelToExitMs of at least 1500.
  • Full workflow on 04a5f66: test (node 22), test (node 24), test (macos) and test (windows) passed: https://github.com/appandflow/stim/actions/runs/43736826863
  • Not exercised: a real stimd writing the record to daemon.ndjson, and a record produced from a stimd thread. The test uses an installed sink and a real spawned child.

Part of #5766

@janicduplessis janicduplessis left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

AI review: head 04a5f66

Verdict: clear

I ran report-runtime.integration.test.ts in the worktree: 21 passed, 2 skipped. I did not run a real stimd.

1. Behaviour identity (exec.ts): no difference from main found

  • cancel(reason?): cancelledAt and cancelReason are assigned synchronously at the top of the memoised async body, before the first await. cancelled ??= still runs the body once. A second call with a different reason returns the same promise and leaves the first reason in place. Neither assignment can throw: signal.reason is a plain property read and the instanceof/in checks are guarded.
  • refuse(message, refusal): the thrown error, the destroys, unref() and rejectClosed are unchanged. recordRefused runs after unref() and before rejectClosed, and returns early when pid is undefined. It only registers a listener or logs. Everything in write() is arithmetic and field reads, and logReportChild swallows sink errors, so nothing can reach the refuse or cancel path.
  • New exit listener: it only assigns two locals. It is attached inside reportChild, so it registers before the cleanupOnExit listener that defaultExecutor attaches afterwards. The close handler is untouched except that it passes 'close'. The deferred once('exit', write) is registered after the recorder, so exitedAt is set when write runs.
  • Exit before cancel: exitedAt is already set, write runs immediately, and cancelToExitMs is negative. This is the descendants case under cleanupOnExit.

3. Process lifetime

  • An exit listener holds no handle, and no timer is added. A CLI process has no sink. In stimd the loop is alive anyway. A child that never exits writes no record, as the PR says.
  • Low, note (stimd/main.ts:778): the sink is never cleared. The early-return paths and the final shutdown call writer.close(), and a later record then goes to a closed writer. write returns false and increments dropped, so nothing throws and nothing is written to a closed fd. In threads.ts the thread's postMessage is inside the try. Neither is worth a change.

4. Output

  • No stdout or stderr writes. The record is one info line with exactly the guide's fields. command is describeReportCommand (basename plus redactArgv, capped at 120 characters), the same text as #5769. Nothing else from argv or env is included.
  • Note: a forwarded CLI command that runs inside stimd logs through the daemon sink without its invocation id. The record cannot be tied to the command that started the child except through command.

5. Data

  • spawnToCancelMs, cancelToExitMs and the timeoutMs that budgetMs returns (omitted when unbounded) answer how long the child lived after the cancel, why it was cancelled, and what its timeout was.
  • Note (exec.ts recordRefused): for descendants, cancelToExitMs is the leader's exit. It says nothing about how long the descendants lived. The guide says "that child's own exit", so it is accurate.
  • Note: spawnedAt is taken when reportChild is called, after the spawn. The skew is negligible.

6. Module global sink

  • It matches debug-log.ts, which is also a module-level instance. Each worker thread has its own module instance and threads.ts installs its own sink, which posts to the main thread. The test resets the sink in finally.

7. Test and guide

  • The test names a real failure: an uncaptured child that is refused and exits later. Its expectation is independent of the implementation (real child, real exit code, cancelToExitMs >= 1500 against a 3 s child). It sits at the lowest stable seam, with an installed sink standing in for the daemon.
  • Note: it does not cover the timeout, report_budget or exit reasons or the negative cancelToExitMs. That is acceptable for diagnostics.
  • It uses process.execPath, so it works on Linux and Windows, and CI passed on both.
  • The guide/logs.ts addition is prose and documents a code-defined event name and fields. No regex test on it is needed.

8. PR body

  • Accurate. It says it exercised no real stimd write and no thread record, and both are unexercised.

@janicduplessis
janicduplessis marked this pull request as ready for review November 15, 2026 16:58
@janicduplessis janicduplessis added the review: ai-approved A fresh AI review found nothing left to fix label Nov 15, 2026
@janicduplessis
janicduplessis merged commit 286452f into main Nov 15, 2026
59 of 60 checks passed
@janicduplessis
janicduplessis deleted the fix/5766-report-child-overrun branch November 15, 2026 17:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

review: ai-approved A fresh AI review found nothing left to fix

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant