feat(learner): collapse cross-OS duplicate projects in the registry

[Sergio-LPA]

Problem

The per-project id is sha256(remote || root). For a project with no git remote, the id is derived from the root — which differs per OS:

• macOS/Linux: /Users/me/Proj
• Windows: C:/Users/Me/Proj

So the same project gets a different id on each machine. When the registry (_sinapsis-projects.json) is shared across machines — e.g. a Nextcloud/Dropbox/iCloud-synced ~/.claude — that one project shows up as two entries, duplicating it in /projects, /eod, and cross-project instinct search.

Projects with a remote are unaffected (the remote is identical across machines, so the id already matches).

Fix

Match on a cross-OS-stable key instead of the raw id: the git remote when present, otherwise the project name. The two sightings then collapse into a single entry:

• each per-OS id is preserved in aliases[] (so future sessions resolve without a re-scan)
• each observed root is stored under roots.{posix,windows}
• the remote key takes precedence over the name, so two genuinely different projects that happen to share a folder name never merge

The change is purely additive — aliases, roots and crossKey are new optional fields; existing readers that don't use them are unaffected. Behaviour for remote-backed projects is unchanged.

Tests

New tests/test-crossos-registry.sh — 5 hermetic tests driving the real hook via a sandbox HOME:

1. two-OS, no-remote sighting collapses into one entry
2. both roots.posix and roots.windows recorded
3. the second per-OS id registered as an alias
4. remote key beats name (same-named distinct projects stay separate)
5. idempotent on re-run

Existing suites re-run clean:

• test-install-upgrade 21/21
• test-registry-isolation 4/4
• test-eod-gather 8/8

Notes

• The name-based fallback could, in theory, merge two different projects that share a folder name across machines and have no remote on either. The remote key takes precedence to minimise this; documented in the code comment.
• Context: surfaced on a real Mac + Windows setup syncing ~/.claude via Nextcloud, where non-git folders (the same logical project) appeared twice in /eod. Follow-on to the v4.5.1 cross-OS /eod work.

[Luispitik]

The diagnosis is right and in scope: project ids are sha256(remote || root), so a no-remote project gets a different id per OS and duplicates in synced registries. The diff applies clean on v4.6.1 and the new code is safe (no eval, execFileSync with args). But I reproduced three functional problems by running the patched hook, so this needs another iteration:

1. Same-machine false merge (regression, data loss). Two different no-remote projects that share a folder name on the same machine (think clientA/scripts and clientB/scripts) collapse silently into one entry, and one root disappears from the registry (roots.windows overwritten — same os-family). Reproduced with the real hook. /eod resolves roots by name, so it would attribute git commits to the wrong project. Fix: only collapse by name when the os-family actually differs, e.g.

   registry.projects.find(p => p && p.crossKey === crossKey && p.root && projectRoot
     && osFamily(p.root) !== osFamily(projectRoot))

2. Pre-existing duplicates never merge. The lookup matches by id first, so a registry that already contains both entries (the synced-via-Nextcloud scenario that motivates this PR) keeps both forever — each machine just updates its own entry. Reproduced. Add a post-upsert migration pass that merges entries with identical crossKey (union of aliases/roots, oldest created, newest last_seen) — or hook it into _dream.sh hygiene. As written, the PR only prevents future duplicates from a clean registry; it doesn't cure the reported symptom.
3. The new test fails on Windows Git Bash (suite exit 1; 1 of the 5 cases): MSYS converts the posix fixture path /Users/tester/CrossProj passed as argv into C:/Program Files/Git/Users/..., so roots.posix never registers. Export MSYS_NO_PATHCONV=1 / MSYS2_ARG_CONV_EXCL='*' at the top of the test, or pass fixture paths via env vars instead of argv. Also drop the || r.projects[0].id==='bbbbbbbbbbbb' clause in test 3 — as written it passes even when the posix run was never processed, which is exactly what happens on Git Bash today.

