GTI_GERENCIADOR_FISCAL/docs/superpowers/plans/2026-09-23-agent-installation-identity-heartbeat.md

Agent Installation Identity Recovery and First Heartbeat Implementation Plan

For agentic workers: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox syntax for tracking.

Goal: Recover and persist Agent 2's existing Hub installation_id, send exactly the first safe heartbeat, and stop without claiming jobs or writing Firebird.

Architecture: The Hub exposes the already-linked installation identity over an authenticated, read-only endpoint. New enrollments return that same ID so Setup can persist it; legacy installations recover it at runtime and commit it into the existing SQLite identity table before heartbeat. AGENT_JOBS_ENABLED=0 skips the job API entirely during activation.

Tech Stack: FastAPI, SQLAlchemy, pytest, Python fdb, SQLite local state, PyInstaller onedir service host, Windows SCM / PowerShell.

Global Constraints

• Keep Agent ID 2; do not create an Agent, reenroll, or create a second Installation.
• Never generate a fallback installation_id for an already-registered Agent.
• Do not call /v1/jobs/next, classification endpoints, or any job execution path during activation.
• Preserve FIREBIRD_WRITES=0, FISCAL_MODE=DRY_RUN, and empty AUTHORIZED_WRITE_DATABASE_PATH.
• All Firebird connections used by preflight remain read-only; issue no Firebird DML/DDL.
• Do not rerun Setup.exe or replace agent.env / credentials.bin during service-host update.
• Keep published GTIFiscalAgent-Setup-1.1.1.exe immutable; update only the installed service runtime.
• Never print or log FB_PASSWORD, the Agent bearer token, or credential-file contents.
• Do not commit unless the operator explicitly requests a commit.

---

Task 1: Hub installation identity response

Files:

• Modify: central/app/api.py
• Test: central/tests/test_jobs.py

Interfaces:

• Add authenticated GET /v1/agents/me/identity.

• Return exactly {agent_id, installation_id, hostname, version, status}; installation_id and hostname are None if the Agent has no Installation.

• Do not change the existing GET /v1/agents/me response.

• Step 1: Write the failing identity endpoint tests

Add tests that create an Agent with one Installation (installation_id fixed UUID, hostname DESKTOP-B0HL02I, version 1.1.1) and assert:

response = client.get("/v1/agents/me/identity", headers=headers)
assert response.status_code == 200
assert response.json() == {
    "agent_id": agent.id,
    "installation_id": installation.installation_id,
    "hostname": "DESKTOP-B0HL02I",
    "version": "1.1.1",
    "status": "OFFLINE",
}

Also assert unauthenticated requests return 401 and an Agent without an Installation returns HTTP 200 with nullable identity fields, without creating an Installation.

• Step 2: Run the focused tests and verify failure

Run: python -m pytest central/tests/test_jobs.py -q Expected: the identity route returns 404 before implementation.

• Step 3: Implement the authenticated endpoint

Use the existing principal dependency, query Installation by agent.id, and derive status with the same online-threshold rule as /v1/agents/me. The route must not commit or mutate database state.

• Step 4: Run the focused tests

Run: python -m pytest central/tests/test_jobs.py -q Expected: all tests pass; existing /v1/agents/me tests remain unchanged and green.

Task 2: Return and persist identity during new enrollment

Files:

• Modify: central/app/agent_distribution.py
• Test: central/tests/test_install_code_enrollment.py
• Modify: installer/install_common.py
• Test: tests/test_installer_artifacts.py

Interfaces:

• Successful /v1/agents/enroll response adds installation_id=enr.enrollment_uuid.

• write_agent_env(install_dir_path, enroll_result) writes INSTALLATION_ID as a non-secret field. It never writes agent_token or AGENT_TOKEN.

• Step 1: Add failing enrollment and Setup-env assertions

In the existing install-code happy-path test, assert body["installation_id"] == uuid. In the installer artifact test, pass a fixed ID such as 00000000-0000-4000-8000-000000000222 and assert the env includes it while the token is absent.

• Step 2: Run focused tests and verify failure

Run: python -m pytest central/tests/test_install_code_enrollment.py::test_enroll_with_install_code_alone_creates_agent tests/test_installer_artifacts.py -q Expected: failures show the response/env currently omit installation_id.

• Step 3: Add the returned ID and env serialization

