Device Access Lock (lock exclusivo do celular do owner)

Em toda sessão em que uma IA (Claude Code, Codex, Gemini CLI, qualquer agente) for acessar o celular físico do owner via ADB/IRIS, ela DEVE primeiro adquirir um lock exclusivo do device e liberá-lo ao terminar. Sibling de android-ui-inspection.kmd (Eye/IRIS-first) e device-mirror-during-ai-access.kmd (mirror).

Por quê — hard, não advisory

O lock de componente (código) é advisory: o KVS faz merge concorrente seguro no cliente, então duas sessões editando o mesmo arquivo não se atropelam. Um celular físico NÃO tem merge. Duas IAs mandando input/am start/screencap ao mesmo aparelho ao mesmo tempo produzem caos determinístico — foco perdido no campo de texto, app trocado no meio da tarefa, taps de uma caindo na tela que a outra abriu. Logo o device-lock é EXCLUSIVO (hard): quem segura, os outros esperam. Cai na categoria de exclusividade-genuína do lock-carve-out.kmd (junto com migraçõesreleasesrebrands).

Escopo de contenção

O celular é USB no laptop; o IRIS é acessado via adb forward. Portanto quem disputa o device são IAs rodando no laptop (Claude Code, Codex, Gemini locais) — todas compartilham o mesmo ~/dev/koder e enxergam o mesmo notice local na hora. O koder_root_bot (no s.khost1) não toca no celular. Um lock local (notice gitignored) cobre toda a contenção real.

Slug e mecanismo

• Slug do device: device/owner-phone → notice

  meta/context/notices/active/lock-device-owner-phone.md (gitignored, local).

• Mecanismo: o mesmo dos locks de componente (tasks/concurrent-lock.md +

  koder-lock). O koder-lock place já recusa se outra sessão segura o lock (ErrConflict) — é exclusivo por construção.

Fluxo obrigatório

1. Check antes de tocar no device:

   koder-lock check device/owner-phone   # exit 0 livre · 1 conflito · 2 erro

   Sem o binário no PATH, checar o arquivo direto: test -e meta/context/notices/active/lock-device-owner-phone.md.

2. Se preso por OUTRA sessão → NÃO acessar o celular. Esperar/ceder

   (ver blocked-work-monitor.kmd) ou coordenar. Exceção: lock stale (ver TTL abaixo) → pode roubar.

3. Se livre → adquirir, declarando TTL e tarefa:

   koder-lock place device/owner-phone --reason "e2e Codex via Telegram" --ttl 15m

   (fallback: escrever o notice à mão com component: device/owner-phone, lock_expires: <agora+TTL> e a sessão/PID.)

4. Usar o celular (ADBIRISmirror) normalmente.

5. Liberar SEMPRE ao terminar (inclusive em erro/abort):

   koder-lock archive device/owner-phone

TTL e stale-steal (anti-brick)

Uma IA que travar segurando o lock não pode prender o celular pra sempre. Todo device-lock declara um TTL curto (default 15 min) via lock_expires: no frontmatter:

• Um lock cujo lock_expires já passou é stale → qualquer sessão pode

  roubar (arquivar o stale + colocar o seu).

• Idem se a sessão dona sumiu (PID morto / sessão encerrada).
• TTL não é "tempo de tarefa": é um teto de segurança. Tarefas longas

  renovam o lock (re-place com novo lock_expires) antes de expirar.

Tooling: a auto-expiração no koder-lock (ignorar/roubar lock stale por lock_expires) é rastreada em koder-tools (ver ticket de enhancement). Até lá, o stale-steal é convenção lida pela IA: ao ver um lock do device com lock_expires no passado, a IA arquiva-o e segue.

Cobertura cruzada

• android-ui-inspection.kmd (IRIS-first) e device-mirror-during-ai-access.kmd

  (mirror) dizem como acessar o celular; esta policy diz quando é permitido (só com o lock). As três se reforçam — o mesmo adb forward habilita IRIS+mirror, e o lock serializa o acesso.

• Generaliza (reuse-first): o mesmo device/<slug> serve para *ualquer

  recurso físico/exclusivo*conectado ao laptop (outro device, dongle, seat de teste), não só o celular do owner.