iw start should run a project-declared worktree init hook before handing over the worktree #526

New issue

Open

opened 2026-09-04 19:33:38 +00:00 by mph · 1 comment

mph commented

2026-09-04 19:33:38 +00:00

Owner

Found triaging MEDECA-377. This prevents a whole class of silent wrong-target failures, rather than documenting each one.

THE PROBLEM
A new worktree is handed over in a state where every port-derived value collides with its siblings. In this project dev-env.sh derives HTTP/Vite/Akka/Mongo/MySQL ports AND the docker VOLUME_SUFFIX from a .port-offset file — but nothing creates that file, so a fresh worktree silently binds the base ports and shares another worktree's database volumes.

WHAT IT COSTS
Three separate incidents in one issue's LESSONS.md, all the same root cause, all green-but-wrong rather than failing loudly:

Integration and E2E runs passed for hours against a sibling worktree's Mongo on the base port. The first honest integration result of the phase came only after the offset was created by hand mid-phase and the sbt server restarted.
A .share-db sibling legitimately holds the base DB ports, so 'docker ps shows the port taken' does not even mean somebody forgot their offset — the failure is ambiguous as well as silent.
Because sbtn's server keeps the environment it was FIRST started with, an offset created after the server started does not reach forked test JVMs at all; the wrong-database runs keep passing until someone thinks to shut the server down.

The current mitigation is prose in the project's CLAUDE.md telling the reader to check ss -ltn and docker ps, and to re-check on every DB-backed run because the check expires. That is a warning a human must remember at the exact moment they are least likely to — and warnings accrete: this project's port section is now three paragraphs long and still prevents nothing.

PROPOSED FIX
Give 'iw start' (and 'iw open' when it creates) a project-declared post-create hook — e.g. an executable .iw/worktree-init.sh, or an init command in .iw/config.conf — run inside the new worktree before the workspace is handed over, with the issue id available to it. A project that needs no setup declares none and nothing changes.

This project's hook would be a few lines: write .port-offset from the issue number, then bring up the databases on the resulting ports. Every value downstream — ports, volume names, the E2E baseUrl — is already derived from that one file, so writing it at creation time closes the whole class.

WORTH CONSIDERING ALONGSIDE
'iw doctor --env' could check the invariant directly: this worktree has an offset, and the ports dev-env.sh prints are the ports actually bound by this worktree's own containers. That turns the expiring manual check into something runnable.

NOTE ON #525: that issue is an accidental probe filed from this same session while diagnosing a Mill crash in 'iw feedback' — please close it. The crash is real and reproducible-ish: the first invocation died with 'Error: Mill failed to resolve core.jar' and 'Worker wire broken, worker likely crashed'; an immediate retry succeeded. Worth a look on its own.

Type: feature
Filed from: /home/mph/Devel/projects/medeca-modul-poptavky-MEDECA-377 on branch MEDECA-377

Found triaging MEDECA-377. This prevents a whole class of silent wrong-target failures, rather than documenting each one. THE PROBLEM A new worktree is handed over in a state where every port-derived value collides with its siblings. In this project dev-env.sh derives HTTP/Vite/Akka/Mongo/MySQL ports AND the docker VOLUME_SUFFIX from a .port-offset file — but nothing creates that file, so a fresh worktree silently binds the base ports and shares another worktree's database volumes. WHAT IT COSTS Three separate incidents in one issue's LESSONS.md, all the same root cause, all green-but-wrong rather than failing loudly: - Integration and E2E runs passed for hours against a sibling worktree's Mongo on the base port. The first honest integration result of the phase came only after the offset was created by hand mid-phase and the sbt server restarted. - A .share-db sibling legitimately holds the base DB ports, so 'docker ps shows the port taken' does not even mean somebody forgot their offset — the failure is ambiguous as well as silent. - Because sbtn's server keeps the environment it was FIRST started with, an offset created after the server started does not reach forked test JVMs at all; the wrong-database runs keep passing until someone thinks to shut the server down. The current mitigation is prose in the project's CLAUDE.md telling the reader to check ss -ltn and docker ps, and to re-check on every DB-backed run because the check expires. That is a warning a human must remember at the exact moment they are least likely to — and warnings accrete: this project's port section is now three paragraphs long and still prevents nothing. PROPOSED FIX Give 'iw start' (and 'iw open' when it creates) a project-declared post-create hook — e.g. an executable .iw/worktree-init.sh, or an init command in .iw/config.conf — run inside the new worktree before the workspace is handed over, with the issue id available to it. A project that needs no setup declares none and nothing changes. This project's hook would be a few lines: write .port-offset from the issue number, then bring up the databases on the resulting ports. Every value downstream — ports, volume names, the E2E baseUrl — is already derived from that one file, so writing it at creation time closes the whole class. WORTH CONSIDERING ALONGSIDE 'iw doctor --env' could check the invariant directly: this worktree has an offset, and the ports dev-env.sh prints are the ports actually bound by this worktree's own containers. That turns the expiring manual check into something runnable. NOTE ON #525: that issue is an accidental probe filed from this same session while diagnosing a Mill crash in 'iw feedback' — please close it. The crash is real and reproducible-ish: the first invocation died with 'Error: Mill failed to resolve core.jar' and 'Worker wire broken, worker likely crashed'; an immediate retry succeeded. Worth a look on its own. --- **Type:** feature **Filed from:** `/home/mph/Devel/projects/medeca-modul-poptavky-MEDECA-377` on branch `MEDECA-377`

mph referenced this issue

2026-09-04 19:33:58 +00:00

test #525

mph added the

needs-human

label

2026-09-04 23:03:10 +00:00

mph commented

2026-09-04 23:03:10 +00:00

Author

Owner

Intake: needs-human
Workflow: waterfall
Reason: 8 open CLARIFY markers (G1); the independent analysis review also returned unsound (G7)
Analysis: project-management/issues/IW-526/analysis.md on branch IW-526

Intake: needs-human Workflow: waterfall Reason: 8 open CLARIFY markers (G1); the independent analysis review also returned unsound (G7) Analysis: project-management/issues/IW-526/analysis.md on branch IW-526

mph referenced this issue

2026-09-11 18:18:30 +00:00

viteBuild takes WEBAWESOME_NPM_TOKEN from the Mill daemon, so a daemon started without it breaks dashboard builds in a fresh worktree #544

mph referenced this issue

2026-09-11 18:18:59 +00:00

feat(start): a worktree builds its search index when its main checkout has one #545