aios-management-web 0.1.0

package/server/test/catalog-sync-service.test.js

@@ -0,0 +1,920 @@
+import { DatabaseSync } from "node:sqlite";
+
+import { AgentStatusSyncService } from "../src/services/agent-status-sync-service.js";
+import { CatalogSyncService } from "../src/services/catalog-sync-service.js";
+
+const TEST_NOW = "2026-05-26T00:00:00.000Z";
+
+function insertAgent(db, {
+  slug,
+  agentName = slug,
+  description = "",
+  docsContent = "",
+  templateName = "default",
+  status = "normal",
+  tagsJson = "[]",
+  dailyLimit = -1,
+  usageSnapshotJson = "{}",
+  remoteStateJson = "{}",
+  createdAt = TEST_NOW,
+  updatedAt = TEST_NOW
+}) {
+  return db.prepare(`
+    INSERT INTO agents (
+      slug, agent_name, description, docs_content, template_name, status, tags_json,
+      daily_limit, usage_snapshot_json, remote_state_json, created_at, updated_at
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    slug,
+    agentName,
+    description,
+    docsContent,
+    templateName,
+    status,
+    tagsJson,
+    dailyLimit,
+    usageSnapshotJson,
+    remoteStateJson,
+    createdAt,
+    updatedAt
+  );
+}
+
+function createDb() {
+  const db = new DatabaseSync(":memory:");
+  db.exec(`
+    PRAGMA foreign_keys = ON;
+
+    CREATE TABLE usage_refresh_state (
+      id INTEGER PRIMARY KEY CHECK (id = 1),
+      status TEXT NOT NULL,
+      trigger_source TEXT,
+      started_at TEXT,
+      finished_at TEXT,
+      last_success_at TEXT,
+      error_message TEXT,
+      summary_json TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    );
+
+    CREATE TABLE agent_sync_state (
+      id INTEGER PRIMARY KEY CHECK (id = 1),
+      status TEXT NOT NULL,
+      trigger_source TEXT,
+      started_at TEXT,
+      finished_at TEXT,
+      last_success_at TEXT,
+      error_message TEXT,
+      summary_json TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    );
+
+    CREATE TABLE skill_sync_state (
+      id INTEGER PRIMARY KEY CHECK (id = 1),
+      status TEXT NOT NULL,
+      trigger_source TEXT,
+      started_at TEXT,
+      finished_at TEXT,
+      last_success_at TEXT,
+      error_message TEXT,
+      summary_json TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    );
+
+    CREATE TABLE template_sync_state (
+      id INTEGER PRIMARY KEY CHECK (id = 1),
+      status TEXT NOT NULL,
+      trigger_source TEXT,
+      started_at TEXT,
+      finished_at TEXT,
+      last_success_at TEXT,
+      error_message TEXT,
+      summary_json TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    );
+
+    CREATE TABLE system_sync_state (
+      id INTEGER PRIMARY KEY CHECK (id = 1),
+      status TEXT NOT NULL,
+      trigger_source TEXT,
+      started_at TEXT,
+      finished_at TEXT,
+      last_success_at TEXT,
+      error_message TEXT,
+      summary_json TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    );
+
+    CREATE TABLE artifacts (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      kind TEXT NOT NULL,
+      bucket TEXT NOT NULL,
+      object_key TEXT NOT NULL,
+      original_name TEXT NOT NULL,
+      mime_type TEXT NOT NULL,
+      byte_size INTEGER NOT NULL,
+      created_by INTEGER,
+      created_at TEXT NOT NULL
+    );
+
+    CREATE TABLE agents (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      slug TEXT NOT NULL UNIQUE,
+      agent_name TEXT NOT NULL,
+      description TEXT NOT NULL,
+      docs_content TEXT NOT NULL,
+      template_name TEXT NOT NULL DEFAULT 'default',
+      status TEXT NOT NULL,
+      tags_json TEXT NOT NULL,
+      daily_limit INTEGER NOT NULL,
+      usage_snapshot_json TEXT NOT NULL,
+      remote_state_json TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    );
+
+    CREATE TABLE external_sessions (
+      session_id TEXT PRIMARY KEY,
+      aios_user_id INTEGER NOT NULL,
+      agent_id INTEGER NOT NULL,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      UNIQUE (aios_user_id, agent_id),
+      FOREIGN KEY (agent_id) REFERENCES agents(id) ON DELETE CASCADE,
+      FOREIGN KEY (aios_user_id) REFERENCES aios_users(id) ON DELETE CASCADE
+    );
+
+    CREATE TABLE aios_users (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      username TEXT NOT NULL UNIQUE,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    );
+
+    CREATE TABLE agent_permissions (
+      agent_id INTEGER NOT NULL,
+      aios_user_id INTEGER NOT NULL,
+      PRIMARY KEY (agent_id, aios_user_id),
+      FOREIGN KEY (agent_id) REFERENCES agents(id) ON DELETE CASCADE,
+      FOREIGN KEY (aios_user_id) REFERENCES aios_users(id) ON DELETE CASCADE
+    );
+
+    CREATE TABLE agent_templates (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      template_name TEXT NOT NULL UNIQUE,
+      description TEXT NOT NULL,
+      artifact_id INTEGER NOT NULL,
+      remote_status TEXT NOT NULL,
+      remote_result_json TEXT,
+      is_builtin INTEGER NOT NULL DEFAULT 0,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    );
+
+    CREATE TABLE skills (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      slug TEXT NOT NULL UNIQUE,
+      description TEXT NOT NULL,
+      artifact_id INTEGER,
+      remote_status TEXT NOT NULL,
+      is_builtin INTEGER NOT NULL DEFAULT 0,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    );
+
+    CREATE TABLE agent_skill_bindings (
+      agent_id INTEGER NOT NULL,
+      skill_id INTEGER NOT NULL,
+      PRIMARY KEY (agent_id, skill_id),
+      FOREIGN KEY (agent_id) REFERENCES agents(id) ON DELETE CASCADE,
+      FOREIGN KEY (skill_id) REFERENCES skills(id) ON DELETE CASCADE
+    );
+
+    CREATE TABLE business_systems (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      provider TEXT NOT NULL,
+      application_name TEXT NOT NULL UNIQUE,
+      description TEXT NOT NULL,
+      ontology_artifact_id INTEGER,
+      scheme TEXT NOT NULL,
+      host TEXT NOT NULL,
+      port INTEGER NOT NULL,
+      status TEXT NOT NULL,
+      last_connectivity_test_status TEXT NOT NULL,
+      last_connectivity_test_result_json TEXT NOT NULL,
+      is_builtin INTEGER NOT NULL DEFAULT 0,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    );
+
+  `);
+
+  for (const tableName of [
+    "usage_refresh_state",
+    "agent_sync_state",
+    "skill_sync_state",
+    "template_sync_state",
+    "system_sync_state"
+  ]) {
+    db.prepare(`
+      INSERT INTO ${tableName} (
+        id, status, trigger_source, started_at, finished_at, last_success_at,
+        error_message, summary_json, created_at, updated_at
+      ) VALUES (1, 'idle', NULL, NULL, NULL, NULL, NULL, '{}', ?, ?)
+    `).run("2026-05-26T00:00:00.000Z", "2026-05-26T00:00:00.000Z");
+  }
+
+  return db;
+}
+
+it("syncs remote agents into sqlite and preserves local-only fields", async () => {
+  const db = createDb();
+  insertAgent(db, {
+    slug: "alpha",
+    agentName: "Alpha Agent",
+    description: "keep-me",
+    usageSnapshotJson: JSON.stringify({
+      usage: {
+        daily: 1,
+        weekly: 2,
+        monthly: 3,
+        total: 4
+      }
+    })
+  });
+  insertAgent(db, {
+    slug: "stale-agent",
+    agentName: "Stale Agent"
+  });
+  const staleAgentId = db.prepare("SELECT id FROM agents WHERE slug = ?").get("stale-agent").id;
+  const userResult = db.prepare(`
+    INSERT INTO aios_users (
+      username, created_at, updated_at
+    ) VALUES (?, ?, ?)
+  `).run(
+    "user-a",
+    TEST_NOW,
+    TEST_NOW
+  );
+  db.prepare(`
+    INSERT INTO agent_permissions (agent_id, aios_user_id)
+    VALUES (?, ?)
+  `).run(staleAgentId, userResult.lastInsertRowid);
+  db.prepare(`
+    INSERT INTO external_sessions (
+      session_id, aios_user_id, agent_id, created_at, updated_at
+    ) VALUES (?, ?, ?, ?, ?)
+  `).run(
+    "session-stale",
+    userResult.lastInsertRowid,
+    staleAgentId,
+    "2026-05-26T00:00:00.000Z",
+    "2026-05-26T00:00:00.000Z"
+  );
+
+  const service = new CatalogSyncService({
+    db,
+    rpcClient: {
+      isConfigured() {
+        return true;
+      },
+      async call(action, params, timeoutMs) {
+        if (action === "agent.list") {
+          return {
+            items: [{
+              agentId: "alpha",
+              name: "Alpha Remote",
+              status: "active"
+            }]
+          };
+        }
+
+        throw new Error(`Unexpected action: ${action}`);
+      }
+    },
+    env: {
+      managementTimeoutMs: 120000
+    }
+  });
+
+  const status = await service.syncAgentsTask({ trigger: "manual" });
+
+  expect(status.status).toBe("success");
+  expect(status.summary).toEqual({
+    agents: 1
+  });
+
+  const agent = db.prepare("SELECT * FROM agents WHERE slug = ?").get("alpha");
+  expect(agent.description).toBe("keep-me");
+  expect(agent.agent_name).toBe("Alpha Remote");
+  expect(agent.status).toBe("normal");
+  expect(JSON.parse(agent.usage_snapshot_json).usage).toEqual({
+    daily: 1
+  });
+  expect(db.prepare("SELECT * FROM agents WHERE slug = ?").get("stale-agent")).toBeUndefined();
+  expect(db.prepare(`
+    SELECT COUNT(*) AS count
+    FROM agent_permissions
+    WHERE agent_id = ?
+  `).get(staleAgentId).count).toBe(0);
+  expect(db.prepare("SELECT COUNT(*) AS count FROM external_sessions WHERE agent_id = ?").get(staleAgentId).count).toBe(0);
+});
+
+it("syncs templates, skills and systems into their own state tables", async () => {
+  const db = createDb();
+  const missingSkillResult = db.prepare(`
+    INSERT INTO skills (
+      slug, description, artifact_id, remote_status, created_at, updated_at
+    ) VALUES (?, ?, ?, ?, ?, ?)
+  `).run(
+    "missing-global",
+    "",
+    null,
+    "installed",
+    "2026-05-26T00:00:00.000Z",
+    "2026-05-26T00:00:00.000Z"
+  );
+  insertAgent(db, {
+    slug: "skill-owner",
+    agentName: "Skill Owner"
+  });
+  const skillOwnerId = db.prepare("SELECT id FROM agents WHERE slug = ?").get("skill-owner").id;
+  db.prepare(`
+    INSERT INTO agent_skill_bindings (agent_id, skill_id)
+    VALUES (?, ?)
+  `).run(skillOwnerId, missingSkillResult.lastInsertRowid);
+  const staleTemplateArtifact = db.prepare(`
+    INSERT INTO artifacts (
+      kind, bucket, object_key, original_name, mime_type, byte_size, created_by, created_at
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    "template",
+    "",
+    "",
+    "stale-template.remote",
+    "application/octet-stream",
+    0,
+    null,
+    "2026-05-26T00:00:00.000Z"
+  );
+  db.prepare(`
+    INSERT INTO agent_templates (
+      template_name, description, artifact_id, remote_status, remote_result_json,
+      created_at, updated_at
+    ) VALUES (?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    "stale-template",
+    "",
+    staleTemplateArtifact.lastInsertRowid,
+    "ready",
+    "{}",
+    "2026-05-26T00:00:00.000Z",
+    "2026-05-26T00:00:00.000Z"
+  );
+  db.prepare(`
+    INSERT INTO business_systems (
+      provider, application_name, description, ontology_artifact_id,
+      scheme, host, port, status, last_connectivity_test_status, last_connectivity_test_result_json,
+      created_at, updated_at
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    "hzg",
+    "stale-local",
+    "delete-local",
+    null,
+    "http",
+    "stale.example.com",
+    8081,
+    "active",
+    "unknown",
+    "{}",
+    "2026-05-26T00:00:00.000Z",
+    "2026-05-26T00:00:00.000Z"
+  );
+  db.prepare(`
+    INSERT INTO business_systems (
+      provider, application_name, description, ontology_artifact_id,
+      scheme, host, port, status, last_connectivity_test_status, last_connectivity_test_result_json,
+      created_at, updated_at
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    "hzg",
+    "crm",
+    "keep-local",
+    null,
+    "http",
+    "crm.example.com",
+    8080,
+    "active",
+    "unknown",
+    "{}",
+    "2026-05-26T00:00:00.000Z",
+    "2026-05-26T00:00:00.000Z"
+  );
+
+  const service = new CatalogSyncService({
+    db,
+    rpcClient: {
+      isConfigured() {
+        return true;
+      },
+      async call(action) {
+        if (action === "agent.template.list") {
+          return {
+            items: [{
+              templateName: "default",
+              path: "/var/aios/workspace-templates/default",
+              "is-built-in": true
+            }]
+          };
+        }
+        if (action === "skills.global.list") {
+          return {
+            items: [{
+              slug: "global-skill",
+              "is-built-in": true,
+              origin: {
+                slug: "global-skill",
+                description: "from kernel"
+              }
+            }]
+          };
+        }
+        if (action === "apps.list") {
+          return {
+            items: [{
+              id: "crm",
+              name: "CRM"
+            }]
+          };
+        }
+        if (action === "ontology.list") {
+          return {
+            items: [{
+              name: "crm",
+              "is-built-in": true
+            }]
+          };
+        }
+        throw new Error(`Unexpected action: ${action}`);
+      }
+    }
+  });
+
+  const [templateStatus, skillStatus, systemStatus] = await Promise.all([
+    service.syncTemplatesTask({ trigger: "manual" }),
+    service.syncSkillsTask({ trigger: "manual" }),
+    service.syncSystemsTask({ trigger: "manual" })
+  ]);
+
+  expect(templateStatus.summary).toEqual({ templates: 1 });
+  expect(skillStatus.summary).toEqual({ skills: 1 });
+  expect(systemStatus.summary).toEqual({ systems: 1 });
+
+  const template = db.prepare("SELECT * FROM agent_templates WHERE template_name = ?").get("default");
+  const skill = db.prepare("SELECT * FROM skills WHERE slug = ?").get("global-skill");
+  expect(template.remote_status).toBe("ready");
+  expect(template.is_builtin).toBe(1);
+  expect(skill.remote_status).toBe("installed");
+  expect(skill.is_builtin).toBe(1);
+  expect(db.prepare("SELECT * FROM skills WHERE slug = ?").get("missing-global")).toBeUndefined();
+  expect(db.prepare("SELECT COUNT(*) AS count FROM agent_skill_bindings WHERE skill_id = ?").get(missingSkillResult.lastInsertRowid).count).toBe(0);
+  expect(db.prepare("SELECT * FROM agent_templates WHERE template_name = ?").get("stale-template")).toBeUndefined();
+  expect(db.prepare("SELECT * FROM business_systems WHERE application_name = ?").get("crm").is_builtin).toBe(1);
+  expect(db.prepare("SELECT * FROM business_systems WHERE application_name = ?").get("stale-local")).toBeUndefined();
+});
+
+it("keeps local catalog rows when kernel sync fails", async () => {
+  const db = createDb();
+  insertAgent(db, {
+    slug: "local-agent",
+    agentName: "Local Agent"
+  });
+  const templateArtifact = db.prepare(`
+    INSERT INTO artifacts (
+      kind, bucket, object_key, original_name, mime_type, byte_size, created_by, created_at
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    "template",
+    "",
+    "",
+    "local-template.remote",
+    "application/octet-stream",
+    0,
+    null,
+    "2026-05-26T00:00:00.000Z"
+  );
+  db.prepare(`
+    INSERT INTO agent_templates (
+      template_name, description, artifact_id, remote_status, remote_result_json,
+      created_at, updated_at
+    ) VALUES (?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    "local-template",
+    "",
+    templateArtifact.lastInsertRowid,
+    "ready",
+    "{}",
+    "2026-05-26T00:00:00.000Z",
+    "2026-05-26T00:00:00.000Z"
+  );
+  db.prepare(`
+    INSERT INTO skills (
+      slug, description, artifact_id, remote_status, created_at, updated_at
+    ) VALUES (?, ?, ?, ?, ?, ?)
+  `).run(
+    "local-skill",
+    "",
+    null,
+    "installed",
+    "2026-05-26T00:00:00.000Z",
+    "2026-05-26T00:00:00.000Z"
+  );
+  db.prepare(`
+    INSERT INTO business_systems (
+      provider, application_name, description, ontology_artifact_id,
+      scheme, host, port, status, last_connectivity_test_status, last_connectivity_test_result_json,
+      created_at, updated_at
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    "hzg",
+    "local-system",
+    "",
+    null,
+    "http",
+    "local.example.com",
+    8080,
+    "active",
+    "unknown",
+    "{}",
+    "2026-05-26T00:00:00.000Z",
+    "2026-05-26T00:00:00.000Z"
+  );
+
+  const service = new CatalogSyncService({
+    db,
+    rpcClient: {
+      isConfigured() {
+        return true;
+      },
+      async call() {
+        throw new Error("kernel unavailable");
+      }
+    }
+  });
+
+  const agentStatus = await service.syncAgentsTask({ trigger: "manual" });
+  const templateStatus = await service.syncTemplatesTask({ trigger: "manual" });
+  const skillStatus = await service.syncSkillsTask({ trigger: "manual" });
+  const systemStatus = await service.syncSystemsTask({ trigger: "manual" });
+
+  expect(agentStatus.status).toBe("failed");
+  expect(templateStatus.status).toBe("failed");
+  expect(skillStatus.status).toBe("failed");
+  expect(systemStatus.status).toBe("failed");
+  expect(db.prepare("SELECT * FROM agents WHERE slug = ?").get("local-agent")).toBeDefined();
+  expect(db.prepare("SELECT * FROM agent_templates WHERE template_name = ?").get("local-template")).toBeDefined();
+  expect(db.prepare("SELECT * FROM skills WHERE slug = ?").get("local-skill")).toBeDefined();
+  expect(db.prepare("SELECT * FROM business_systems WHERE application_name = ?").get("local-system")).toBeDefined();
+});
+
+it("refreshes agent usage snapshots with kernel stock values", async () => {
+  const db = createDb();
+  insertAgent(db, {
+    slug: "alpha",
+    agentName: "Alpha",
+    status: "active",
+    usageSnapshotJson: JSON.stringify({
+      usage: {
+        daily: 1,
+        weekly: 2,
+        monthly: 3,
+        total: 10
+      }
+    })
+  });
+
+  const service = new CatalogSyncService({
+    db,
+    auditLogService: {
+      write() {}
+    },
+    rpcClient: {
+      isConfigured() {
+        return true;
+      },
+      async call(action) {
+        if (action !== "agent.usage") {
+          throw new Error(`Unexpected action: ${action}`);
+        }
+
+        return {
+          usage: {
+            daily: 4
+          }
+        };
+      }
+    }
+  });
+
+  const result = await service.refreshAgentUsage({ trigger: "scheduled" });
+
+  expect(result.status).toBe("success");
+  expect(result.trigger_source).toBe("scheduled");
+  expect(result.summary.refreshed_agents).toBe(1);
+  expect(result.summary.captured_at).toContain("T");
+
+  const agent = db.prepare("SELECT * FROM agents WHERE slug = ?").get("alpha");
+  expect(JSON.parse(agent.usage_snapshot_json).usage).toEqual({
+    daily: 4
+  });
+});
+
+it("overwrites agent usage snapshots with latest kernel stock values", async () => {
+  const db = createDb();
+  insertAgent(db, {
+    slug: "alpha",
+    agentName: "Alpha"
+  });
+  const usageValues = [4, 6];
+  const service = new CatalogSyncService({
+    db,
+    rpcClient: {
+      isConfigured() {
+        return true;
+      },
+      async call(action) {
+        if (action !== "agent.usage") {
+          throw new Error(`Unexpected action: ${action}`);
+        }
+
+        return {
+          usage: {
+            daily: usageValues.shift()
+          }
+        };
+      }
+    }
+  });
+
+  await service.refreshAgentUsage({ trigger: "scheduled" });
+  await service.refreshAgentUsage({ trigger: "scheduled" });
+
+  const agent = db.prepare("SELECT * FROM agents WHERE slug = ?").get("alpha");
+  expect(JSON.parse(agent.usage_snapshot_json).usage).toEqual({
+    daily: 6
+  });
+});
+
+it("does not write audit logs during agent usage refresh", async () => {
+  const db = createDb();
+  insertAgent(db, {
+    slug: "alpha",
+    agentName: "Alpha",
+    status: "active"
+  });
+  const auditWrites = [];
+
+  const service = new CatalogSyncService({
+    db,
+    auditLogService: {
+      write(entry) {
+        auditWrites.push(entry);
+      }
+    },
+    rpcClient: {
+      isConfigured() {
+        return true;
+      },
+      async call(action) {
+        if (action !== "agent.usage") {
+          throw new Error(`Unexpected action: ${action}`);
+        }
+
+        return {
+          usage: {
+            daily: 4
+          }
+        };
+      }
+    }
+  });
+
+  const result = await service.refreshAgentUsage({ trigger: "scheduled" });
+
+  expect(result.status).toBe("success");
+  expect(auditWrites).toEqual([]);
+});
+
+it("moves non-disabled agents to overlimit when refreshed usage reaches quota", async () => {
+  const db = createDb();
+  insertAgent(db, {
+    slug: "alpha",
+    agentName: "Alpha",
+    dailyLimit: 10
+  });
+  insertAgent(db, {
+    slug: "beta",
+    agentName: "Beta",
+    status: "disabled",
+    dailyLimit: 10
+  });
+
+  const service = new CatalogSyncService({
+    db,
+    auditLogService: {
+      write() {}
+    },
+    rpcClient: {
+      isConfigured() {
+        return true;
+      },
+      async call(action, params) {
+        if (action !== "agent.usage") {
+          throw new Error(`Unexpected action: ${action}`);
+        }
+
+        return {
+          usage: {
+            daily: params.agentId === "alpha" ? 12 : 20,
+          }
+        };
+      }
+    }
+  });
+
+  const result = await service.refreshAgentUsage({ trigger: "scheduled" });
+
+  expect(result.status).toBe("success");
+  expect(db.prepare("SELECT status FROM agents WHERE slug = ?").get("alpha").status).toBe("overlimit");
+  expect(db.prepare("SELECT status FROM agents WHERE slug = ?").get("beta").status).toBe("disabled");
+});
+
+it("serializes concurrent sqlite write transactions across sync services", async () => {
+  const db = createDb();
+  insertAgent(db, {
+    slug: "alpha",
+    agentName: "Alpha",
+    usageSnapshotJson: JSON.stringify({
+      usage: {
+        daily: 1,
+        weekly: 2,
+        monthly: 3,
+        total: 10
+      }
+    })
+  });
+
+  let releaseUsageCall;
+  const usageBlocked = new Promise((resolve) => {
+    releaseUsageCall = resolve;
+  });
+
+  const sharedRpcClient = {
+    isConfigured() {
+      return true;
+    },
+    async call(action) {
+      if (action === "agent.usage") {
+        await usageBlocked;
+        return {
+          usage: {
+            daily: 4
+          }
+        };
+      }
+
+      if (action === "agent.list") {
+        return {
+          items: [{
+            agentId: "alpha",
+            name: "Alpha Remote",
+            status: "active"
+          }]
+        };
+      }
+
+      throw new Error(`Unexpected action: ${action}`);
+    }
+  };
+
+  const catalogSyncService = new CatalogSyncService({
+    db,
+    rpcClient: sharedRpcClient,
+    auditLogService: {
+      write() {}
+    }
+  });
+  const agentStatusSyncService = new AgentStatusSyncService({
+    db,
+    rpcClient: sharedRpcClient,
+    auditLogService: {
+      write() {}
+    }
+  });
+
+  const usagePromise = catalogSyncService.refreshAgentUsage({ trigger: "scheduled" });
+  const statusPromise = agentStatusSyncService.refreshStatuses({ trigger: "scheduled" });
+
+  releaseUsageCall();
+
+  const [usageResult, statusResult] = await Promise.all([usagePromise, statusPromise]);
+
+  expect(usageResult.status).toBe("success");
+  expect(statusResult.status).toBe("success");
+  expect(statusResult.updated_agents).toBe(1);
+
+  const agent = db.prepare("SELECT * FROM agents WHERE slug = ?").get("alpha");
+  expect(agent.status).toBe("normal");
+  expect(agent.agent_name).toBe("Alpha Remote");
+  expect(JSON.parse(agent.usage_snapshot_json).usage.daily).toBe(4);
+});
+
+it("records skipped status when rpc is not configured", async () => {
+  const db = createDb();
+  const service = new CatalogSyncService({
+    db,
+    rpcClient: {
+      isConfigured() {
+        return false;
+      }
+    }
+  });
+
+  const status = await service.syncAgentsTask({ trigger: "startup" });
+
+  expect(status.status).toBe("skipped");
+  expect(status.trigger_source).toBe("startup");
+  expect(status.error_message).toContain("not configured");
+});
+
+it("fails usage refresh when agent.usage returns a non-usage payload", async () => {
+  const db = createDb();
+  insertAgent(db, {
+    slug: "alpha",
+    agentName: "Alpha",
+    status: "active"
+  });
+
+  const service = new CatalogSyncService({
+    db,
+    rpcClient: {
+      isConfigured() {
+        return true;
+      },
+      async call(action) {
+        if (action !== "agent.usage") {
+          throw new Error(`Unexpected action: ${action}`);
+        }
+
+        return {
+          configPath: "/var/aios/.openclaw/openclaw.json",
+          defaultModel: "corp-openai/gpt-5.4"
+        };
+      }
+    }
+  });
+
+  const result = await service.refreshAgentUsage({ trigger: "scheduled" });
+
+  expect(result.status).toBe("failed");
+  expect(result.error_message).toContain("usage fields");
+});
+
+it("does not sample agent usage during agent sync", async () => {
+  const db = createDb();
+  const calls = [];
+
+  const service = new CatalogSyncService({
+    db,
+    rpcClient: {
+      isConfigured() {
+        return true;
+      },
+      async call(action) {
+        calls.push(action);
+        if (action === "agent.list") {
+          return {
+            items: [
+              { agentId: "alpha", name: "Alpha", status: "active" },
+              { agentId: "beta", name: "Beta", status: "active" },
+              { agentId: "gamma", name: "Gamma", status: "active" }
+            ]
+          };
+        }
+
+        throw new Error(`Unexpected action: ${action}`);
+      }
+    }
+  });
+
+  const result = await service.syncAgentsTask({ trigger: "manual" });
+  expect(result.status).toBe("success");
+  expect(result.summary).toEqual({ agents: 3 });
+  expect(calls).toEqual(["agent.list"]);
+});