deepdebug-local-agent 1.0.23 → 1.2.0

package/docs/OBSERVABILITY.md

@@ -0,0 +1,164 @@
+# Client Observability — method & runbook
+
+How the DeepDebug local agent brings **observability to a client that has none**.
+It is the client-side delivery of the same stack we run for ourselves in
+`vh-observability` (Grafana + Loki + Alloy + Alertmanager) — same building
+blocks, different plumbing.
+
+| | `vh-observability` (ours) | This bundle (client) |
+| --- | --- | --- |
+| Runs on | Cloud Run (multi-container) | Client VPS/host (docker-compose) |
+| Log source | Cloud Logging → Pub/Sub (`gcplog`) | **`docker.sock`** (every container) |
+| Loki storage | GCS bucket | **local filesystem volume** |
+| Grafana login | Google Workspace OAuth | local admin (loopback-only) |
+| Alerts → | gateway `/webhooks/alertmanager` (Bearer secret) | **same gateway webhook** |
+
+Everything downstream of Loki is identical: the ruler evaluates a LogQL error
+rule, Alertmanager posts firing alerts to the gateway (tenant resolved from the
+trigger secret, sent as a Bearer header), and Grafana's logs dashboard has an **"Open in DeepDebug
+Workbench"** data link into `/api/v1/webhooks/from-log`.
+
+---
+
+## Architecture
+
+```
+   All containers on the host
+        │  (docker.sock, read-only)
+        ▼
+   Alloy  ──push──▶  Loki (filesystem)  ◀──query──  Grafana (127.0.0.1:3000)
+ (discovery.docker,   (chunks + tsdb in        (provisioned datasource +
+  service = name,      a local volume)          dashboard, loopback only)
+  level parsed)            │ ruler
+                           ▼
+                      Alertmanager  ──webhook──▶  gateway /api/v1/webhooks/alertmanager (Bearer <secret>)
+                                                        │
+                                        incident (tenant from the secret) + Slack notify
+```
+
+Four containers, one compose project (`deepdebug-observability`). Only Grafana
+publishes a port, and only on `127.0.0.1` — reach it over an SSH tunnel, never
+expose it to the internet.
+
+## The error → workbench loop
+
+- **Automatic** — Loki rule `ClientServiceErrors` fires on error rate → Alertmanager
+  → `POST /api/v1/webhooks/alertmanager` (`Authorization: Bearer <secret>`) → incident → Slack.
+- **Manual** — the Logs panel data link → `GET /api/v1/webhooks/from-log?s=<secret>&…`
+  → incident → 302 redirect to `<frontend>/incidents/<id>` (the PG-persisted id).
+
+The tenant is always resolved from the trigger secret, never from the
+caller — the secret IS the auth.
+
+## Logs into the platform (Live logs + services)
+
+Loki stays on the host for Grafana, but the platform cannot reach it (no inbound
+port). Alloy therefore **also pushes** the same Docker stream to the gateway:
+
+```
+loki.process ──▶ otelcol.receiver.loki ──▶ batch ──▶ otelcol.exporter.otlphttp
+   POST <gateway>/api/v1/webhooks/logs/otlp   (JSON, gzip, Authorization: Bearer <secret>)
+        ──▶ Redis list vh.logs.push.<tenant> ──▶ monitor-service (provider SELF_HOSTED)
+        ──▶ log_entries + live tail  ──▶ Live logs (one service per container)
+```
+
+- Outbound HTTPS only; same `vht_` secret as the Alertmanager.
+- The first push creates the tenant's `SELF_HOSTED` row in `tenant_log_configs`.
+- Pushed logs are **not** promoted to incidents by the monitor (the Loki rule above
+  already does that) unless `MONITOR_PUSH_DETECT_ENABLED=true`.
+- The gateway accepts OTLP **JSON** only (protobuf gets 415).
+
+**Existing installs** (provisioned before this change): run
+`scripts/upgrade-observability-push.sh` on the server (`--dry-run` first). It finds the
+bundle, reads the gateway URL and secret from `alertmanager.yml`, probes the push endpoint,
+adds the `otelcol.*` blocks, moves the secret to a Bearer header, validates both configs
+with the stack's own images, restarts only `alloy` + `alertmanager` and rolls back on
+failure. Idempotent.
+
+---
+
+## The zero-observability method
+
+The agent only offers to provision when the host has **nothing** already shipping
+logs/metrics. The decision is deliberately conservative: a false "they have it"
+just means we skip; a false "they have nothing" would deploy on top of a real
+stack. So we skip on ANY match.
+
+**Signals** (matched case-insensitively against container image/name AND process
+command lines): promtail, fluent-bit, fluentd, vector, filebeat, logstash,
+otel-collector, telegraf, loki, elasticsearch, opensearch, victoriametrics,
+prometheus, thanos, mimir, signoz, grafana, kibana, datadog, newrelic, splunk,
+dynatrace, instana, sumologic, … (see `OBSERVABILITY_SIGNALS` in
+`src/observability/detect.js`).
+
+**Our own stack never counts** as the client already having observability: any
+container whose compose project is `deepdebug-observability` is excluded, so
+re-running detection after we provision still reports the client's baseline and
+`up -d` stays idempotent.
+
+### Step-by-step the agent performs (`provisionObservability`)
+
+1. **Probe** the host — `docker ps` + process list → classify (above).
+2. **Guard** — if the client already has observability and `force` is not set,
+   **stop** and report what was found. Do not touch their stack.
+3. **Pre-flight** — verify `docker` and the compose plugin are present
+   (else return an actionable error).
+4. **Render** the bundle for this tenant: inject `gatewayUrl`, the alertmanager
+   `triggerSecret`, and a static `environment` label into every template.
+5. **Write** files to `~/.deepdebug/observability/deepdebug-observability/`
+   plus a `.env` (Grafana admin creds, `DDO_ENVIRONMENT`).
+6. **Start** — `docker compose up -d --remove-orphans`.
+7. **Report** — container status + the loopback Grafana URL and admin password.
+
+---
+
+## Agent API
+
+Called by the gateway (Setup/Onboarding agent) or by an operator directly.
+
+### `GET /observability/status`
+Probe + classify. No side effects.
+```json
+{ "ok": true, "hasObservability": false, "recommendation": "provision",
+  "found": [], "ownStackRunning": false,
+  "docker": { "docker": true, "compose": true }, "containersScanned": 6 }
+```
+
+### `POST /observability/provision`
+```jsonc
+{
+  "gatewayUrl": "https://api.visionhammer.io",   // no trailing slash needed
+  "triggerSecret": "vht_….",                     // tenant alertmanager secret
+  "environment": "production",                    // static label for this client
+  "grafanaUser": "admin",                         // optional
+  "grafanaPassword": "…",                         // optional (else generated + returned)
+  "force": false,                                 // deploy even if a stack exists
+  "start": true                                   // run `docker compose up -d`
+}
+```
+Returns `409 { skipped: true, found: [...] }` when the client already has a stack
+and `force` is not set. On success returns `installDir`, container `status`, and
+`grafana: { url, user, password }`.
+
+### `POST /observability/teardown`
+`{ "purge": false }` → `docker compose down` (`purge:true` also removes volumes).
+
+---
+
+## Access & security
+
+- **Grafana** is bound to `127.0.0.1:3000`. Reach it with
+  `ssh -L 3000:127.0.0.1:3000 <host>` then open `http://localhost:3000`.
+- The **trigger secret** is the only credential in the alertmanager webhook URL
+  and it authorises exactly one tenant. Rotate via the gateway trigger source.
+- Alloy mounts `docker.sock` **read-only** and only tails logs.
+- The generated Grafana admin password is reported once — rotate it, or pass
+  your own `grafanaPassword`.
+
+## Where the bundle lives
+
+The bundle is **embedded** in the agent (`src/observability/bundle-files.js`) so
+it ships inside the `pkg` binary — there are no loose asset files to lose. Editing
+that file changes what the agent deploys. `renderBundle()` is a pure function
+(templated in → final files out) and is covered by
+`test/observability-detect.test.js`.

