fix(native-playground): adopt a hard-linked catalog winner while its staging link is still present by ScriptedAlchemy · Pull Request #377 · ScriptedAlchemy/agent-bundle

ScriptedAlchemy · 2026-09-03T05:34:26Z

Summary

Root-causes and fixes the one-off main CI failure on the #364 merge run (run 33715395180, Node 24):
native-playground-service.test.ts > fsyncs durable catalog publication, validates a no-replace winner, … → Native Playground catalog snapshot is invalid. at #readSidecar (the nlink !== 1 guard), reached from #persistSnapshot → #snapshotReceipt on the loser side of the two-service race.

Root cause. Hard-link publication (link(stage, sidecar) then unlink(stage)) leaves the sidecar legitimately doubly linked between the winner's link() and the unlink of its .stage- file (the directory fsync sits inside that window, so it widens under I/O load). A loser that lost the link() race — or any reader arriving in that window — hit the singly-linked guard and rejected the winner instead of adopting it.

Fix (no retries, no timing, no masking). The extra link is accounted for by identity: a same-epoch staging sibling that shares the sidecar's dev/ino explains it, or — if the staging file vanished while the directory was being listed — the still-open handle now reports a single link. Any other extra hard link is still rejected as aliasing. Rollback paths (allowMultipleLinks) are unchanged.

Evidence

Deterministic reproduction: new test gates the winner's staging remove() behind a promise so the loser reads while nlink === 2. Before the fix it fails with the exact CI error/frame (#readSidecar line 1026); after the fix the loser adopts the winner, both catalogs are equal, and no .stage- file survives.
Aliasing regression test: a sidecar hard-linked to alias.json, .epoch-other.stage-alias, or .<epoch>.staged is still rejected with catalog snapshot is invalid.
native-playground-service.test.ts 20× loop while pnpm test:unit ran concurrently: 20/20 green (35 tests each).
pnpm build, pnpm typecheck, pnpm lint, pnpm test:unit (2668 passed), pnpm test:projection: green.
pnpm test:route-unit: one unrelated lifecycle-replay.test.ts 5 s timeout on a box at load average ~110 (other lanes running); not touched by this change.
pnpm test:integration:run: 937/938; the single failure is host-install-proof.test.ts Codex manifest keys now including logo (pre-existing from fix(adapters): third-wave review findings (#346/#350/#352/#354/#357/#358) #364, real-host install only).

Test plan

New deterministic linked-winner test red before / green after
New hard-link aliasing rejection test
20× file loop under load green
Unit / route-unit / projection / typecheck / lint
CI green on this PR

changeset-bot · 2026-09-03T05:34:31Z

🦋 Changeset detected

Latest commit: 34b8782

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

This PR includes changesets to release 1 package

Name	Type
agent-bundle	Patch

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

chatgpt-codex-connector · 2026-09-03T05:34:39Z

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-03T05:37:50.670293Z	`a0d7b0d`	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

pkg-pr-new · 2026-09-03T05:36:50Z

npm i https://pkg.pr.new/ScriptedAlchemy/agent-bundle@377

npm i https://pkg.pr.new/ScriptedAlchemy/agent-bundle/create-agent-bundle@377

npm i https://pkg.pr.new/ScriptedAlchemy/agent-bundle/@agent-bundle/runtime@377

commit: 34b8782

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a0d7b0de94

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-09-03T05:37:48Z

+      if (!entry.startsWith(stagingPrefix)) continue;
+      try {
+        const staged = await lstat(join(directory, entry));
+        if (staged.isFile() && sameFile(staged, metadata)) return true;


Wait for publication before adopting the staged inode

When the winning publisher fails its directory fsync or staging-file cleanup after link(), its staging link is still present while #persistSnapshot proceeds to roll the sidecar back. A concurrent catalog() or publishCatalogSnapshot() now returns successfully here and caches an accepted snapshot, after which the owner can remove the sidecar during rollback; the successful reader therefore exposes an epoch whose supposedly persisted catalog no longer exists, and a later restart may rediscover different eval configuration. Treat the matching staging link as an in-progress publication and only accept the sidecar after it becomes singly linked and stable.

Useful? React with 👍 / 👎.

Fixed on main in #408 (a00273b): #readSidecar now treats a doubly linked sidecar with a matching .<epoch>.stage-* sibling as a publication in progress. It polls the open handle until it is singly linked and the sidecar path still names that inode (accept), or the path was withdrawn/replaced (return to discovery, never cache), and rejects a staging link that has not settled within 5 s. Tests: the linked-winner test now asserts the reader stays pending until the staging link is released; a new test stalls the winner's staging cleanup, fails it, and verifies the reader never adopts the rolled-back inode and republishes its own singly linked sidecar.

…staging link is still present Hard-link publication leaves the sidecar doubly linked between the winner's link() and the unlink of its .stage- file. A loser (or any reader) arriving in that window hit the nlink !== 1 guard in #readSidecar and failed with "Native Playground catalog snapshot is invalid." — the main CI flake on the #364 merge run (Node 24). Account for the extra link by identity: a same-epoch staging sibling sharing dev/ino, or the open handle reporting nlink 1 once the staging file is gone. Other extra hard links stay rejected. Adds a deterministic gate-ordered reproduction and an aliasing regression test.

#379/#385/#390 - dev: lease the adopted epoch in EpochAdoptionPolicy until replaced or closed; select the contract-matrix target from the server's own target list; apply the session timeout per matrix request; observe lifecycle progress through the session trace via a new ContractMatrixClient.observeProgress seam (#385) - playground: wait for a hard-link catalog publisher to release its staging link before adopting the sidecar; return to discovery when the publication is rolled back (#377) - build: run the Agent Plugins byte lane over portable/ during ordinary artifact validation; reject every forbidden control character in header values (#373) - events/hooks: Codex PostToolUse accepts any present JSON tool_response (#378) - api: project only contract fields of adapter capability rows in inspect (#390) - tests/support: digest the real Claude home in the live session guard; isolate USERPROFILE alongside HOME (#374) - docs: Claude plugin-root cwd exception, parked-pin trigger independence, provider typing contract, portable validation moments (#368/#379/#382/#373)

/#379/#385/#390) (#408) * fix: address late review threads on merged PRs #368/#373/#374/#377/#378/#379/#385/#390 - dev: lease the adopted epoch in EpochAdoptionPolicy until replaced or closed; select the contract-matrix target from the server's own target list; apply the session timeout per matrix request; observe lifecycle progress through the session trace via a new ContractMatrixClient.observeProgress seam (#385) - playground: wait for a hard-link catalog publisher to release its staging link before adopting the sidecar; return to discovery when the publication is rolled back (#377) - build: run the Agent Plugins byte lane over portable/ during ordinary artifact validation; reject every forbidden control character in header values (#373) - events/hooks: Codex PostToolUse accepts any present JSON tool_response (#378) - api: project only contract fields of adapter capability rows in inspect (#390) - tests/support: digest the real Claude home in the live session guard; isolate USERPROFILE alongside HOME (#374) - docs: Claude plugin-root cwd exception, parked-pin trigger independence, provider typing contract, portable validation moments (#368/#379/#382/#373) * fix(dev): lease before publishing contract status; align fixtures with the portable byte lane - EpochAdoptionPolicy acquires the epoch lease before publishing a passed dev.contract.status and announces adoption synchronously with it, so a status reader never sees "passed" for an epoch that is not yet adopted - hooks.test: Codex PostToolUse accepts a string tool_response and rejects a missing one; Claude keeps the object check - mcp-session-service/public-api-packed fixtures: Agent Plugins forbids placeholders in headers and non-bare/non-./ commands, and ordinary artifact validation now enforces the standard, so the fixtures carry a literal header and a bare `node` command * chore(changeset): drop the Codex tool_response bullet already released by #404 * fix(playground,test): withdraw a failed catalog publication before releasing its staging link; bind custom observeProgress - #persistSnapshot rolls the sidecar back while the staging link still exists when the post-link directory fsync fails, so a concurrent reader keeps seeing an in-progress publication until the path is withdrawn instead of adopting a briefly singly linked file - contractProgressObserver invokes a client's observeProgress method with the client as receiver * chore(changeset): one-paragraph summary ending with the PR reference * fix(playground): recover a catalog staging link abandoned by an exited publisher After the settle deadline, a matching .stage-<pid>-* link whose publisher pid no longer exists is an abandoned publication of an already fsynced sidecar: withdraw the orphan and adopt the sidecar instead of rejecting the epoch forever. A live publisher's staging link is still never yanked. Adds the @internal catalogStagingSettleDeadlineMs seam for deterministic tests. * fix(playground): fsync the catalog directory after withdrawing an abandoned staging link * fix(dev): forward request _meta (progress token) through McpSession and the dev matrix client Lifecycle fixtures pass their generated progressToken as params._meta; the session adapter and McpSession.callTool dropped it, so generated routes never enabled sendProgress and every progress-gated lifecycle fixture failed the dev matrix. McpSessionToolCallOptions and McpClient.callTool now carry _meta. * fix(dev,playground): restart the adoption drain after a handoff race; keep the staging link when a sidecar rollback fails - EpochAdoptionPolicy reschedules its drain from the completion handler when a candidate arrived between the loop's last empty check and #processing being cleared, and settled() waits through restarts - #persistSnapshot releases the staging link after a failed publication only once the owned sidecar is confirmed withdrawn, so a rollback failure never leaves a singly linked sidecar for readers to adopt * ci: retrigger checks for the rebased head * chore: drop the portable byte-lane changes superseded by #406; keep the _meta assertions * fix(playground): restore the staging guard when a recovery fsync fails * fix(playground): accept a concurrently restored staging guard (EEXIST aliasing the sidecar) during recovery * fix(dev): recheck supersession after the adoption lease settles * fix(playground): keep a fresh pid-owned guard when recovery can neither re-link nor withdraw the sidecar * fix(playground): fsync every compensating recovery guard before trusting it

chatgpt-codex-connector Bot reviewed Sep 3, 2026

View reviewed changes

ScriptedAlchemy force-pushed the fix/main-hygiene branch from a0d7b0d to 34b8782 Compare September 3, 2026 05:53

ScriptedAlchemy merged commit 605cfe3 into main Sep 3, 2026
9 checks passed

ScriptedAlchemy deleted the fix/main-hygiene branch September 3, 2026 06:18

ScriptedAlchemy mentioned this pull request Sep 3, 2026

fix: address late review threads on merged PRs (#368/#373/#374/#377/#378/#379/#385/#390) #408

Merged

2 tasks

ScriptedAlchemy mentioned this pull request Sep 3, 2026

fix(routes): reject same-server MCP App resourceUri collisions with AB4829 and sweep orphaned Playground staging files #430

Merged

4 tasks

Navigation Menu

fix(native-playground): adopt a hard-linked catalog winner while its staging link is still present - #377

fix(native-playground): adopt a hard-linked catalog winner while its staging link is still present#377
ScriptedAlchemy merged 1 commit into
mainfrom
fix/main-hygiene

ScriptedAlchemy commented Sep 3, 2026

Uh oh!

changeset-bot Bot commented Sep 3, 2026 •

edited

Loading

Uh oh!

chatgpt-codex-connector Bot commented Sep 3, 2026 •

edited

Loading

Uh oh!

pkg-pr-new Bot commented Sep 3, 2026 •

edited

Loading

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot Sep 3, 2026

Uh oh!

ScriptedAlchemy Sep 3, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

ScriptedAlchemy commented Sep 3, 2026

Summary

Evidence

Test plan

Uh oh!

changeset-bot Bot commented Sep 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

chatgpt-codex-connector Bot commented Sep 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codex Review Summary

Uh oh!

pkg-pr-new Bot commented Sep 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Sep 3, 2026

Choose a reason for hiding this comment

Uh oh!

ScriptedAlchemy Sep 3, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

changeset-bot Bot commented Sep 3, 2026 •

edited

Loading

chatgpt-codex-connector Bot commented Sep 3, 2026 •

edited

Loading

pkg-pr-new Bot commented Sep 3, 2026 •

edited

Loading