fix(2113): recover incomplete use-m aliases and cleanup races

[konard]

Problem

fix --ci-cd failed while loading command-stream from a global use-m alias in three supplied production runs:

1. the alias contained src/$.mjs but lacked its relative import src/terminal-capture.mjs;
2. another run lacked src/$.trace.mjs instead;
3. after use-m@8.14.3 added corrupt-alias self-healing, repair failed while removing the alias with ENOTEMPTY.

Hive Mind's shared retry classifier did not recognize the wrapped internal ERR_MODULE_NOT_FOUND. Both use-m's new repair and Hive Mind's downstream cleanup also called recursive fsPromises.rm() with Node's default maxRetries: 0, allowing the transient cleanup race to escape.

Solution

• recognize ERR_MODULE_NOT_FOUND only when it is the cause of use-m's exact Failed to import module from ... wrapper;
• recognize use-m's exact corrupt/incomplete-alias cleanup wrapper only for Node's documented recursive-removal retry codes;
• extract or derive the whole versioned alias, remove it with recursive, force, five retries, and a 100 ms retry delay, then call use-m again;
• retain shared ensureUseM() wrapping, so every current and future use(...) call site receives the recovery;
• emit cleanup failures through the existing opt-in HIVE_MIND_USE_M_DEBUG trace instead of silently discarding them;
• add a patch changeset, regression tests, and two reusable real-filesystem experiments.

Dependency ownership and pinning

An npm pack command-stream@0.17.2 --dry-run --json audit found all 466 published entries, including src/$.mjs, src/$.trace.mjs, and src/terminal-capture.mjs; tag js-v0.17.2 agrees with the tarball. The varying absent file therefore identifies incomplete aliases, not a command-stream packaging defect. Pinning command-stream cannot prevent the same partial-install state.

Pinning use-m to 8.14.2 would remove upstream self-healing while leaving the downstream zero-retry cleanup gap. The original install problem was reported in use-m #66 and fixed by use-m PR #67. The post-release cleanup race is separately reported with the production evidence, reproduction, and suggested fix in use-m #68.

Reproduction and verification

Regression-first evidence:

• the cleanup follow-up started with 35 passing and 3 failing cases before implementation;
• node tests/test-use-with-retry.mjs — 39/39 passed after the fix;
• node experiments/issue-2113/reproduce-missing-transitive.mjs — produces the real wrapped ERR_MODULE_NOT_FOUND, removes the alias, and recovers on attempt 2;
• node experiments/issue-2113/reproduce-cleanup-race.mjs — zero-retry removal reproduces ENOTEMPTY; retry-budget removal completes without leaving the alias behind.

Final local gates:

• npm test — all 354 selected test files passed;
• npm run lint;
• npm run format:check;
• bash scripts/check-mjs-syntax.sh;
• bash scripts/check-file-line-limits.sh;
• git diff --check.

Preserved evidence

The issue #2113 case study contains all three complete supplied logs, package/release audit data, timeline, requirement map, root-cause analysis, alternatives, online/upstream research, and the preserved use-m #68 report body.

Fixes #2113

[konard]

Working session summary

Implemented and finalized the fix.

• PR ready for review: fix(2113): recover incomplete use-m aliases and cleanup races #2114
• Added narrowly scoped retry/recovery for incomplete use-m dependency trees.
• Added regression tests and a hermetic reproduction experiment.
• Preserved investigation logs, timeline, research, and root-cause analysis in the case study.
• Reported findings upstream: Failed global installs are unretried and undiagnosable (stdio: 'ignore'); corrupt alias installs are sticky link-foundation/use-m#66 (comment)
• All 354 local test files, lint, formatting, syntax, and file-limit checks passed.
• Fresh CI passed on exact head commit 50698e2a.
• Branch is pushed, synchronized, and the working tree is clean.

---

This summary was automatically extracted from the AI working session output.

[konard]

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost estimation:

• Model: GPT-5.6 Sol
• Provider: OpenAI
• Public pricing estimate: $22.660326

📊 Context and tokens usage:

• 269.7K / 200K (135%) input tokens, 23.7K / 128K (18%) output tokens

Total: (269.7K + 18.9M cached) input tokens, 23.7K output tokens, $22.660326 cost

🤖 Models used:

• Tool: OpenAI Codex
• Requested: gpt-5.6-sol
• Thinking level: low (~7999 tokens)
• Model: GPT 5.6 Sol (gpt-5.6-sol)

📎 Log file uploaded as Gist (3509KB)

• View complete solution draft log

---

Now working session is ended, feel free to review and add any feedback on the solution draft.

[konard]

✅ Ready to merge

This pull request is now ready to be merged:

• All CI checks have passed
• No merge conflicts
• No pending changes

---

Monitored by hive-mind with --auto-restart-until-mergeable flag

[konard]

https://gist.githubusercontent.com/konard/a94889ae049294cced9361c17822a140/raw/9d373db37c0f9aaca93584614f7ae8c4b47c2a36/tmp-start-command-logs-isolation-docker-b768891e-103f-4671-95b7-b875880cbc21.log.txt

After update of github.com/link-foundation/use-m I got:

https://gist.githubusercontent.com/konard/154eaf009bdf41cd722fe902cfbcb10c/raw/952db715cf19c37f8fba4ca0b959c79819857468/tmp-start-command-logs-isolation-docker-4b54d1b8-64c5-4128-ad86-232167bf45e9.log.txt

Double check also if it is related to https://github.com/link-foundation/command-stream and if we need to fix it also.

Maybe pinning to previous versions will work as a workaround, in any case if it is possible to fix, all issues must be reported to our dependencies repositories.

[konard]

🤖 AI Work Session Started

Starting automated work session at 2026-07-28T20:37:07.518Z

The PR has been converted to draft mode while work is in progress.

This comment marks the beginning of an AI work session. Please wait for the session to finish, and provide your feedback.

[konard]

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

🤖 Models used:

• Tool: OpenAI Codex
• Requested: gpt-5.6-sol
• Thinking level: xhigh (~31999 tokens)
• Model: GPT 5.6 Sol (gpt-5.6-sol)

📎 Log file uploaded as Gist (6699KB)

• View complete solution draft log

---

Now working session is ended, feel free to review and add any feedback on the solution draft.