package/docs/byoc-agent-image.md

@@ -0,0 +1,70 @@
+# BYOC agent image (`local-agent-full`)
+
+Customer-cloud agents (BYOC GCP Cloud Run and BYOC Azure Container Instances)
+run the public image built from `Dockerfile.full`:
+
+```
+europe-west1-docker.pkg.dev/visionhammer/visionhammer-docker-public-eu/local-agent-full:<semver>
+europe-west1-docker.pkg.dev/visionhammer/visionhammer-docker-public-eu/local-agent-full:<git-sha>
+```
+
+The managed per-tenant Cloud Run agent (gateway `AgentProvisioningService`) is
+built separately per tenant and does not use this image.
+
+## Publishing a version
+
+1. Actions → **Build BYOC Agent Image** → *Run workflow* on `main` (version
+   defaults to `package.json`; or push a `v*` tag / publish a release on a
+   commit that is on `main`).
+2. The workflow builds `Dockerfile.full`, smoke-tests it (`/health` public,
+   API returns 401 without `X-Agent-Token` when `LOCAL_AGENT_TOKEN` is set),
+   then pushes `:<semver>` and `:<git-sha>`. It refuses to overwrite an
+   existing `:<semver>` built from a different commit, and never moves an
+   existing `:<git-sha>` (a commit rebuilt under a new semver keeps its first
+   image under `:<git-sha>`; always pin `:<semver>@sha256:`). There is no floating tag.
+3. Copy the pinned reference from the run summary
+   (`...local-agent-full:<semver>@sha256:<digest>`).
+
+4. Optional supply chain (flag, off by default): tick `supply_chain` on the
+   dispatch (or set the repository variable `BYOC_SUPPLY_CHAIN=true` for tag and
+   release runs). The `supply-chain` job signs `:<semver>@sha256:<digest>` with
+   cosign keyless (GitHub OIDC), attaches an SPDX SBOM (syft) and a SLSA v1
+   provenance attestation, and verifies all three. Consumers verify with:
+
+   ```
+   cosign verify \
+     --certificate-identity-regexp '^https://github.com/VISIONHAMMER/deepdebug-local-agent/' \
+     --certificate-oidc-issuer https://token.actions.githubusercontent.com \
+     <image>@sha256:<digest>
+   ```
+
+   Use `cosign verify-attestation --type spdxjson` (or `slsaprovenance1`) for
+   the SBOM and the provenance. The provenance is generated inside this
+   workflow and signed with the workflow identity; it is not a
+   slsa-github-generator (isolated builder) attestation.
+
+Fallback without GitHub Actions: `cloudbuild-full.yaml` (see header).
+
+## Rolling it out (gateway)
+
+Set `deepdebug.byoc.agent-image` in vh-api-gateway (env `BYOC_AGENT_IMAGE`) to
+the pinned reference, or bump its default in `application.yml` via PR. Only
+newly provisioned agents pick it up; existing ones keep their image until
+re-provisioned from the platform (Cloud Engineer → provision again). Azure
+container groups created before the TLS/token spec are recreated on re-provision.
+
+## Runtime knobs relevant to BYOC
+
+| Env | Meaning |
+| --- | --- |
+| `LOCAL_AGENT_TOKEN` | Enforce `X-Agent-Token` on every non-public route (gateway sets it = the per-workspace shared secret on ACI). |
+| `AGENT_SHARED_SECRET` | Same secret; used for the agent's own in-process calls. |
+| `LOCAL_AGENT_BIND_HOST` | Listen address. Default: `0.0.0.0` when a token (`LOCAL_AGENT_TOKEN`/`AGENT_SHARED_SECRET`) or Cloud Run is present, otherwise `127.0.0.1`. ACI sets `127.0.0.1`: only the Caddy TLS sidecar in the same container group can reach it. |
+
+## One-time operator setup
+
+- `github-deployer@visionhammer.iam.gserviceaccount.com` needs
+  `roles/artifactregistry.writer` on the `visionhammer-docker-public-eu` repository (europe-west1; today granted at project level)
+  (and `artifactregistry.reader` for the overwrite guard).
+- The repository must stay public-read (`allUsers` → `artifactregistry.reader`) so
+  customer projects / ACI pull without credentials.