Add "installation_id": enr.enrollment_uuid to the successful enrollment JSON. Add INSTALLATION_ID to write_agent_env; do not change credential storage or Firebird guard values.

• Step 4: Run focused tests

Run the same command as Step 2. Expected: enrollment and installer artifact tests pass; agent.env remains token-free with FIREBIRD_WRITES=0 and FISCAL_MODE=DRY_RUN.

Task 3: Persist or recover identity before heartbeat

Files:

• Modify: agent/src/gti_fiscal_agent/state.py
• Modify: agent/src/gti_fiscal_agent/client.py
• Modify: agent/scripts/run_agent_service.py
• Test: agent/tests/test_state.py
• Test: agent/tests/test_run_agent_service.py

Interfaces:

• AgentState.installation_id(candidate: str | None = None) -> str returns the persisted UUID; if no UUID is stored, it persists a valid candidate; if neither exists, it raises instead of generating a random UUID. A different candidate from an already-persisted UUID raises.

• HubClient.identity() -> dict calls authenticated GET /v1/agents/me/identity.

• resolve_installation_id(config, env, state, client) -> str selects persisted state, then INSTALLATION_ID, then authenticated identity; verifies returned agent_id equals config.agent_id; persists before returning.

• Step 1: Write failing state identity tests

Cover: empty store plus valid candidate persists and returns it; second call returns the same ID; conflicting candidate raises; missing candidate does not generate; malformed UUID raises.

• Step 2: Run state tests and verify failure

Run: python -m pytest agent/tests/test_state.py -q Expected: the missing identity case currently generates a UUID and the persistence API is absent.

• Step 3: Implement deterministic SQLite identity persistence

Validate candidate values with uuid.UUID. Within a SQLite transaction, read the existing row, compare any candidate, insert only when absent, and return the single stored canonical UUID. Remove random UUID creation from the registered-agent path.

• Step 4: Write failing runtime bootstrap tests

Use a fake Hub identity response and fake state. Assert missing local identity calls identity() once, verifies matching Agent ID, persists the returned UUID, and uses it in heartbeat. Assert a mismatched Agent ID, null ID, or identity request error fails before heartbeat. Assert an already-persisted ID avoids the identity request.

• Step 5: Run runtime tests and verify failure

Run: python -m pytest agent/tests/test_run_agent_service.py -q Expected: current loop calls the random-UUID-producing state method and has no authenticated identity bootstrap.

• Step 6: Implement identity bootstrap before the heartbeat loop

Add HubClient.identity(), implement resolve_installation_id, and invoke it after constructing the Hub client/state but before entering the loop. An identity failure must exit before heartbeat and before job polling.

• Step 7: Run focused state/runtime tests

Run: python -m pytest agent/tests/test_state.py agent/tests/test_run_agent_service.py -q Expected: persisted/recovered identity tests pass and mismatches fail closed.

Task 4: Disable job polling without disabling heartbeat

Files:

• Modify: agent/scripts/run_agent_service.py
• Test: agent/tests/test_run_agent_service.py
• Modify on this host only: C:\Program Files\GTI\FiscalAgent\agent.env

Interfaces:

• Config.agent_jobs_enabled parses AGENT_JOBS_ENABLED, default True.

• When false, the loop sleeps for poll_interval_seconds and continues after heartbeat without calling HubClient.next_job().

• Step 1: Add the failing no-poll test

Use a fake Hub whose next_job() raises if called. Make its first heartbeat set the external stop flag. Run one loop cycle with AGENT_JOBS_ENABLED=0 and assert one heartbeat, zero next_job calls, and zero job/classification calls.

• Step 2: Run the focused test and verify failure

Run: python -m pytest agent/tests/test_run_agent_service.py -q Expected: the current loop calls next_job() immediately after heartbeat.

• Step 3: Implement the gate with a backward-compatible default

Parse AGENT_JOBS_ENABLED as enabled unless its stripped, uppercased value is 0, FALSE, or NO. After successful heartbeat, if disabled, sleep once and continue before constructing or calling the job endpoint.

• Step 4: Run focused runtime tests

Run: python -m pytest agent/tests/test_run_agent_service.py -q Expected: disabled polling makes no next_job request; default configuration retains the existing job behavior.

Task 5: Full regressions and guard review

Files:

• Verify: central/tests/, agent/tests/, tests/

• Step 1: Run Hub and Agent regressions

