[P0][Index Lock Regression] Recuperar lock órfão e impedir deep pass preso em deep_running

[wesleysimplicio]

Regression after: #176
Related: #120, #123, wesleysimplicio/simplicio-runtime#2989 e #3005

Problema medido

O mapper publicado ainda pode ficar preso indefinidamente por um .simplicio/index.lock órfão.

Reprodução em 2026-07-11, Windows, após o preflight atualizar para simplicio-mapper 0.19.0:

1. simplicio-mapper scan . --json foi executado em simplicio-agent e simplicio-runtime.
2. O comando retornou deep-pass PIDs 13204 e 15764.
3. simplicio-mapper status . --await --timeout 120 --json permaneceu:
   • phase=deep_running
   • terminal=false
   • lock=true
4. Os dois PIDs já não existiam.
5. Ambos os background-index.log continham repetidamente:
   index skipped: lock already exists at .../.simplicio/index.lock.
6. No Agent, artifacts_present=false; no Runtime, apenas artefatos anteriores/stale estavam presentes.

Resultado: o survey obrigatório não converge, inspect/handoff não pode produzir prova fresca e o usuário precisa remover lock manualmente, contrariando o contrato de #176.

Objetivo

Tornar aquisição, recuperação e liberação do lock de indexação crash-safe, cross-platform e observável, sem roubar lock de processo vivo.

Contrato proposto

Registro versionado no lock, por exemplo:

simplicio.mapper-index-lock/v1 com pid, process_start_identity, host, created_at, heartbeat_at, owner_token, root_fingerprint, mapper_version e operation.

Reason codes mínimos:

• lock_acquired
• lock_live_owner
• lock_dead_owner_reclaimed
• lock_expired_reclaimed
• lock_malformed_reclaimed
• lock_legacy_reclaimed
• lock_owner_mismatch
• worker_died_before_terminal.

Critérios de aceite

• scan/index detecta PID morto e recupera o lock automaticamente.
• PID reutilizado não é confundido com o processo original; liveness usa start identity ou equivalente robusto.
• Lock de processo vivo nunca é roubado; status retorna owner/age/operation e retry guidance.
• Lock malformed, vazio, legacy PID-only e expirado têm política determinística e reason code.
• Acquire é atômico; duas execuções concorrentes não entram no deep pass juntas.
• Release exige owner_token correspondente e não apaga lock alheio.
• Crash/kill do worker é detectado; status --await termina como failed ou recupera/reinicia conforme policy, nunca fica deep_running com PID morto.
• --timeout retorna estado terminal/timeout honesto e exit code documentado.
• Um novo scan após crash converge sem Remove-Item index.lock manual.
• Paths Unicode/long path e filesystem semantics de Windows são cobertos.
• Testes cobrem dead/live/reused PID, malformed/legacy lock, concorrência, crash antes/depois de escrever state e owner mismatch.
• Integração scan -> status --await -> inspect -> handoff passa em repositório temporário.
• Wheel/CLI instalado é testado, não somente import in-tree.
• Logs/JSON não expõem dados sensíveis e incluem evidence suficiente para diagnóstico.
• Benchmark prova que o heartbeat/liveness check não reintroduz latência relevante no macro fast path.

Evidência exigida

• fixtures de lock por caso;
• testes unit/integration cross-platform;
• transcript do kill/recovery;
• JSON status antes/depois;
• prova de dois scanners concorrentes;
• smoke com pacote publicado/instalado;
• changelog/release note da regressão.

Não objetivos

• Permitir deep passes concorrentes no mesmo root;
• apagar locks indiscriminadamente por idade;
• depender de remoção manual;
• usar apenas kill(pid, 0) POSIX como prova cross-platform;
• mascarar falha retornando artefato stale como fresco.

[wesleysimplicio]

Evidência nova — drain do Simplicio Agent (2026-07-17)

Durante a execução bounded simplicio-loop run-20260717-044710-lemslobz, o run permaneceu em phase=mapping com next_action=mapper_scan_required e sem mapper.receipt.

Reprodução observada no Windows:

1. simplicio-loop run --task .orchestrator/loop/goal-all-open-issues.md --repo . --max-iterations 64
2. O run persistiu contrato/estado, mas não avançou além de mapping.
3. .simplicio/map-job.json apontou para worker morto pid=28000, phase=macro_done, sync=false.
4. simplicio-mapper status . --json --await --timeout 10 retornou phase=failed, terminal=true, failure_reason=worker_died_before_terminal, fresh=false, warnings=["deep_pass_failed"] e retry_guidance="rerun scan to recover and rebuild".
5. O lock órfão foi detectado como inativo/ausente após a recuperação, mas os artefatos ficaram stale (index-state.updated_at=2026-07-16T19:39:20Z).
6. O refresh simplicio-mapper scan . --json --sync --timeout 120 não produziu receipt observável nesta tentativa.

Impacto: o Loop não consegue satisfazer o gate obrigatório de survey/mapping, mesmo com artefatos rasos e índices antigos presentes.

Critérios de aceite adicionais

• Um worker morto sempre produz estado terminal persistido com exit code, stderr tail e causa.
• scan --sync --timeout N retorna dentro do bound ou deixa receipt explícito; nunca fica sem saída observável.
• Lock órfão é recuperado somente após validar PID/start identity e a recuperação fica registrada.
• Um scan falho não é aceito pelo Loop como mapper pronto.
• Retry idempotente regenera map-job, atualiza index-state e fornece mapper.receipt.
• Teste Windows cobre worker morto, lock stale, timeout, retry e artifacts stale.
• O contrato documenta como o Loop consome status --json e distingue falha terminal de progresso.