package/docs/dlp.md

@@ -0,0 +1,78 @@
+# DLP: masking secrets and PII before content leaves the agent (T4-09)
+
+Status: module + first integration point. Flag `LOCAL_AGENT_DLP_MODE`, default **off**.
+
+## Flags
+
+| Variable | Values | Default | Effect |
+|---|---|---|---|
+| `LOCAL_AGENT_DLP_MODE` | `off`, `warn`, `enforce` | `off` | `off`: nothing scanned, output identical to before. `warn`: output unchanged, counters and local log report what enforce would redact. `enforce`: hits replaced by `[REDACTED:<rule_id>]`. Any other value means `off`. |
+| `LOCAL_AGENT_DLP_BLOCK_CLASSES` | comma list of classes | empty | Enforce only. If a hit belongs to a listed class the whole text is replaced by `[BLOCKED:<class>]`. |
+| `LOCAL_AGENT_DLP_MAX_BYTES` | integer | `2000000` | Larger inputs are not scanned; enforce fails closed (`[REDACTED:dlp_oversize]`). |
+
+Classes: `private-key`, `cloud-credential`, `vcs-token`, `payment-key`, `saas-token`, `token`,
+`credential`, `connection-string`, `url-credential`, `pii-email`, `pii-phone`, `pii-id`,
+`pii-financial`, `high-entropy`.
+
+## API (reusable by the WebSocket work, task M)
+
+```js
+import { maskSensitive, maskDeep, protectEgress, protectEgressAsync, protectDeep,
+         getDlpStats, rulesetHash, RULESET_VERSION } from './src/dlp/index.js';
+```
+
+- `maskSensitive(text, { mode, blockClasses, maxBytes })`: **pure** function (no env, no state).
+  Returns `{ text, redactions: {rule_id: n}, total, blocked, blockedClasses, oversize, rulesetVersion }`.
+- `maskDeep(value, opts)`: same over every string of a JSON-like value (keys untouched, input not mutated).
+- `protectEgress(text, { source, log, env })`: reads the flag from the environment, updates counters,
+  writes a local record with counts per rule (never the value). Returns `{ text, ... }`.
+- `protectEgressAsync(text, { policyDecision, timeoutMs, ... })`: as above, plus a per-action
+  PolicyGate decision (D19). In `enforce`, anything other than an explicit `'ALLOW'` (DENY, unknown
+  answer, throw, timeout, PolicyGate offline) returns `[DLP_DENIED]`.
+- `protectDeep(value, opts)`: env-driven `maskDeep`.
+- `getDlpStats()`: `{ mode, ruleset_version, ruleset_hash, scanned, blocked, denied, dlp_redactions_total: {rule_id: n} }`.
+  Counts only; intended for the heartbeat (`dlp_redactions_total` by rule). `rulesetHash()` is what
+  `config.update` can carry to prove which ruleset is active.
+
+Fail-closed rules in `enforce`: internal error, oversize input, policy not ALLOW = content withheld.
+In `warn`/`off` the original text is always returned.
+
+## Where it is applied today
+
+- `src/siblings/incident-forwarder.js`: `message` of the incident POSTed to the gateway (log excerpt).
+
+Not applied yet (follow-ups, outside this PR's boundary): `content.request` responses and `job.event`
+(WebSocket channel, task M), prompts of the loop, error messages returned by routes. They can call
+`protectEgress`/`protectDeep`/`maskSensitive` directly.
+
+## Ruleset (version `2026.10.28-1`, 40 rules)
+
+Order matters (specific before generic). Highlights: PEM/OpenSSH/PGP private keys; AWS key id and secret;
+GCP API key, OAuth token and client secret; Azure storage key; DigitalOcean; GitHub (classic, fine-grained);
+GitLab; npm; PyPI; Stripe (keys, webhook secret); Shopify; Slack (token, webhook); Discord webhook;
+SendGrid; Twilio; Mailgun; Hugging Face; Telegram; Anthropic; OpenAI; JWT; Bearer and Basic headers;
+DB connection strings (postgres, mysql, mongodb, redis, amqp, mssql, cockroach); JDBC and ADO passwords;
+credentials in URLs; generic `name = literal` assignments (with a validator that ignores identifiers,
+calls, templates and placeholders); e-mail (ignores asset names and documentation domains);
+IBAN (mod-97); card numbers (Luhn); PT NIF (checksum and keyword context); international phone
+(leading `+`/`00`, 9 to 15 digits); opaque high-entropy blobs (40+ chars, ignores hex digests, UUIDs,
+SRI hashes and paths). Patterns are reimplemented from public token formats; no third-party rule
+files were copied. The PiiEgressMasker of the agents repo was used as a behavioural reference only.
+
+Bump `RULESET_VERSION` in `src/dlp/rules.js` on any change.
+
+## Tests
+
+`test/dlp/`: every rule has at least one synthetic positive (fixtures are built at runtime from split
+prefixes and a deterministic hash stream, no real secrets); 40 negative lines (code, hashes, UUIDs,
+SSH remotes, templates) must be unchanged; mode, block, oversize, idempotence, performance on
+pathological 1 MB inputs, policy fail-closed and the forwarder integration (flag off = byte-identical).
+
+Indicative false-positive check (not a measured product metric): running `enforce` over this repo
+(182 text files, ~41k lines) altered about 40 lines, almost all true positives (e-mail addresses in
+docs and test fixtures, literal tokens in tests). The plan's target (<= 2 % FP on a real code
+corpus) still needs to be measured on a customer-like corpus during the pilot.
+
+## Rollback
+
+Unset `LOCAL_AGENT_DLP_MODE` (or set `off`) and restart the agent. No data, schema or protocol changes.