Run: python -m pytest central/tests -q and python -m pytest agent/tests -q. Expected: both suites pass.

• Step 2: Run repository offline regressions

Run: python -m pytest tests -q. Expected: all tests pass with only the repository's pre-existing skip.

• Step 3: Verify write and secret invariants

Assert tests and source still guarantee FIREBIRD_WRITES=0, FISCAL_MODE=DRY_RUN, empty AUTHORIZED_WRITE_DATABASE_PATH, no token in agent.env, and identity endpoint contains only the approved fields. Do not connect to Firebird for this check.

Task 6: Deploy the API and update only the installed service runtime

Files/artifacts:

• Deploy Hub source: central/app/api.py, central/app/agent_distribution.py

• Build artifact: dist/installer/GTIFiscalAgentService/ only

• Existing install: C:\Program Files\GTI\FiscalAgent\GTIFiscalAgentService\

• Step 1: Deploy the Hub code without a migration

Use the approved production deployment path and preserve the existing Hub .env, PostgreSQL volume, release volume, SSO, and DNS. Build/restart only fiscal-hub; verify /health, /version, and authenticated /v1/agents/me/identity return Agent 2's already-existing identity. Do not query the database directly to retrieve the ID.

• Step 2: Build only the service-host onedir

Record SHA-256 of dist/installer/GTIFiscalAgent-Setup-1.1.1.exe before building. Verify no unversioned GTIFiscalAgent-Setup.exe exists, then run scripts/build_windows_installer.ps1 -SkipSetup -SkipUninstall. Confirm the versioned Setup hash is unchanged and no Setup.exe is run.

• Step 3: Back up and replace only the service runtime

With GTIFiscalAgent stopped, copy the current installed GTIFiscalAgentService directory to a timestamped local backup. Replace only that directory with the newly built service onedir. Leave agent.env, credentials.bin, Uninstall.exe, registry/ARP entries, and state files untouched.

• Step 4: Prepare the existing installation for heartbeat-only operation

Elevated-edit agent.env to set AGENT_JOBS_ENABLED=0, preserving FIREBIRD_WRITES=0, FISCAL_MODE=DRY_RUN, the existing Agent ID, Firebird configuration, and SYSTEM/Administrators ACL. Do not put the bearer token in this file.

• Step 5: Verify recovery before SCM start

Run the installed runtime's read-only identity bootstrap/preflight with the existing DPAPI credential. Confirm recovered agent_id=2, installation_id equals the endpoint value, the SQLite state contains that same ID, and jobs are disabled. If any check fails, leave the service stopped.

Task 7: First heartbeat only, then stop

Files:

• Existing Windows service: GTIFiscalAgent

• Existing Hub identity endpoint: GET /v1/agents/me/identity

• Step 1: Capture a baseline

Before service start, record the existing local ipi_write_log row count and confirm service state is STOPPED. Do not call /v1/jobs/next or submit classification requests.

• Step 2: Start the existing service

Run sc.exe start GTIFiscalAgent; wait for SCM state RUNNING and verify the identity endpoint shows agent_id=2, the same stored installation_id, correct hostname, version 1.1.1, and status ONLINE.

• Step 3: Stop immediately after first heartbeat

Run sc.exe stop GTIFiscalAgent; verify STOPPED. Keep AGENT_JOBS_ENABLED=0 in agent.env.

• Step 4: Verify zero jobs and writes

Compare local ipi_write_log count with baseline; assert unchanged and equal to zero. Confirm no classification request or job was sent, FIREBIRD_WRITES=0, and WRITE_ATTEMPTS=0 / WRITE_SUCCESSES=0. Verify authenticated identity still maps to Agent 2 and the original installation ID; do not create or enroll anything.

• Step 5: Verify user-visible status if panel access is available

Confirm Agent 2 displays ONLINE with the host name and version 1.1.1. If the panel requires unavailable human authentication, report the authenticated identity endpoint evidence and leave the panel UI item as a blocker; do not bypass authentication.

Rollback and stop gates

• If Hub identity response is absent, mismatched, or does not name Agent 2, stop before writing the local identity or starting SCM.
• If Hub deployment or service-host replacement fails, restore the backed-up service directory and leave the service stopped.
• If AGENT_JOBS_ENABLED=0 is not verified, do not start the service.
• If preflight, identity, hostname, version, or write guards fail, stop and report; do not retry enrollment, generate another UUID, run a job, or write Firebird.