[wesleysimplicio]

Implementação em andamento — timeout bounded + Windows worker hardening

A branch local agora contém uma correção focada, ainda não publicada:

• scan --sync inicia o index em subprocesso controlável em vez de executar deep pass indefinidamente dentro da CLI.
• --timeout N encerra o worker e descendentes, retorna exit code 1 e grava phase=timeout, failure_reason=scan_timeout, PID, elapsed bound e exit code.
• O lock é recuperado somente após validar que o owner morreu; lock vivo não é removido.
• status --json converte timeout em estado terminal failed e preserva reason code/next action.
• O worker recebe stdin=subprocess.DEVNULL, eliminando WinError 6 DuplicateHandle em hosts Windows com stdin inválido.

Evidência local

• 16 testes focados passaram: sync complete/lock guard, background, async, timeout terminal e lock recovery.
• python -m py_compile dos módulos alterados passou.
• git diff --check passou.
• Repro real contra simplicio-agent com scan --json --sync --timeout 8: exit 1 em ~8s, phase=timeout, failure_reason=scan_timeout, lock recuperado e status terminal.
• Suíte combinada: 81 passed, 3 falhas pré-existentes de git init/WinError 6 sob o host Windows; o worker mapper específico foi corrigido e os testes de background passaram.

A correção ainda precisa de PR/CI e validação em wheel instalado antes de fechar qualquer issue.

[wesleysimplicio]

Fresh reproduction — async scan remains deep_running with self-conflicting lock

Environment

• Windows, 2026-07-17
• Source checkout: C:\Users\Z0059V7A\m\repos\simplicio-mapper
• Target: C:\Users\Z0059V7A\m\repos\simplicio-agent
• Mapper source commit: 6cc2e2298c3c90b6946141151e11fed6ba7cd5bc (PR fix(scan): bound synchronous workers and recover timeout #232 implementation)
• Target size: 8,482 files, 81,972 symbols

Reproduction

1. Start async scan through Runtime:

simplicio shell compact -- python -m simplicio_mapper.cli scan C:\Users\Z0059V7A\m\repos\simplicio-agent --json

2. The command returns phase=macro_done, sync=false, PID 8456.
3. Poll through the source checkout:

simplicio shell compact -- python -m simplicio_mapper.cli status C:\Users\Z0059V7A\m\repos\simplicio-agent --json

4. After 161 seconds, the envelope still reports:

phase=deep_running
terminal=false
fresh=false
lock=true
lock_status.reason=live
lock_status.reason_code=lock_live_owner
job.phase=macro_done
job.exit_code=null
failure_reason=null
warnings=[deep_pass_in_progress]

5. The live process command line is:

python.exe -m simplicio_mapper.cli index C:\Users\Z0059V7A\m\repos\simplicio-agent --out .simplicio

6. The background log reports repeated attempts:

index skipped: lock already exists at C:\Users\Z0059V7A\m\repos\simplicio-agent\.simplicio\index.lock (x8)

Impact

The async scan path can remain non-terminal and never produce fresh artifacts, even though the worker process is alive. This blocks handoff, makes simplicio-loop unable to start a trustworthy survey, and can consume a worker slot indefinitely. It is not equivalent to the bounded synchronous timeout fixed in PR #232 because there is no terminal timeout/failed receipt for the async path.

Investigation and implementation plan

1. Trace lock ownership across scan, background wrapper, and index; identify whether the parent, child, or a stale previous job holds the lock.
2. Record owner token, PID, process-start identity, parent PID, and lock acquisition/release events for every async transition.
3. Make async launch atomic: exactly one process owns the lock and the child must not re-enter index while the parent still owns it.
4. Add a bounded async watchdog or explicit terminal failure receipt when heartbeat/progress is absent beyond a configured deadline.
5. Ensure recovery only reclaims a lock after PID/process-start validation, never merely by age.
6. Ensure status --json reports terminal=true, a stable failure_reason, and no live orphan after abort/recovery.
7. Keep the successful async path returning phase=complete, fresh=true, lock=false, and handoff.ready=true.

Required tests

• async scan on a small fixture reaches complete;
• async scan on the 8,482-file Agent fixture reaches complete or bounded terminal failure;
• parent/child lock ownership race;
• duplicate async scan while one is live;
• worker death before and after lock acquisition;
• stale lock with reused PID;
• timeout/watchdog process-tree termination on Windows;
• status/handoff after success, timeout, crash, and recovery;
• no unrelated worktree indexer is terminated;
• receipts preserve process-start identity and owner token.

Acceptance criteria

• No repeated self-conflicting index skipped loop.
• Every async job reaches complete, timeout, or failed within its configured bound.
• A live lock always maps to exactly one live owner process with matching process-start identity.
• A dead owner is recovered safely and visibly.
• fresh and handoff.ready are false until artifacts are complete and validated.
• The real Agent path has a reproducible receipt and regression test.
• Existing synchronous timeout, lock recovery, and stdin=DEVNULL behavior remain green.

Related: #230 (bounded synchronous scan timeout), #231 (Windows stdin handle), mapper release follow-up #233, agent issue #151.