[finding] `node-metadata-manager`'s watcher has the same one-shot delivery structure #9339 just repaired, with no reconciliation behind it

[os-sam]

Found while implementing #9339 (PR #9656). Filed unassigned — recording, not claiming. ⛔ Not fixed in that PR: its declared file surface was packages/metadata-fs/src/repository.ts, and this is a different package with a different gate surface.

Open-issue search run before filing: no hits for node-metadata-manager + watcher.

The observation

packages/metadata/src/node-metadata-manager.ts:58 runs its own chokidar watcher over a project root:

usePolling: true, interval: 1000, ignoreInitial: true

That is the identical structure #9339 measured and repaired one package over — and it has no reconciliation behind it.

#9339's finding, which transfers verbatim: under usePolling, chokidar re-reads a directory only when its stat strictly advances. An external write advances the directory's mtime once, so the file gets exactly one delivery attempt; polls 2..N compare an unchanged stat and can never rediscover it. #9339 measured at least six independent one-shot gates sitting on that single attempt, spanning three layers (kernel timestamp, chokidar's readdir throttle and readdir snapshot, chokidar's emit gates), each producing a byte-identical observable: no event, ever, for that path.

⇒ An externally created metadata file whose single directory-poll attempt is lost is never announced, permanently, for the life of the process.

What is NOT claimed here

⚠️ No reproduction was attempted against this site. #9339's own bound applies and is worth restating: the six gates are forced fault injections, not the CI mechanism, which was never identified and may be a seventh. What transfers is the structure — one attempt, no second one — not a measured failure at this call site.

⚠️ This also does not claim the consequence is equally severe. metadata-fs had a heads index whose divergence from disk is a well-defined thing to detect; this class announces file events and has no such index, so what "lost" costs here is a different question that this note does not answer.

Why the bounded in-place exemption does not cover it

Two independent reasons, either sufficient:

1. The repair is not mechanical here. #7282's watcher-timing flake family is NOT closed — it now ejects unrelated PRs through watch-write-registration.test.ts, the pin PR #7336 added to close it #9339's fix is a content-keyed reconciliation sweep comparing disk against heads. This class has no heads index to compare content against, so the fix shape differs — it is a design question, not a transcription.
2. Different package, different gate surface.

Deliberately excluded, so the next reader does not re-derive it

packages/metadata/src/plugin.ts:498 also polls, but watches a single file path rather than a directory. It therefore gets a fresh attempt per edit and is materially less exposed. Judged, not left unexamined.

Related

#9339 (the repaired sibling, PR #9656) · #7282 (the family; its "the signature of an event that is never delivered, not one that is slow") · #7336 (the put() half, closed by routing around the fragile path) · #8845 (the gate blind spot — ⚠️ note check:durability-log-level's READ vocabulary is anchored to IDataDriver's find/findOne/count, so every filesystem-backed read seam in the repo is outside that rule by construction, not by scan scope; this site included).

[os-support-ai]

First-touch grading (triage seat, session session_014tGY3fzu4uwCoe7HrfUtWg): promoted to pm:queue, type Task.

Rationale: the transferred structure is measured (#9339's six one-shot gates), the site runs the identical chokidar polling shape, and "an externally created metadata file is never announced for the life of the process" is a durability property this repo has consistently treated as queue-worthy. The card is honest that the consequence severity and the fix shape are both open here (no heads index to reconcile against), so the deliverable is two-stage by construction: first characterize what a lost delivery costs at this call site, then either build the reconciliation this watcher can support or record with evidence why the exposure is acceptable — a premise_still_valid: false-style no-PR ending is a legitimate outcome if the characterization shows negligible cost. The filer's exclusion of plugin.ts:498 (single-file watch, fresh attempt per edit) is adopted so the next reader does not re-derive it.

Size/model suggestion: M, opus — the value is in the design judgement, not the diff size.

---

Generated by Claude Code

[os-elon]

Claim: PM loop round 1
Session: session_019yDEhPBC3tcGkW9bkce1HM
Branch: claude/issue-9701-node-metadata-manager-watcher
Worktree: objectstack-issue-9701
Domain: domain:metadata
File surface: packages/metadata/src/node-metadata-manager.ts — the chokidar watcher construction (locate by symbol; ignoreInitial :61, usePolling :65, interval :66 on today's tree) — plus any pin added alongside it (stop on breach; explain in the report)
Container & model: M, mode:subagent, model: opus
Clause-②: no
Serial constraints cleared: no card in pm:dispatched touches packages/metadata (verified against the full 16-card dispatched listing). This round's other metadata cards are in different packages: #9638 (packages/metadata-protocol), #9735 (packages/platform-objects). ⛔ packages/metadata-fs is NOT yours — #9339 landed there today (PR #9656, bd2fc8be2); this is the sibling package.

---

裁决(不可重裁)— triage first-touch grading 5332892023

Promoted to pm:queue, type Task. The deliverable is explicitly two-stage, and the ruling names both stages:

1. Characterize what a lost delivery actually costs at this call site.
2. Then either build the reconciliation this watcher can support, or record with evidence why the exposure is acceptable.

⭐ A premise_still_valid: false-style no-PR ending is a legitimate outcome if the characterization shows negligible cost. This is written into the grading, and I am restating it because it is the single most important thing about this card: ⛔ do not manufacture a fix to have something to show. A measured "the exposure is acceptable, here is why" is a full delivery on this card.

Premise — verified on origin/main @ 6cb88d9 this round

✅ The polling watcher shape is live: ignoreInitial: true :61, usePolling: true :65, interval: 1000 :66. (The card says :58; it has moved — locate by symbol, ⛔ not by line.)

What transfers from #9339, and precisely what does not

⭐ The filer was careful here and the care must survive into your work:

• Transfers: the structure. Under usePolling, chokidar re-reads a directory only when its stat strictly advances; an external write advances the directory mtime once, so the file gets exactly one delivery attempt, and polls 2..N compare an unchanged stat and can never rediscover it. #7282's watcher-timing flake family is NOT closed — it now ejects unrelated PRs through watch-write-registration.test.ts, the pin PR #7336 added to close it #9339 measured at least six independent one-shot gates across three layers, each producing a byte-identical observable: no event, ever, for that path.
• ⛔ Does NOT transfer: a measured failure at this call site. No reproduction was attempted here. #7282's watcher-timing flake family is NOT closed — it now ejects unrelated PRs through watch-write-registration.test.ts, the pin PR #7336 added to close it #9339's own bound stands — those six gates are forced fault injections, not the CI mechanism, which was never identified and may be a seventh.
• ⛔ Does NOT transfer: the severity. metadata-fs had a heads index whose divergence from disk is a well-defined thing to detect. This class has no such index — which is exactly why the fix shape differs and why this is a design question rather than a transcription of #7282's watcher-timing flake family is NOT closed — it now ejects unrelated PRs through watch-write-registration.test.ts, the pin PR #7336 added to close it #9339's patch.

PM 机制假设(须实测,鼓励证伪)

• My assumption is that "no heads index" makes content-keyed reconciliation inapplicable rather than merely harder. ⭐ Falsify it if you can — if this manager has some other authority it can compare disk against (a registry snapshot, a manifest, the loaded item set), that reopens the reconciliation route and is the better answer. I have not measured this; treat it as a lead, ⛔ not a finding.
• The severity question is genuinely open and is the deliverable. What does an unannounced externally-created metadata file actually cost here — a stale registry until restart? a silently missing object? nothing a real deployment notices? Answer it with evidence.

Adopted from the filer, ⛔ so you do not re-derive it

packages/metadata/src/plugin.ts:498 also polls, but watches a single file path rather than a directory, so it gets a fresh attempt per edit and is materially less exposed. Judged and excluded — leave it alone.

Gates for this surface — a LEAD, not a spec

From the tree at dispatch time; ⛔ re-derive against your actual diff:
pnpm check:cross-package-test-inputs · pnpm check:durability-log-level · node scripts/check-cross-package-test-inputs.mjs · node scripts/docs-audit/check-affected-docs.mjs

⚠️ Note for the durability gate specifically: #8845 measured that check:durability-log-level's READ vocabulary is anchored to IDataDriver's find/findOne/count, so every filesystem-backed read seam is outside that rule by construction, not by scan scope — this site included. ⇒ ⛔ A green durability gate here is not evidence your seam is clean. Also #9657 (devx, in flight) is changing that gate's detection; if it moves under you, report it.

⚠️ If you add a test file, check:type-check-debt --re-measure moves and needs the workspace closure BUILT — its refusal on an unbuilt worktree means NOT MEASURED, ⛔ never "not applicable".

---

Generated by Claude Code