Skip to content

perf(disk-hygiene): run the guard-launch monitor only on Stops after a new guard launch #8771

Description

@kyle-sexton

Part of #20261020-235600-stop-hook-fanout-latency-per-turn

Problem

The disk-hygiene Stop row "Checking for silent destructive-guard failures..."
(plugins/disk-hygiene/hooks/hooks.json:116-139) is the slowest Stop hook on a measured Windows host:
p50 580 ms, p95 2,072 ms over 104 Stops. It sets the Stop wall.

The launcher skip (exec-bash.mjs --skip-unless-marker guard-launch-monitor, from #6254 and #3516)
skips only when the session has no <session>.launched marker. One marker turns the monitor on for
every later Stop of the session, so it starts bash and Python each turn even when no guard launched
since the last check. Markers are common:

  • run-python-hook.sh --launch-marker writes the marker whenever an engine-gate row launches
    (run-python-hook.sh:120,287). Those rows are if-gated on Bash(*hygiene.py*),
    PowerShell(*hygiene.py*), PowerShell(*python*$*) and PowerShell(*& $*) (hooks.json:39,66,88,110).
    The if match is on command text, so any command naming the engine file, a read-only grep included,
    launches the guard and marks the session (reproduced this pass: a grep naming the file was refused
    by the guard).
  • The marker is keyed by session id, which subagents and workflow agents share, so any agent marks
    the whole session.
  • On the measuring host, 250 of about 382 top-level sessions since 2026-10-01 hold a .launched
    marker (marker files versus session transcripts in the same window), and the measured session held one.

Evidence

Verified this pass on origin/main (31eafaa): the Stop row, the four engine-gate rows and their if
filters, the marker write in run-python-hook.sh, and the monitor's contract
(skills/clean/scripts/guard_launch_monitor.py header: it emits only {"systemMessage": ...}, never
blocks). Timings from findings.py stop-hook-timing on the measured session. Which row marked that
session was not determined.

Proposed approach

Recommended: make the skip mean "no guard launch since the last monitor run". The launcher records a
launch count or a timestamp in the marker on each launch; the monitor records what it last processed
in its existing <session>.cursor; the node-side --skip-unless-marker check compares the two and
skips when nothing is new. Keep failing closed: unreadable or missing state runs the monitor.

Alternatives:

  • async: true on the Stop row. The monitor is advisory and only emits a systemMessage, so it need
    not hold the turn. Verify against the hooks docs that a background hook's systemMessage still reaches
    the user before relying on it.
  • Narrow the PowerShell if filters. Rejected as the main fix: they exist to catch indirect engine
    launches, and narrowing them weakens the guard.

Files: lib/exec-bash.mjs (canonical; regenerate copies with scripts/sync-shared-copies.sh),
plugins/disk-hygiene/hooks/run-python-hook.sh, plugins/disk-hygiene/skills/clean/scripts/guard_launch_monitor.py.

Acceptance criteria

  • In a session whose marker exists but no guard launched since the last Stop, the Stop row starts
    only node (job-object or process census shows no bash or Python).
  • A guard launch after the last Stop makes the next Stop run the monitor, and a seeded
    hook_non_blocking_error for the guard is still reported.
  • Missing or unreadable marker or cursor state runs the monitor (test).
  • Re-measured p95 for this row on Windows drops below the node-only rows' p95 (about 1,000 ms on the
    measuring host) with host load stated.