Please also:

• Add an anti-regression test: two same-name no-remote projects with different roots in the same os-family must stay 2 entries.
• Teach the consumers about aliases: commands/projects.md (step 3) should also count observations from homunculus/projects/{alias}/; _eod-gather.sh should register aliases in its registry[] map (for (const a of p.aliases||[]) registry[a] = {name:p.name, root:p.root}).
• Document the known asymmetry in a code comment: if remote detection fails on one machine (git not on PATH for execFileSync), that sighting falls back to a name: crossKey and won't match the remote: entry — duplicate persists.

Good direction — with the cross-OS restriction and the migration pass this becomes a clean merge. Windows Git Bash compatibility is non-negotiable in this repo (it's where most users hit bugs).

[Sergio-LPA]

Hola Luis, ¿pudiste echarle un ojo a este PR? Lo llevo corriendo en local desde principios de junio (Mac y PC Windows con el registry compartido por Nextcloud) sin ningún problema, y la regresión de upstream me salió verde (install 21/21, registry-isolation 4/4, eod-gather 8/8).

Si le ves algo raro o prefieres otro enfoque para el aliasing de roots, me dices y lo ajusto. Sin prisa 🙂

[Luispitik]

The cross-OS diagnosis is correct and the hermetic test harness (real hook, sandbox HOME, no mocks) is exactly how this repo tests — thank you. One design flaw blocks the merge as-is:

The name-key fallback merges two genuinely different projects — and not only across machines. crossKey = "name:" + projectName matches ANY other no-remote project with the same folder name, including on the same machine: ~/work/app and ~/personal/app (both no remote) get different ids (roots differ), but the second sighting finds the first entry via crossKey === "name:app" and collapses them — aliases them together, overwrites root/roots.posix, and from then on /projects, /eod and cross-project search treat two projects as one. Your Notes section flags the cross-machine variant as theoretical; the same-machine variant is the common case (demo, test, scratch, api…), and a false merge is worse than the duplicate it replaces — a duplicate is cosmetic, a merge corrupts the registry.

Suggested fix — restrict the name-key match to the actual cross-OS scenario: only accept a crossKey name match when the candidate root's OS family is NOT already recorded on the entry, e.g.:

|| (crossKey !== "name:" ? registry.projects.find(p => p && p.crossKey === crossKey
     && !(p.roots && p.roots[osFamily(projectRoot)])
     && osFamily(p.root || "") !== osFamily(projectRoot)) : null)

That still collapses the Mac+Windows sighting you're targeting (families differ), but two same-family same-name projects stay separate. Please add the regression test: two same-named no-remote projects on the SAME OS remain 2 entries.

Also needed after the fix:

1. Rebase onto v4.6.2 — main now routes registry reads through a BOM-safe readJson() in _session-learner.sh (#25); your hunk sits right below it.
2. Register tests/test-crossos-registry.sh in .github/workflows/tests.yml — the suite list is explicit, new suites don't run otherwise.
3. Minor: osFamily classifies Git-Bash /c/... as windows but observe_v3.py normally emits C:/... cwds — fine, just add one test line covering the /c/ branch since you handle it.

Happy to merge once the name-key guard is in.

[Sergio-LPA]

Hecho todo lo de la review, Luis:

• Guard cross-OS en el name-key: el fallback por nombre ahora solo matchea cuando la familia de SO del root difiere Y la entrada no tiene ya un root de mi familia registrado (tu snippet, con early-return para las keys remote:). Dos proyectos homónimos sin remote en la misma máquina quedan separados — test de regresión incluido, con assert de que ninguno de los dos roots se pisa.
• Pasada de migración post-upsert: cura los duplicados pre-existentes (el síntoma del registry sincronizado que motivó el PR). Merge por crossKey bajo el mismo guard de familias que el lookup, unión de aliases/roots, created más viejo, last_seen más nuevo. Con backfill de crossKey para entradas legacy, así los registries escritos antes de la feature también se curan.
• Consumers con aliases: _eod-gather.sh resuelve ids aliased al proyecto fusionado, y commands/projects.md suma las observaciones de cada homunculus/projects/{alias}/.
• Asimetría documentada en comentario en el código: si la detección de remote falla en una máquina, ese sighting cae a key name: y no matchea la entrada remote: — el duplicado persiste hasta que el key upgrade lo cura.
• Git Bash: MSYS_NO_PATHCONV=1 + MSYS2_ARG_CONV_EXCL='*' al principio de la suite, fuera la cláusula || id==='bbbb...' del test 3 (el assert del alias ahora es estricto), y test nuevo cubriendo el branch /c/ de osFamily.
• Rebase sobre v4.8.1 (el hunk asienta sobre el readJson BOM-safe) y suite registrada en .github/workflows/tests.yml.

La suite queda en 10 casos, 10/10 en local (Linux). Re-corridas las afectadas, todas en verde: install-upgrade 21/21, registry-isolation, eod-gather, bom-decay-python, v45-opus47 y v46-opus48.

[Luispitik]

Gracias, Sergio, y perdona la espera — abriste esto el 2 de junio y te he tenido dos ciclos de review con semanas de por medio. La segunda tanda la resolviste entera y bien: el guard cross-OS en el name-key era exactamente lo que pedía.

Lo he verificado por mi cuenta ejecutando el hook real, no leyendo el diff. El caso que me preocupaba queda cerrado:

C:/work/app  +  C:/personal/app   (misma maquina, sin remote)  ->  2 entradas

Y el Test 6 que añadiste cubre justo eso. La pasada de migración también hace lo que dice: fusiona duplicados preexistentes con unión de roots/aliases, created más antiguo y last_seen más reciente.

Una cosa que no viste, y es culpa mía

El CI de este PR no ha llegado a ejecutarse nunca. Al venir de un fork y tocar .github/workflows/tests.yml, GitHub lo dejó en action_required esperando mi aprobación, y yo no la di. total_count=0: cero checks en todo el PR. Por eso el estado salía UNSTABLE — no había ningún test en rojo, no había ningún test.

Ya lo he aprobado. Y al correr tu suite en Windows con Git Bash me salió esto:

Error: ENOENT: no such file or directory,
open 'C:\tmp\tmp.GIvov0rIIO\.claude\homunculus\projects.json'

=== Results: 0 passed, 10 failed ===

La causa es fina: MSYS_NO_PATHCONV=1 está exportado para toda la suite (bien puesto, hace falta para que los fixtures posix no se conviertan), pero newhome() sigue usando mktemp -d, que devuelve /tmp/.... Con la conversión desactivada, node —que es un binario Windows nativo— resuelve eso a C:\tmp\..., que no existe. Es decir: el propio fix de Git Bash es el que rompe la suite en Git Bash.

Nada de esto toca la lógica de producto, que es correcta. Lo comprobé a mano con un HOME de estilo Windows y sale lo que tiene que salir:

{ "id": "aaaaaaaaaaaa", "crossKey": "name:crossproj",
  "roots": { "posix": "/Users/tester/CrossProj",
             "windows": "C:/Users/Tester/CrossProj" },
  "aliases": ["bbbbbbbbbbbb"] }

Si el CI hubiera corrido en junio esto habría saltado en windows-latest el primer día. Ahí el fallo es mío por no aprobarlo.

Lo que he añadido encima de tu rama

En vez de devolvértelo otro ciclo más, lo he cerrado yo. Son 82 líneas en 2 ficheros, y prefiero que les des el visto bueno:

1. newhome() — 3 líneas. Ruta nativa para node:

h=$(cd "$h" && { pwd -W 2>/dev/null || pwd; })

Con eso tu suite pasa 10/10 en Windows sin tocar nada más.

2. El falso merge cross-familia, aceptado pero visible. Tu guard cierra el caso de misma máquina, pero queda uno que no tiene solución limpia: dos proyectos no relacionados que comparten nombre de carpeta (app, api, docs) vistos desde máquinas de familias distintas sí se fusionan, porque sin remote no queda nada con que distinguirlos:

C:/work/app  +  /home/otro/personal/app  ->  1 entrada

No he querido endurecer el guard, porque lo obvio —exigir que coincida el directorio padre— rompería el caso legítimo (C:/dev/app y /Users/x/code/app son el mismo proyecto en rutas distintas), que es justo para lo que existe la feature. Así que lo he dejado como límite aceptado, pero con rastro: cada fusión por nombre sella la entrada con name_merged y guarda el par de roots en name_merge_log, más una línea en _session-learner.log. Una fusión equivocada pasa de deriva invisible a evento auditable que se deshace a mano.

Detalle que me costó un rato: el log no puede ir por stderr. El bloque node -e entero se invoca con 2>/dev/null (línea 593), así que todo lo que se escriba ahí se descarta — incluidos los mensajes de lock contention y upsert failed que ya había en el código y que no ha leído nadie nunca. Puede que merezca otro PR aparte.

Y otro: no se puede usar comilla simple literal dentro de ese bloque, cierra el string de bash. Ya lo avisa un comentario en la línea 538, pero me lo comí igual.

3. Nota sobre osFamily(). Documentado que macOS y Linux caen los dos en posix, así que mac↔linux no se deduplica. Es una consecuencia razonable del diseño, solo que no estaba escrita.

Tests: añadí 3 que fijan el comportamiento nuevo — que la fusión por nombre queda sellada, que ambos roots se registran para auditoría, y que una fusión por remote no se sella (para que el sello signifique algo). Tu suite queda en 13/13 y el repo entero en 201/201 en Windows.

Antes de mergear

Te dejo 48-72h para que le des un repaso antes de mergear, por si quieres cambiar algo. Sobre todo dos cosas: si el sello name_merged te parece el sitio correcto o preferirías que fuese solo al log, y si estás de acuerdo con aceptar el falso merge cross-familia en vez de endurecer el guard. Es tu diseño y no quiero decidirlo yo por encima.

Si no dices nada en ese plazo, lo mergeo tal cual y va en la v4.9.0 — que sale con tu feature y el #29 de @juanparisma.

Gracias otra vez por la paciencia y por dogfoodearlo dos meses en Mac y PC antes de insistir. Ese tipo de contribución es la que hace que esto funcione.

[Sergio-LPA]

Gracias por cerrarlo tú, Luis — y por cazar lo del mktemp: la ironía de que el fix de Git Bash fuese lo que rompía la suite en Git Bash es de enmarcar. El pwd -W es la solución buena.

A tus dos preguntas:

1. name_merged en la entrada: sí, déjalo donde lo has puesto. Lo pensé con mi caso real: el registry viaja sincronizado entre máquinas, el _session-learner.log no (y rota). Si una fusión equivocada se hace en el PC y yo estoy mirando desde el Mac, el sello en la entrada es lo único que llega hasta donde estoy mirando. Solo-log sería auditoría que se queda en la máquina equivocada.

2. De acuerdo con aceptar el falso merge cross-familia. Sin remote no queda señal fiable, y exigir parent-dir igual mataría justo el caso para el que existe la feature. Con el sello, el coste del error pasa de deriva silenciosa a un name_merge_log que se deshace a mano. Trade-off correcto.

Un dato de campo sobre la nota de osFamily(): mi setup real ya es de tres máquinas (Mac + Windows + un contenedor Linux), así que el límite mac↔linux me toca de lleno — hoy lo cubro con un patch local con mis rutas hardcodeadas. No lo pido para este PR, pero si te encaja lo exploro como follow-up (¿familias por heurística /Users/ vs /home/, o bases configurables?).

Y me apunto el otro follow-up que mencionas: el 2>/dev/null de la línea 593 tragándose el stderr del learner desde siempre. Te abro PR aparte con eso.

Por mí, mergea cuando quieras. Gracias por el tiempo de las reviews — se nota el cuidado.

[Luispitik]

Mergeado. Gracias, Sergio.

Tus dos respuestas cierran el diseño, y me quedo sobre todo con el argumento del sello: el registry viaja sincronizado entre máquinas y el _session-learner.log no. Yo lo había razonado como "dónde molesta menos"; tú lo has razonado desde dónde va a estar mirando la persona cuando la fusión salga mal, que es la razón buena. name_merged se queda en la entrada.

Antes de que abras el PR del stderr: no lo abras

Ya está resuelto. Llegué a la línea 593 por mi cuenta cerrando la v4.9.0, y el fix va en esa misma release:

• Los diagnósticos del bloque node -e dejan de escribirse en stderr y se anexan a _session-learner.log.
• Con eso SINAPSIS_DEBUG=1 vuelve a servir para el 95% del script que vive dentro de ese bloque. Hasta ahora el switch de debug no producía absolutamente nada ahí, que es lo peor que puede hacer un switch de debug.
• Y los mensajes que ya existían desde siempre y no había leído nadie nunca (lock contention, upsert failed) por fin salen a algún sitio.

Perdona por dejarte apuntar el follow-up sin decirte que ya estaba en marcha. Cuando esté mergeado, si al verlo crees que se queda corto, dímelo y lo ampliamos.

El límite mac↔linux sí me interesa

Y tu setup de tres máquinas es mejor banco de pruebas para eso que el mío, así que me viene bien que lo lleves tú. Pero ábrelo como issue antes de escribir código, no como PR directo.

Las dos opciones que planteas me dan respeto por motivos distintos. La heurística /Users/ vs /home/ es frágil de una forma que no se ve hasta que falla en casa de otro: un contenedor Linux puede montar el home donde quiera, y en macOS no todo el mundo vive bajo /Users/. Y las bases configurables meten configuración en un sistema cuya gracia es precisamente no tener ninguna: si hay que declarar las rutas a mano, el usuario ya está haciendo el trabajo que la feature debería hacer por él — que es más o menos lo que ya haces hoy con tu patch local.

No digo que no haya solución, digo que la forma es la parte difícil y prefiero que la discutamos antes de que te pongas a escribir. Ya te he hecho dos ciclos de review largos con semanas de por medio; no quiero un tercero.

Gracias otra vez, y por los dos meses de dogfooding en Mac y PC antes de insistir. Va en la v4.9.0 junto con el #29 de @juanparisma.

[Luispitik]

Publicado: v4.9.0. Tu feature abre las notas de release, con tu nombre y lo que hiciste, porque es la mitad de lo que va dentro.

Dos cosas para cerrarte los cabos:

El follow-up mac↔linux ya está abierto: #32. Lo he escrito yo para que no dependa de que lo abras tú, pero está planteado como diseño, no como patch, y el port es tuyo si lo quieres — dilo ahí y es tuyo. Dentro está tu dato de campo (las tres máquinas, el patch local con las rutas a mano), el argumento de por qué la heurística /Users/ vs /home/ me da respeto, y una tercera opción que no habíamos puesto sobre la mesa: preguntarle al sistema qué es en el momento de la observación (uname, $OSTYPE) en vez de deducirlo de la ruta después. Cuesta un campo en el registry y una migración, pero deja de adivinar.

Tu trampa del mktemp ha vuelto a aparecer, en otro sitio. Al cerrar el #10 —install.sh reventando en Git Bash por lo mismo, ruta posix a un node nativo— he acabado citándote: es el mismo fallo que rompía tu suite, en el sentido contrario. La cura general es la tuya, pwd -W. Van dos veces que esto muerde en este repo, así que ya no es una anécdota.

Gracias otra vez.