fix: persist and recover the Agent's real installation_id (heartbeat activation)

POST /v1/agents/enroll now returns installation_id; new installs persist it
to agent.env immediately. Runtime recovery precedence: existing SQLite
installation_identity -> configured INSTALLATION_ID -> authenticated
GET /v1/agents/me/identity. Recovery fails closed on missing/malformed/
mismatched identity rather than inventing a UUID (which the Hub would then
reject as a conflicting Installation on an already-enrolled Agent). An
explicit AGENT_JOBS_ENABLED gate stops the service from claiming a job right
after the first heartbeat.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

agent/src/gti_fiscal_agent/client.py

@@ -13,6 +13,7 @@ class HubClient:
     def get_json(self, path):
         response = httpx.get(f"{self.url}{path}", headers=self._headers(), timeout=30)
         response.raise_for_status(); return response.json()
+    def identity(self): return self.get_json("/v1/agents/me/identity")
     def health(self):
         response = httpx.get(f"{self.url}/health", timeout=10)
         return response.status_code == 200

agent/src/gti_fiscal_agent/state.py

@@ -9,12 +9,31 @@ class AgentState:
         self.connection.executescript("CREATE TABLE IF NOT EXISTS product_state(product_id TEXT PRIMARY KEY, source_fingerprint TEXT NOT NULL, dataset_version TEXT NOT NULL, engine_version TEXT NOT NULL, status TEXT NOT NULL, last_processed_at TEXT, last_result_hash TEXT, reason_code TEXT); CREATE TABLE IF NOT EXISTS outbox(product_id TEXT PRIMARY KEY, source_fingerprint TEXT NOT NULL, status TEXT NOT NULL, retries INTEGER NOT NULL DEFAULT 0); CREATE TABLE IF NOT EXISTS ipi_write_log(product_id TEXT NOT NULL, source_fingerprint TEXT NOT NULL, decision_status TEXT, ipi_status TEXT, write_status TEXT NOT NULL, before_value TEXT, proposed_value TEXT, result TEXT, reason_code TEXT, timestamp TEXT NOT NULL);")
         self.connection.execute("CREATE TABLE IF NOT EXISTS installation_identity (id INTEGER PRIMARY KEY CHECK(id=1), installation_id TEXT NOT NULL)")
         self.connection.commit()
-    def installation_id(self):
+    def stored_installation_id(self):
         row = self.connection.execute("SELECT installation_id FROM installation_identity WHERE id=1").fetchone()
-        if row:
-            return row["installation_id"]
-        value = str(uuid.uuid4())
-        self.connection.execute("INSERT INTO installation_identity(id, installation_id) VALUES(1, ?)", (value,)); self.connection.commit()
+        if row is None:
+            return None
+        try:
+            return str(uuid.UUID(row["installation_id"]))
+        except (TypeError, ValueError, AttributeError) as error:
+            raise ValueError("stored installation_id is not a valid UUID") from error
+    def installation_id(self, candidate=None):
+        existing = self.stored_installation_id()
+        if existing:
+            if candidate is not None and str(uuid.UUID(str(candidate))) != existing:
+                raise ValueError("configured installation_id conflicts with persisted identity")
+            return existing
+        if candidate is None or not str(candidate).strip():
+            raise ValueError("installation_id is required; refusing to generate a new identity")
+        try:
+            value = str(uuid.UUID(str(candidate)))
+        except (TypeError, ValueError, AttributeError) as error:
+            raise ValueError("installation_id must be a valid UUID") from error
+        self.connection.execute("INSERT OR IGNORE INTO installation_identity(id, installation_id) VALUES(1, ?)", (value,))
+        self.connection.commit()
+        row = self.connection.execute("SELECT installation_id FROM installation_identity WHERE id=1").fetchone()
+        if row is None or str(uuid.UUID(row["installation_id"])) != value:
+            raise ValueError("persisted installation_id conflicts with candidate")
         return value
     def enqueue(self, product_id, source_fingerprint, dataset_version, engine_version):
         row = self.connection.execute("SELECT * FROM product_state WHERE product_id=?", (product_id,)).fetchone()