Constraints and gotchas

  • This row is a safety detector for a destructive-command guard. Any change must degrade toward
    running, never toward silence (the monitor's own doctrine).
  • exec-bash.mjs is shared by many plugins; the new behavior must stay behind the
    --skip-unless-marker flag.
  • Bump disk-hygiene's version and CHANGELOG; shared-copy changes bump each plugin whose copy changes.

Context

Source: local handoff item 20261020-235600-stop-hook-fanout-latency-per-turn.md. Prior: #6254, #3516,
#4416, #2577 (harness-ops detector that overlaps this one by design).

Activity

  1. github-actions commented on Oct 21, 2026

    @github-actions
    Contributor

    Proposed work class: work-class: scoped
    Basis: automated intake triage; the lanes App applied this class.

    Size: Medium
    Complexity: High
    Uncertainty: Known
    Flags: none
    Blocked by: none

    Decision recorded. Decided on the facts, under the body's constraint: "Any change must degrade toward running, never toward silence". These answer the four points in the lane's pushback.

    1. What a launch writes: a token unique to that launch (epoch seconds, the bash PID and $RANDOM, all bash builtins) into <session>.launched. A count and a whole-second timestamp can each miss a launch that runs concurrently with a Stop (lane analysis).
      [quote truncated; the full decision is at the link]

    Link: #8771 (comment)

    The decision settles the open questions: the marker token format, the write order, the new .seen file, the fail-toward-running cases, and moving the Windows p95 criterion to #9158. Nothing is left to ask. The remaining work is one change to the launcher, the monitor and the shared exec-bash.mjs, with tests and version bumps.

    Automated triage, applied by the lanes App.

  2. removed
    agent-readyFully specified and briefed; eligible for autonomous pickup from the frontier.
    on Oct 21, 2026
  3. kyle-sexton commented on Oct 21, 2026

    @kyle-sexton
    MemberAuthor

    Issue Triage: this issue's 01:36Z lane run skipped (issue-dimensions: not-assessed): Size, Complexity and Uncertainty were unset. Fields now set: Medium / High / Knowable. agent-ready is removed until: a Known call settles the marker and cursor state format, and the Windows census and p95 criteria are split into a needs-human child. It is re-added at that point, which starts a new run.

  4. github-actions commented on Oct 26, 2026

    @github-actions
    Contributor

    The triage sweep dispatched intake triage for this issue (attempt 1 of 2).

  5. added
    admission-deferredAdmitted but waiting for WIP room; the hourly work-unblock sweep labels it agent-ready.
    agent-readyFully specified and briefed; eligible for autonomous pickup from the frontier.
    and removed
    admission-deferredAdmitted but waiting for WIP room; the hourly work-unblock sweep labels it agent-ready.
    on Oct 29, 2026
  6. 1 remaining item

  7. removed
    agent-readyFully specified and briefed; eligible for autonomous pickup from the frontier.
    on Oct 29, 2026
  8. melodic-automation-lanes commented on Oct 29, 2026

    @melodic-automation-lanes
    Contributor

    The work-resolve-issue lane did not start this issue: it needs a person to make it clearer first.

    Why, in the run's own words:

    Open decision: the state format behind 'no guard launch since the last monitor run'. The 2026-10-21 triage comment made a Known call on the marker and cursor state format a precondition for agent-ready. No Decision recorded. comment makes that call, and the body still offers 'a launch count or a timestamp'. The format decides whether this safety detector can miss a launch, so this run did not pick one. Please record a decision on these four points. (1) What each launch writes into <session>.launched. Recommended: a token unique to that launch (epoch seconds, the bash PID and $RANDOM, all bash builtins). A count is a read-modify-write: a launch that read N before another launch wrote N+1 can write N+1 again after the monitor recorded N+1, so the next Stop skips that launch. A whole-second timestamp (the launcher's only clock today, printf '%(%s)T' at plugins/disk-hygiene/hooks/run-python-hook.sh:529) compares equal for two launches in one second with a monitor run between them. Both races need a launch concurrent with Stop, such as a background subagent, which the issue says shares the session id. (2) Where the monitor records the value it processed. Recommended: a new <session>.seen file beside <session>.cursor. The issue names the existing cursor, but _read_cursor (plugins/disk-hygiene/skills/clean/scripts/guard_launch_monitor.py:199-211) requires the text after the offset line to be exactly the transcript path plus a newline, so an added line makes every Stop cold-rescan the whole transcript unless that parse changes too. (3) Acceptance criterion 3 read literally ('missing marker ... runs the monitor') undoes the existing skip for sessions where no guard ever launched (#6254). Confirm it means: a .launched marker that exists but is empty, unreadable or malformed, or a missing or unreadable processed-state file, runs the monitor, while a marker directory holding no .launched still skips. Today's markers are empty files, so they would run the monitor until the next launch writes a value. (4) Criteria 1 (Windows process census) and 4 (Windows p95 re-measure) need a Windows host run this lane cannot make. The same triage comment asked for them in a needs-human child, and the body still lists them. Say whether this PR may leave them as remaining work (the PR refs the issue without closing it), or whether the child is filed first.

    What the run says it did not do:

    • No implementation: the run pushed back before any edit, so tidy, review, build, tests and lint were not run.

    The newest comment from a listed maintainer, #8771 (comment), does not start with **Decision recorded.**, so the lane did not count it as an answer. If it answers the question, post the answer again in a new comment whose first line is:

    **Decision recorded.** <answer>
    

    Run: https://github.com/melodic-software/claude-code-plugins/actions/runs/40831842391

    To retry, answer the question in a comment whose first line is **Decision recorded.**, then remove needs-human and add agent-ready again.

  9. kyle-sexton commented on Oct 30, 2026

    @kyle-sexton
    MemberAuthor

    Decision recorded. Decided on the facts, under the body's constraint: "Any change must degrade toward running, never toward silence". These answer the four points in the lane's pushback.

    1. What a launch writes: a token unique to that launch (epoch seconds, the bash PID and $RANDOM, all bash builtins) into <session>.launched. A count and a whole-second timestamp can each miss a launch that runs concurrently with a Stop (lane analysis).
    2. Write order, so that a failed write degrades toward running: the launcher first removes <session>.seen, then truncates .launched, then writes the token. If the open fails, .seen is already gone, and a missing .seen runs the monitor. If the write fails after the truncate, .launched is empty, and an empty .launched runs the monitor (item 4). If both the .seen removal and the .launched open fail, the launcher passes that fact to the guard it execs (for example, an environment variable naming the marker it could not write), and the guard adds a systemMessage that names the marker, in the same output that carries its own decision. Its decision and exit status do not change. A stderr line alone would not do: at exit 0 it is discarded (docs/contracts/liveness-assertion/README.md, "a stderr line discarded on exit 0"). This keeps the body's constraint: "Any change must degrade toward running, never toward silence". The existing first-launch residual (run-python-hook.sh:182-187) is unchanged.
    3. Where the monitor records what it processed: a new <session>.seen file holding the token it last processed. The existing .cursor format stays unchanged, so its parse in guard_launch_monitor.py is untouched. The Stop skips only when .seen exists, is readable, and equals the token in .launched. The monitor does not record a token whose epoch part is less than 60 seconds old, the engine-gate rows' hook timeout (hooks.json:51,78,100,122). A launch still in flight during a Stop, such as one from a background agent that shares the session id, then runs the monitor again on the next Stop and is not marked seen before its error can reach the transcript.
    4. Criterion 3 means: the monitor runs when an existing .launched is empty, unreadable or malformed, or when .seen is missing or unreadable. A session with no .launched keeps the existing perf(autonomy, disk-hygiene): decide how Stop rows skip bash when idle #6254 skip. Today's empty markers run the monitor until the next launch writes a token.
    5. Criterion 1 allows "job-object or process census". A process census of the skip path, on the lane's runner, meets it. Criterion 4 needs a Windows host. The Windows re-measure runs under #9158 ("Re-measure the Windows Stop wall p95 after perf(disk-hygiene): run the guard-launch monitor only on Stops after a new guard launch #8771 and perf(harness-ops): keep the hook-failure audit off the Stop wall #8772 land"), which is blocked on this issue closing. The pull request closes this issue, and criterion 4 is checked in that re-measure.
    • In a session whose marker exists but no guard launched since the last Stop, the Stop row starts only node (job-object or process census shows no bash or Python). (body, unchanged)
    • A guard launch after the last Stop makes the next Stop run the monitor, and a seeded hook_non_blocking_error for the guard is still reported. (body, unchanged)
    • An existing .launched that is empty, unreadable or malformed, or a missing or unreadable .seen, runs the monitor, and a launch whose token write fails leaves state that runs the monitor (test). (body, amended: "missing marker" keeps the perf(autonomy, disk-hygiene): decide how Stop rows skip bash when idle #6254 skip, per item 4, and the write order in item 2 is tested)
    • Re-measured p95 for this row on Windows drops below the node-only rows' p95 (about 1,000 ms on the measuring host) with host load stated. (body, amended: checked in the Re-measure the Windows Stop wall p95 after #8771 and #8772 land #9158 Windows re-measure, not by this issue's pull request)
    • A launch whose .seen removal and .launched open both fail makes the guard emit a systemMessage naming the marker, with the guard's decision and exit status unchanged (test). (body constraint "never toward silence", unchanged; covers the later-launch case item 2 introduces)
  10. removed
    needs-humanHuman-in-the-loop required; autonomous sessions must not resolve items carrying this.
    status: readyTriaged, unblocked, and fully specified; eligible to pick up.
    on Oct 30, 2026
  11. added
    status: readyTriaged, unblocked, and fully specified; eligible to pick up.
    admission-deferredAdmitted but waiting for WIP room; the hourly work-unblock sweep labels it agent-ready.
    agent-readyFully specified and briefed; eligible for autonomous pickup from the frontier.
    and removed
    admission-deferredAdmitted but waiting for WIP room; the hourly work-unblock sweep labels it agent-ready.
    on Oct 30, 2026
  12. melodic-automation-lanes commented on Oct 30, 2026

    @melodic-automation-lanes
    Contributor

    The work-resolve-issue run that agent-ready started ended over 3 hours ago with no report and no pull request. work-unblock removed and added agent-ready back to start a fresh run on main's workflow files. If this run ends the same way, it re-fires the issue again, waiting longer each time.

  13. added
    agent-readyFully specified and briefed; eligible for autonomous pickup from the frontier.
    and removed
    agent-readyFully specified and briefed; eligible for autonomous pickup from the frontier.
    on Oct 30, 2026
  14. added
    agent-readyFully specified and briefed; eligible for autonomous pickup from the frontier.
    and removed
    agent-readyFully specified and briefed; eligible for autonomous pickup from the frontier.
    on Oct 30, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    agent-readyFully specified and briefed; eligible for autonomous pickup from the frontier.status: readyTriaged, unblocked, and fully specified; eligible to pick up.

    Type

    Fields

    No fields configured for Task.

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions