Skip to content

marketplace: two unconditional in-place rewriters race on every Write with no defined precedence, nobody sums the always-on per-turn cost, and thirteen CRITICALs need an ordering #1809

Closed

Description

@kyle-sexton

Filed by an agent session that audited six components in one run. These three items belong to no single plugin — each was noticed by two or more audits and owned by none. Following the precedent in issue #1682, which bundles cross-plugin observations "rather than silently mis-filed" and invites a maintainer to split them.

1. Two unconditional in-place rewriters race on every Write, and nobody owns it

typos-format 0.4.2 and markdown-format 0.8.4 both register PostToolUse with matcher: "Write|Edit", unconditionally, and both rewrite file content in place.

The hooks reference states matching hooks "run in parallel, and identical handlers are deduplicated automatically", and separately that when multiple hooks return competing results "the last one to finish takes effect. Since hooks run in parallel, the order is non-deterministic."

So on any Markdown write, two independent processes read, rewrite, and write back the same file with no defined precedence and no locking.

Both audits noticed this. typos-format discloses it in its own script header and README as a fleet concern; markdown-format's audit reached the same conclusion. Both classified it as something neither plugin can solve alone — so it is recorded twice and owned zero times, which is precisely how a defect survives an audit.

Disclosure is honest but is not a fix. This needs a named owner and one of: a shared advisory lock, a declared ordering, a single serialising formatter dispatcher, or an explicit decision that last-writer-wins is acceptable and why.

Observed evidence that the risk is not theoretical: during this audit both hooks mutated the same class of files, and three separate content-destroying rewrites were captured — a dictionary autocorrect renaming Win32 identifiers, MD004 falsifying a quoted changelog line, and MD018 destroying a line-leading issue reference while fabricating a heading. Each was individually recoverable; two of them landing on one file in undefined order is not something any audit has bounded.

2. Nobody sums the always-on cost, and the consumer is the one who feels it

This single session carried, on every turn or every tool call, in every consumer session regardless of whether the plugin was in use:

  • disk-hygiene's plugin-level engine gate — on every Bash and PowerShell command. Its marker-free fallback calls os.path.samefile on every separator-carrying word of every command, including commands with no relation to the plugin. Its own docstring names this as the strongest candidate for an observed 17-second stall.
  • disk-hygiene's Stop detector — once per turn. Its amortisation claim holds only after a failure has been reported, because the marker is written only when a warning fires. On the happy path every turn pays interpreter startup (the plugin's own ADR measures python3 -c 'pass' at 396 ms on this host) plus a seek-and-read of up to 2 MB.
  • four guardrails classifiers — on every Bash and PowerShell command.
  • two PostToolUse formatters — on every Write and Edit.

Each plugin accounts for its own share honestly where it accounts at all. Nobody adds them up. A per-turn and per-tool-call cost budget across the marketplace is the missing question, and the aggregate is what a user experiences — the 17-second stall that disk-hygiene's guard docstring investigates is a symptom of the sum, not of any single component.

Suggested shape: a stated budget (milliseconds per turn, milliseconds per tool call) that every always-on hook must fit inside, plus a measured accounting per plugin against it. Without a shared ceiling, each plugin's individually-reasonable cost composes into something no one reviewed.

3. Sequence the batch — this is worth more than the individual reports

This audit produced thirteen CRITICALs across five plugins, all destined for this repository at once, with no ordering. Several of the highest-value fixes are one-liners, and none requires agreeing with the deeper structural findings first:

  1. Flip typos_format_write_changes to false in typos-format's plugin.json. Write mode becomes opt-in. Removes the entire silent-corruption class immediately — including the already-filed issue typos-format: hook silently corrupts abbreviated git SHAs, including inside backticks #1257 — while preserving the zero-config reporting win that 0.2.0 was protecting. Verified working: with it false, the file is byte-identical afterwards and findings still surface.
  2. Make markdown-format report-only when no markdownlint config is discoverable. This is the same author's own doctrine elsewhere in this marketplace: bash-format refuses to run when the repo has no shfmt config, "so the plugin never imposes a style you did not [choose]". Applying it here closes the quote falsification, the issue-reference destruction, the unreachable remediation advice, and roughly 115 unactionable MD013 findings in one change, using machinery collect_risky_configs already has.
  3. Give block-noncanonical-commit an exit 0 on rc=2, following the precedent already present at block-convention-violation.sh:375-383. Coverage cost is provably zero — both guards call ps::classify_git_command with identical arguments, corroborated across a 12-case corpus where every commit-guard block was also a dangerous-git block carrying that guard's accurate message.

An ordered "these three land most of the CRITICAL surface today" list is more actionable than five independent reports arriving together.

One hard ordering constraint

A typos-format audit found a write-bypass leak in guardrails' block-hook-bypass.sh: a Python one-liner that opens a path and writes it evades the Write/Edit PostToolUse hooks entirely, while the guard refuses the echo/printf redirection form.

Closing that leak removes the last escape hatch from typos-format's unconditional write mode. So item 1 must land before the bypass is closed, or the situation gets strictly worse for anyone whose vocabulary the dictionary mangles.

4. A process finding, since it affects every future audit in this repo

There is no verification step anywhere between "auditor writes evidence packet" and "drafter reads packet", while the plugin-quality workflow instructs a fresh auditor to treat the packet as ground truth for behavioural claims.

In this run: packet files were mutated in place by sibling hooks three times; one packet's evidence.md carried three false factual claims; and an independent review gate found four further factual errors that had survived into the locked-contract layer in two cases. One of those was load-bearing — an incorrect explanation of a measured attribute discrepancy that would have caused a maintainer to dismiss a CRITICAL on first verification.

Content-hash-at-write-time is the right primitive and is currently one clause inside a bundled remediation in the plugin-quality issue. Raising it here because the exposure is not specific to that plugin: any workflow in this marketplace that writes durable evidence for a later reader, while unconditional in-place formatters are installed, has the same hole.

Activity

  1. added
    needs-triageNot yet classified. Floor until a type and one priority tier are set.
    on Jul 30, 2026
  2. kyle-sexton commented on Jul 31, 2026

    @kyle-sexton
    MemberAuthor

    Delegated-authority decision — recorded by the autonomous drain lane under this session's delegated decision authority, for post-hoc review. Verified against origin/main (d5d02a2) before deciding: both hooks register PostToolUse on Write|Edit; typos-format (now 0.4.4) still writes by default (typos_format_write_changes default true in both the manifest and the script fallback), markdown-format (now 0.8.6) still runs --fix unconditionally whenever a linter binary resolves. The race, the missing sum, and the ordering gap all reproduce as filed.

    Decision 1 — precedence architecture for the two rewriters

    Chosen: single-writer-by-default. The precedence question is dissolved, not adjudicated: by default, at most one in-place rewriter may match any file class.

    • typos-format: typos_format_write_changes default flips true → false (manifest and script fallback). Out of the box the hook is report-only; write mode is an explicit consumer opt-in. Batch item 1 verbatim; removes the silent-corruption class including typos-format: hook silently corrupts abbreviated git SHAs, including inside backticks #1257.
    • markdown-format: the run is gated on a discoverable markdownlint config (the same directory walk collect_risky_configs already does, extended to the full candidate list). No config → no run at all: markdownlint's built-in rule set is a style the repo never chose, so neither --fix rewrites nor default-rule findings (the ~115-finding MD013 class) are imposed. This is bash-format's own shfmt opt-in doctrine applied to its sibling; batch item 2.
    • Resulting invariant: a default install has zero unconditional writers on any file class. typos-format still reads while markdown-format may write in an opted-in repo — a stale read can misstate a finding but cannot corrupt content. The one re-openable overlap — a consumer switches typos write mode ON in a repo that also carries a markdownlint config — is a deliberate double opt-in and is documented in both READMEs as last-writer-wins rather than left undefined.
    • fleet: concurrent PostToolUse hook writes can silently clobber each other (no locking/ordering) #875 stays open as the fleet tracker for the residual scoped-writer overlap class (eol-normalizer + extension-scoped formatters); this decision removes that class's unconditional members.

    Rejected alternative (designed second): shared advisory lock / serializing formatter dispatcher. Rejected on four grounds: (1) a lock serializes but does not define order — the final bytes stay nondeterministic, so the race is hidden, not resolved; (2) it adds acquisition latency to every Write on top of an already-heavy per-Write hook wall (measured below); (3) to be sound the protocol must be vendored into every writer plugin's duplicated hook-utils.sh and adopted by every future writer — a fleet-wide coordination primitive owned by nobody, which is precisely the ownership failure this issue documents; (4) it leaves the root cause untouched: a default-on dictionary rewriter mutating content nobody asked for. Stale-lock expiry under the harness's hook-timeout kill adds failure modes with no compensating benefit.

    Decision 2 — the always-on cost budget

    Measured on a representative dev host (Windows 11, Git Bash), method: EPOCHREALTIME wall clock around direct hook invocation with benign payloads; 10-run averages for singles; & + wait for parallel sets (an approximation of the harness's parallel dispatch — if anything friendlier, since the harness adds its own spawn wrapping):

    What Cost
    python3 -c pass / bash -c : / jq --version ~158 / ~82 / ~73 ms
    one guardrails classifier, benign ls -la ~1.6 s
    disk-hygiene engine-gate solo / Stop detector ~135 ms / ~280 ms per turn
    per-Bash-call always-on set (6 guardrails classifiers + engine gate), parallel wall ~5.9 s
    per-Write set (2 formatters + 3 guardrails verifiers), parallel wall ~1.9 s

    The 17-second-stall reading is corroborated: no single hook is outrageous; the sum is, and process-spawn contention makes the parallel wall far worse than any member. Budget adopted (codified as docs/conventions/hook-budget/README.md in the attached PR): fleet-wide always-on aggregate ≤ 1 s typical / 2 s worst-case wall per tool call, ≤ 500 ms per turn (Stop), measured as parallel wall on a representative dev host; every plugin adding an always-on hook states its measured share in its README. The current Bash|PowerShell lane exceeds the budget ~3–6×; the overage becomes per-plugin work items (guardrails spawn-reduction is already tracked in #1403) — a reason to fix the members, never to relax the ceiling.

    Decision 3 — ordering the thirteen-CRITICAL batch

    1. Now (PR attached to this issue): batch items 1 + 2 — typos-format report-only default; markdown-format config gate. Largest CRITICAL surface closed, both plugin-local, zero cross-plugin coordination.
    2. Stage 2 (separate guardrails-scoped PR): batch item 3 — block-noncanonical-commit exit 0 on rc=2, per the precedent at block-convention-violation.sh:375-383. Staged separately not for size but because guardrails' commit guards carry a dense open surface (guardrails: block-noncanonical-commit on main exits 139 (SIGSEGV) on a wrapped cd builtin in a shell-alias body #1495, guardrails: block-noncanonical-commit resolves the repository at the outer invocation when the nested one determines it #1500, guardrails: block-noncanonical-commit analyzes the wrong repository when a ! alias body relocates the process (cd) #1486, guardrails: both git guards recurse into aliases git itself refuses (environment-changing global in a non-shell expansion) #1502) and their changelog/review must not ride a formatter PR.
    3. Hard constraint honored: the block-hook-bypass.sh write-bypass-leak closure must not merge before stage 1 does. Once typos-format is report-only by default, closing that leak no longer worsens exposure for anyone whose vocabulary the dictionary mangles.
    4. Item 4 (evidence-packet integrity) routes to plugin-quality: the resume rule breaks on any multi-target audit, retention is a model-executed recursive delete over the tree holding the deliverable, and packets are mutable by sibling hooks #1808, which already tracks packet mutability by sibling hooks; content-hash-at-write-time belongs there. Stage 1 also removes the packet-mutation vector itself for default installs.
  3. kyle-sexton commented on Jul 31, 2026

    @kyle-sexton
    MemberAuthor

    Stage 1 landed as PR #1859 (typos-format 0.5.0 report-only default; markdown-format 0.9.0 config opt-in gate; docs/conventions/hook-budget/README.md), which closes this issue per the decision comment above. Staging: stage 2 (guardrails block-noncanonical-commit rc=2 exit) is #1858, which also restates the hard constraint that the block-hook-bypass write-leak closure must not merge before #1859 does; item 4 (evidence-packet integrity) is owned by #1808; residual scoped-writer overlap stays tracked in #875.

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

    needs-triageNot yet classified. Floor until a type and one priority tier are set.

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions