fix(runtime): use process-owned credential-home locks

[mldangelo-oai]

Summary

Follow-up to the now-merged #611, merged with main at fa9dfa491a9ed464fbfca9481dc493784a8ef1fc.

Reused PIDs are a real recovery problem, but an expired heartbeat does not prove that the owner exited. A paused process or an older client can still be using the credential home when heartbeat expiry admits another writer. This replaces heartbeat expiry with a process-owned lock.

Changes

• Hold an exclusive SQLite transaction in the process preparing the scan runtime, using Node's or Bun's built-in SQLite. No new dependency, helper process, CLI surface, or production lock timeout.
• Keep the existing owner directory for older clients. Mark new records so an available native lock lets us reclaim them regardless of PID reuse. Preserve conservative handling of live legacy PID-only records.
• Keep the guard file between operations, validate its path and permissions, and close the connection on cancellation and acquisition/release errors.
• Replace heartbeat timer mocks with a real stalled/crashed-owner regression shared by Bun tests and the installed Node package smoke test. Bound the test holder's wait so it exits if its controller dies.
• Shorten the README's lock guidance and replace the outdated cleanup-failure comment.

Testing

Feature-head validation at 170d1d1f5826f5807ecdc75c6a240d1a9ac0be5c:

• Full Bun suite with seeds 12345 and 1267267794: 1,584 passed, 30 platform-specific or opt-in skips, and 0 failed in each run.
• Focused runtime suite: 129 passed, 11 platform-specific skips, and 0 failed.
• pnpm run types, pnpm run format, pnpm run build, and git diff --check: passed.
• Built-runtime paused-owner/crash-recovery fixture on Node 22.13.0 and Node 24.15.0: passed. The Bun runtime suite also exercises the shared fixture.
• Parent-exit probes on Node 22, Node 24, and Bun: the stalled holder exited and the native lock became available after its controller was killed. A before-change control reproduced the orphaned holder and was cleaned up afterward.

Integration validation after merging main at 0557442c1d425b45229b506cc88cc3ba2d21ae4d:

• Credential-lock runtime tests: 8 passed, 132 filtered out, and 0 failed.
• pnpm run types, pnpm run format, pnpm run build, and git diff --check: passed.
• pnpm pack --pack-destination ../../dist followed by pnpm run test:package: passed on Node 22.13.0, including the installed-package credential-lock regression.

Risk and rollout

Stop operations using the heartbeat-only implementation before upgrading. Those clients do not participate in the native lock and can still steal a paused owner's directory, with or without a compatibility heartbeat.

Legacy PID-only records cannot safely distinguish a live owner from a reused PID, so ambiguous records still require manual recovery after stopping all operations using the home. The persistent SQLite guard must not be removed while operations are running. Node 22 emits its built-in SQLite experimental warning; the supported Node range is unchanged. Cross-platform CI is required before landing.

Public disclosure review

• No customer, partner, prospect, or user identities, data, or identifying details are included.
• No credentials, personal data, private source, scan findings, or nonpublic links or tickets are included.
• I reviewed the branch name, title, description, commits, changes, comments, logs, screenshots, attachments, and links for public disclosure.

[mldangelo-oai]

@codex review

Please review current head 379a59e3f83106c4d05c479d5571086072e63a11, especially native lock lifetime, paused/crashed owners, conservative legacy PID handling, cancellation/error cleanup, and Node/Bun behavior on Windows and Unix. This is stacked on #611; the regression fixture also runs against the installed npm package.

[chatgpt-codex-connector]

Codex Review Summary

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

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-08-22T14:40:47.940599Z	0557442	Manual request
🔒 Security Review	✅ Completed 2026-08-22T08:00:06.833119Z	5ab8e68	Draft marked ready

ℹ️ 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.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 379a59e3f8

ℹ️ 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".

[mldangelo-oai]

@codex review

Please re-review current head 379a59e3f83106c4d05c479d5571086072e63a11 with the clarified rollout requirements. The code is unchanged and all 27 CI checks passed. #611 is an unmerged review base, not a release to deploy before this PR. The latest released tag (npm-v0.1.16) has PID-only locking; two-process probes with that pre-heartbeat protocol and this head waited correctly in both directions.

The PR now explicitly requires landing the corrected combined tree and stopping any heartbeat-only preview processes first. Please verify whether the mixed-version finding remains a blocker under that rollout, and check the corrected tree for any other issues. The reasoning and compatibility evidence are in the existing review thread.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Bravo.

Reviewed commit: 379a59e3f8

ℹ️ 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".

[mldangelo-oai]

@codex review

Please review rebased head 5ab8e682a90633a1731c99cd58a580f43a7c1431 against main. #611 is now merged, so this PR is no longer based on the temporary mirror. git range-diff confirms the follow-up patch is unchanged.

The runtime suite (129 passed, 11 platform skips), types, formatting, build, and the built Node 22.13 paused-owner/crash-recovery regression passed again. Please check integration with the current base and the documented requirement to stop heartbeat-only operations before upgrading.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Nice work!

Reviewed commit: 5ab8e682a9

ℹ️ 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".

[mldangelo-oai]

@codex review

Please review current head 170d1d1f5826f5807ecdc75c6a240d1a9ac0be5c, including the bounded stalled-child lifetime and shortened credential-lock documentation. Production locking behavior is unchanged.

The runtime suite passed (129 tests, 11 platform-specific skips), as did types, formatting, and build. The normal paused-owner/crash-recovery fixture passed on Node 22.13 and Node 24.15. Parent-exit probes passed on Node 22, Node 24, and Bun; a before-change control still reproduced the orphaned holder.

The broader seeded and random-order test suites and fresh CI are still running.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Keep it up!

Reviewed commit: 170d1d1f58

ℹ️ 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".

[mldangelo-oai]

@codex review

Please review current head 0557442c1d425b45229b506cc88cc3ba2d21ae4d.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Breezy!

Reviewed commit: 0557442c1d

ℹ️ 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".