req-167: Elevação de Permissão no project_transport_remote_exec para Execução Remota em Tenants HestiaCP (BATCH-172)

1. Descrição do Problema & Contexto

Durante a execução do pipeline ./c2f project:update-all [REDACTED]-local --confirmar-remoto, a etapa 1/8 (Sincronização Core) conclui com sucesso, mas a etapa 2/8 (Atualização de Banco de Dados) falha imediatamente com o seguinte erro retornado pelo SSH:

[2026-09-17 17:03:42] Running database updates...
[2026-09-17 17:03:42] Project deploy: resources will be overwritten and marked with '[REDACTED]-local'
 ✖ ERROR  bash: line 1: cd: [REDACTED] Permission denied
[ERROR] An error occurred during database updates.

Causa Raiz Mapeada

1. No HestiaCP / Linux multi-tenant, os diretórios de cada tenant (ex: [REDACTED]) possuem permissões restritas (ex: 750 ou 700, pertencentes ao usuário [REDACTED]).

2. A conexão SSH é autenticada com o usuário de infraestrutura/desenvolvedor ([REDACTED]).

3. Na biblioteca ai-workspace/en/scripts/lib/project-transport.sh, a função project_transport_remote_exec() monta o comando da seguinte forma:

   "$PT_SSH_BIN" "${PT_SSH_OPTS[@]}" "$PT_SSH_TARGET" \
    "cd $(printf '%q' "$PT_REMOTE_PATH") && $remote_cmd"

   onde $remote_cmd vira sudo -u [REDACTED] php ....

4. Como o cd é executado antes da elevação com sudo, o shell do usuário otavio tenta navegar para [REDACTED] sem permissão de travessia/leitura na pasta do tenant, abortando com cd: Permission denied.

5. A mudança de diretório (cd) e a execução do comando PHP precisam ocorrer dentro do contexto elevado do usuário alvo (ex: sudo -u $PT_SSH_RUN_AS sh -c "cd $(printf '%q' "$PT_REMOTE_PATH") && $remote_cmd" ou comando encapsulado).

2. Escopo Técnico de Alterações

Módulo 1: Biblioteca de Transporte (ai-workspace/en/scripts/lib/project-transport.sh)

• Em project_transport_remote_exec():

  • Garantir que a troca de diretório (cd "$PT_REMOTE_PATH") seja executada dentro da casca do usuário configurado em ssh_run_as / PT_SSH_RUN_AS (usando sudo -u $PT_SSH_RUN_AS sh -c "cd ... && ..." ou sudo -u $PT_SSH_RUN_AS -- bash -c ...), permitindo acesso transparente a diretórios restritos do tenant.

  • Preservar compatibilidade quando PT_SSH_RUN_AS não estiver definido (execução direta sob o usuário [REDACTED]).

Módulo 2: Testes Automatizados

• Em tests/Unit/PHP/ProjectSshDeployReq034Test.php:

  • Atualizar/adicionar asserções garantindo que project_transport_remote_exec encapsule o cd e o comando remoto sob o sudo -u quando ssh_run_as estiver preenchido.

Módulo 3: Governança & Skills

• Em .codex/skills/c2f-shell-and-windows-traps/SKILL.md (e nos 4 espelhos):

  • Documentar a armadilha de cd prévio sem elevação em ambientes multi-tenant SSH e a necessidade de encapsulamento com sudo -u.

3. Critérios de Validação e Aceite

1. Execução Remota sem Erro de Permissão:

   • A etapa 2/8 (Atualização do Banco) de ./c2f project:update-all [REDACTED]-local --confirmar-remoto executa o script PHP remoto com sucesso sem falhar por cd: Permission denied.

2. Suíte de Testes 100% Verde:

   • bash -n sem erros nos scripts shell.

   • PHPUnit 100% passando.

3. Evidências Registradas:

   • Registrar evidências em sdd/implementation/BATCH-172.md, BATCH-INDEX.md e CURRENT.md.