package/docs/graphify-packaging-plan.md

@@ -0,0 +1,133 @@
+# Graphify no `local-agent-full`: plano de empacotamento e checklist de licenças
+
+Estado: **proposta** (tarefa T4-06 do plano GA do Local Agent, decisões D8, D11, D12, D14 e D18 do ADR-0017). Nada neste
+documento está aplicado: nenhum Dockerfile, workflow ou `package.json` foi alterado. A implementação é a tarefa T4-07
+(PR separado). Marcação: **[V]** verificado nesta sessão (comando e saída em `docs/graphify-validation-run-2026-10-28.md`),
+**[N]** não verificado.
+
+## 1. Decisões que este plano executa
+
+| Decisão | Consequência técnica |
+|---|---|
+| D8: Graphify via PyPI, versão fixada, com hash | dependência `graphifyy==X.Y.Z`, sem fork; instalação só com `--require-hashes` |
+| D11: GA 1.1.0 | a imagem `local-agent-full:1.1.0` é a primeira com o runtime; o `Dockerfile.full` e o Helm deixam de apontar para `1.0.0` e `:latest` (tarefa T4-07) |
+| D12: cosign e SBOM obrigatórios | a imagem e o SBOM saem assinados na mesma release (secção 6) |
+| D14: fallback ripgrep | a imagem inclui `ripgrep`; se o índice do grafo faltar ou estiver velho, o contexto vem de `rg` |
+| D18: runtime pack multi-runtime | o runtime Graphify é um pack como os outros (Java, Swift): instalável e removível sem tocar no agente Node |
+
+## 2. O que vai fixado, e como
+
+### 2.1 Ficheiros de lock (já no harness)
+
+`tools/graphify-validation/requirements.in` tem **uma** linha, `graphifyy[sql,terraform]==0.9.93`. Dois locks com hashes SHA-256
+de todos os artefactos de cada versão:
+
+- `requirements.lock`, Python 3.12 (venv do harness) [V];
+- `requirements-py311.lock`, Python 3.11, a versão do Debian bookworm que o `Dockerfile.full` já instala (`python3`, `libpython3.11`) [V no ficheiro].
+
+**Os locks não são intermutáveis [V]:** em 3.11 o resolvedor escolhe `networkx 3.6.1` e `numpy 2.4.6`; em 3.12, `networkx 3.7` e
+`numpy 2.5.4`. A imagem usa o lock do Python que tiver. Para a mesma versão de Python, o conjunto de pacotes resolvido é o mesmo em
+Linux x86_64, Linux aarch64 e macOS arm64 (`uv pip compile --python-platform ...`, comparado) [V]. O lock 3.11 foi instalado com
+`--require-hashes --no-deps --only-binary=:all:` num venv Python 3.11 em macOS arm64 e deu o mesmo grafo (52 nós, 84 arestas) na fixture Spring [V];
+a instalação em Linux (glibc, musl) **não foi corrida** [N] (sem Docker local).
+
+Extras: só `sql` (`tree-sitter-sql`) e `terraform` (`tree-sitter-hcl`). **Não** entram `mcp`, `leiden` (puxa `graspologic`), nem extras de LLM
+(`anthropic`, `openai`, `gemini`, `bedrock`, `ollama`...). Sem `leiden`, a deteção de comunidades usa o fallback do próprio Graphify;
+as comunidades não são identificadores estáveis de qualquer modo (nota do piloto). O pacote instala o script `graphify-mcp`
+mesmo sem o extra `mcp` [V, `entry_points.txt`]: **apagar `bin/graphify-mcp`** na imagem.
+
+### 2.2 Instalação
+
+```dockerfile
+# proposta para Dockerfile.full (T4-07); não aplicada
+ARG GRAPHIFY_LOCK=requirements-py311.lock
+COPY tools/graphify-validation/${GRAPHIFY_LOCK} /tmp/graphify.lock
+RUN python3 -m venv /opt/vh-graphify \
+ && /opt/vh-graphify/bin/pip install --no-cache-dir --disable-pip-version-check \
+      --require-hashes --no-deps --only-binary=:all: -r /tmp/graphify.lock \
+ && /opt/vh-graphify/bin/python -m compileall -q /opt/vh-graphify/lib \
+ && rm -f /opt/vh-graphify/bin/graphify-mcp /tmp/graphify.lock
+```
+
+Porquê cada flag: `--require-hashes` recusa qualquer ficheiro cujo hash não esteja no lock; `--no-deps` impede que o pip resolva
+dependências por fora do lock; `--only-binary=:all:` proíbe sdists, logo **nenhum `setup.py` de terceiros corre no build** (a nota do piloto já
+tinha visto que o `pyproject` do Graphify é setuptools puro [C]); `compileall` deixa o bytecode feito para o sistema de ficheiros só de leitura
+(o Python não escreve `.pyc` com `PYTHONDONTWRITEBYTECODE=1`).
+
+Tamanho medido do `site-packages`: 154 MB (Python 3.12, macOS arm64, com `pip`) e 124 MB (3.11, sem `pip`) [V]. Em Linux pode diferir [N]; o
+limite proposto de delta de imagem é 400 MB (G9).
+
+### 2.3 Política de subida
+
+1. Só versões com mais de 7 dias no PyPI (cooldown contra pacote comprometido). A fixada, 0.9.93, tinha 8 dias a 2026-10-28 [V, data de upload no PyPI]; o
+   upstream já ia na 0.9.97 (publicada a 2026-10-27, **não escolhida de propósito**).
+2. PR de subida: editar `requirements.in`, regenerar os dois locks (comandos no README do harness), **rever o diff do código Python do Graphify entre versões**
+   (o PyPI mostra 13 versões em 17 dias, de 0.9.84 a 0.9.97 [V]), repetir o harness (G1, G2, G7, G8) e anexar o `REPORT.md`.
+3. Nunca `pip install graphifyy` sem lock, nem `--upgrade`, nem `latest`, em Dockerfile, instalador, Helm ou CI.
+4. Mesma regra para o `pip-audit` (`requirements-tools.in/.lock`).
+
+## 3. `pip-audit` e cadeia de fornecimento
+
+- Local: `run.sh --pip-audit` corre `pip-audit --require-hashes --disable-pip --no-deps -r requirements.lock`. Resultado de 2026-10-28: **0 vulnerabilidades conhecidas em
+  32 pacotes** (base PyPI/OSV nessa data) [V]. O mesmo audit tem de correr para `requirements-py311.lock` [N: só o lock 3.12 foi auditado].
+- CI (T4-07): job no PR que toca nos locks e job semanal agendado; falha com qualquer vulnerabilidade com versão corrigida disponível. Exceções só com ID, motivo e data de expiração
+  num ficheiro `pip-audit-ignore.txt` revisto no PR. Nota: o audit só vê vulnerabilidades **publicadas**; não substitui a revisão de diff da secção 2.3.
+- Proveniência: confirmar se o `graphifyy` publica atestações PyPI (Trusted Publishing) [N]. Se publicar, verificar no job de subida; se não, registar o risco no ADR.
+- A imagem corre **sem rede para o Graphify**: o `entrypoint` do pack não define proxies nem chaves, e o contentor de teste usa `--network none` (G9) [N].
+
+## 4. Superfície permitida em runtime
+
+O Local Agent chama o Graphify por **um wrapper** (`vh-graphify`, a escrever em T4-07), nunca diretamente:
+
+| Permitido | Proibido (o wrapper recusa com exit 64) |
+|---|---|
+| `update <path>`, `query`, `affected`, `explain`, `path`, `god-nodes` | `label`, `cluster-only` sem `--no-label`, `add`, `clone`, `prs`, `watch`, `install`, `global`, `merge-graphs`, `graphify-mcp` |
+
+- Ambiente do processo filho: `HOME` num diretório do volume de dados, `PATH`, `LANG`, `PYTHONHASHSEED=0`, `PYTHONDONTWRITEBYTECODE=1`. **Sem** chaves LLM, tokens nem proxies
+  (a CLI auto-deteta chaves e envia nomes de comunidade ao LLM, nota do piloto). O harness corre assim e o relatório regista as chaves passadas [V].
+- Rede: o harness provou 0 eventos `socket.*` com a rede bloqueada nos três repos VH, a rede estava de facto bloqueada (sonda TCP falhou) e os únicos `subprocess.Popen` foram `git rev-parse HEAD` [V].
+  O wrapper deve manter o `git` no `PATH`.
+- Um índice de cada vez (fila), limite de memória 1,5 GB e timeout por job. Medido: o `update` incremental chega a 1,13-1,17 GB no maior processo filho nos repos de ~1 700 ficheiros [V]; num VPS de 4 GB cabe, num de 2 GB não.
+  Em 2 vCPU 4 GB **não medido** [N].
+- `graphify-out/` fica no volume de dados do cliente, fora do git, e entra na lista de limpeza/erasure. `git ls-files graphify-out` tem de dar 0; hoje o `visionhammer-agents@release/qa` tem 57 ficheiros versionados [V] (remoção = PR próprio no agents, `git rm -r --cached graphify-out`).
+- Utilizador não-root, FS só de leitura exceto o volume de dados e `/tmp`.
+
+## 5. Checklist de licenças
+
+Inventário da instalação do harness (32 distribuições, `lib/licenses.py`) [V]: **32 permissivas, nenhuma copyleft, nenhuma desconhecida**.
+
+| Componente | Licença (metadados) | Ficheiro de licença no wheel | Ação |
+|---|---|---|---|
+| graphifyy 0.9.93 | Apache-2.0 (+ `LICENSE-MIT`, `NOTICE`) | sim (`LICENSE`, `LICENSE-MIT`, `NOTICE`) | copiar os três para `/usr/share/doc/vh-graphify/`; incluir o `NOTICE` no `THIRD_PARTY_NOTICES` do release |
+| networkx 3.7 / 3.6.1 | BSD-3-Clause | sim | notice |
+| numpy 2.5.4 / 2.4.6 | `BSD-3-Clause AND 0BSD AND MIT AND Zlib AND CC0-1.0` (libs incluídas) | sim | notice com a lista das licenças incluídas |
+| RapidFuzz 3.14.6, tree-sitter 0.25.2 (core) | MIT | sim | notice |
+| 27 gramáticas `tree-sitter-*` instaladas | MIT (2 em Apache-2.0: `tree-sitter-elixir`, `tree-sitter-hcl`) | sim, **exceto `tree-sitter-groovy`** | `tree-sitter-groovy` é MIT nos metadados mas **o wheel não traz ficheiro de licença**: obter o texto do repositório upstream e anexar [N] |
+| ripgrep (Debian) | Unlicense/MIT | pacote Debian | notice (D14) |
+| Python 3.11 (Debian) | PSF | pacote Debian | notice |
+
+Checklist antes de publicar:
+
+- [ ] Gerar o SBOM CycloneDX da imagem final (inclui hashes e licenças de cada wheel) e anexar à release; é a fonte do `THIRD_PARTY_NOTICES`.
+- [ ] Reter `LICENSE`, `LICENSE-MIT` e `NOTICE` do Graphify, sem os alterar (exigência do Apache-2.0 para redistribuição; o `package.json` do agente diz `Proprietary`, o que não impede redistribuir um componente Apache-2.0 com notice).
+- [ ] Obter o texto de licença de `tree-sitter-groovy` e conferir que a gramática distribuída corresponde ao MIT declarado.
+- [ ] Não incluir os extras `leiden` (graspologic), `neo4j`, `falkordb`, `postgres`, `google`, `video`, `office`, `pdf` sem nova revisão: não foram inventariados [N].
+- [ ] Marca: o upstream promove o "Graphify Cloud" no README; a imagem e a documentação VH não usam o nome nem o logótipo comerciais, só o nome do pacote.
+- [ ] Confirmar com quem decide (jurídico) que a redistribuição dentro de uma imagem proprietária cumpre os contratos de cliente. Isto é uma checklist técnica, **não parecer jurídico**.
+- [ ] Repetir o inventário (`lib/licenses.py`) a cada subida de versão; qualquer licença nova fora de MIT/BSD/Apache/PSF/ISC bloqueia o PR.
+- [ ] Decisão pendente do Edu: abandonar o fork `VISIONHAMMER/visionhammer-graphify` (recomendado no plano GA); se se mantiver, manter os cabeçalhos de licença e o `NOTICE` do upstream.
+
+## 6. Assinatura e SBOM (D12)
+
+- `syft <imagem> -o cyclonedx-json` no workflow de build; o SBOM vai como asset da release e é anexado à imagem com `cosign attach sbom` ou atestação `cosign attest --type cyclonedx`.
+- `cosign sign` da imagem por digest (keyless via OIDC do GitHub Actions, ou chave no KMS; escolha por decidir [N]). O workflow `build-byoc-image.yml` hoje não assina [N, não verificado nesta tarefa].
+- Verificação no instalador/Helm: `cosign verify` do digest antes de arrancar; o Helm deixa de usar `:latest` e passa a referenciar o digest.
+- O hash do lock e o hash do SBOM do pack Graphify ficam no `metadata` do heartbeat para o gateway poder detetar versões não aprovadas (desenho em T4-07/T4-08) [N].
+
+## 7. O que falta provar (antes de declarar G9)
+
+1. `docker build -f Dockerfile.full` com o bloco da secção 2.2 e medir o delta de imagem (limite 400 MB).
+2. `docker run --read-only --network none --user 10001 ... vh-graphify update /workspace` com sucesso, mesmo grafo que o harness (comparar `signature`).
+3. Lock 3.11 em Linux x86_64 e aarch64; `pip-audit` sobre `requirements-py311.lock`.
+4. `tree-sitter-groovy`: licença anexada.
+5. Wrapper `vh-graphify` com teste de que cada comando proibido sai com 64 e que nenhuma chave LLM é herdada.