AgentCompany/docs/2026-03-18-cross-feature-integrity-audit.md

AgentCompany Cross-Feature Integrity Audit (2026-03-18)

Scope

• PRD.md
• Electron runtime code under src/main, src/preload, src/renderer, src/shared
• Connector adapters under packages/*
• Build and packaging config: package.json, electron-builder.yml, electron.vite.config.ts, scripts/build-desktop.mjs
• Existing validation assets under tests/unit, tests/integration, tests/e2e
• Current Electron guidance and packaging guidance from official Electron and electron-builder documentation

Pipeline Mapping

Phase 1: ProjectManager

• Confirmed product target remains a local-first Electron desktop control plane, not a browser-shaped admin shell.
• Current milestone for this remediation wave: cross-feature integrity, autonomous execution gating, and release validation.

Phase 2: ResearchAnalyst

• Checked current Electron guidance for:
  • context isolation and preload boundaries
  • sandbox and navigation restrictions
  • utility-process usage
  • packaging and update prerequisites

Phase 3: TechnicalImplementationResearcher

• Traced how connector health, onboarding, hiring, orchestration, snapshot loading, and renderer forms interact.
• Focused on defects where one subsystem looked valid locally but corrupted another subsystem at runtime.

Phase 4: EnterpriseArchitect

• Validated that the highest-severity current issues were policy drift and hidden truncation, not absence of feature surfaces.
• Chose to fix shared policy and shared data integrity before any cosmetic refactor.

What Is Already Real

• Main / preload / renderer separation exists.
• Renderer does not depend on direct Node access.
• SQLite-backed local-first persistence exists.
• The app already contains real systems for onboarding, companies, agents, goals, projects, tasks, approvals, runs, costs, meetings, knowledge, documents, social accounts, automation, messaging, and packaging.
• Worker execution already runs outside the renderer.

Highest-Severity Findings From This Audit

1. Global snapshot truncation polluted company-scoped behavior

Source:

• src/main/database.ts

Problem:

• listSnapshot() hard-capped runs, cost_entries, agent_messages, and activity.
• listRendererSnapshot() then filtered that already-truncated global result down to the current company.
• This allowed newer rows from other companies to displace current-company runs, messages, costs, and activity from the renderer snapshot.

Why this matters:

• Inbox severity, board unread counts, standup summaries, cost totals, run history, and communication history could silently diverge from real persisted state.
• The defect was cross-feature by construction because multiple views derived from the same truncated snapshot.

2. Connector policy drift allowed non-production runtimes onto the main execution path

Sources:

• src/main/onboarding-service.ts
• src/main/orchestration-service.ts
• src/main/ipc-core-work-graph-handlers.ts
• src/main/api-server.ts
• src/renderer/components/CompanyOnboarding.tsx
• src/renderer/components/organization.tsx
• src/main/connectors.ts
• packages/adapter-kimi-local/src/server/test.ts

Problem:

• Health checks marked generic or partial runtimes as degraded.
• Onboarding and orchestration still treated degraded as runnable.
• Hiring and agent editing could still bind agents to connectors that were not suitable for autonomous execution.
• kimi_local was explicitly documented as generic downgraded mode but was still able to enter product-critical flows.

Why this matters:

• The app could create or keep agents on runtimes that do not guarantee session resume or structured transcripts.
• That breaks the internal coordination model because messaging, run tracking, recovery, and auditability depend on a stable execution contract.

3. Policy enforcement was inconsistent across desktop UI, IPC, and local agent API

Problem:

• Even if the renderer restricted a path, API or IPC handlers could still write invalid connector assignments unless the same rule existed server-side.

Why this matters:

• The system would appear correct in one surface and remain invalid in another.
• That is an integrity failure, not a pure UI bug.

4. Architecture remains operationally real but still too concentrated

Largest modules remain heavy:

• src/main/database.ts
• src/main/api-server.ts
• src/main/automation-service.ts
• src/main/prompt-builder.ts
• src/renderer/App.tsx
• src/renderer/components/communication.tsx
• src/renderer/components/execution.tsx

Interpretation:

• The app is no longer a blank prototype, but some boundaries are still broader than a stable long-term production shape.
• This is a structural follow-up item, not a reason to leave integrity bugs unfixed.

Remediation Implemented In This Wave

Shared connector execution policy

• Added src/shared/connector-policy.ts.
• Defined a single execution-readiness rule used by main and renderer.
• Autonomous execution now requires:
  • connector status ready
  • session resume support
  • structured transcript support

Snapshot integrity correction

• Kept protective limits on the global snapshot path used by broad system scans.
• Moved renderer and company analytics onto company-scoped SQL reads instead of filtering a global snapshot in memory.
• Added company + created_at indexes so the scoped history reads can stay predictable as data grows.

Main-side enforcement

• Onboarding now rejects non-execution-ready connectors instead of silently falling back.
• Orchestration now blocks autonomous runs when the connector is not execution-ready.
• IPC agent save / hire request paths now reject non-execution-ready connectors.
• Local agent API hire requests now reject non-execution-ready connectors.

Renderer alignment

• Onboarding only offers execution-ready connectors and explains why others are blocked.
• Agent creation only offers execution-ready connectors.
• Agent editing keeps blocked current connectors visible for repair, but prevents saving or waking until the agent is moved onto a ready connector.
• Dashboard connector health now uses the same execution-readiness rule as onboarding and orchestration.

Verification Executed

• pnpm typecheck
• pnpm lint
• pnpm test:unit
• pnpm test:integration
• pnpm test:e2e
• AGENTCOMPANY_BUILD_VERSION=0.4.39 pnpm build

Build artifact produced in this session:

• build/release/AgentCompany-0.4.39-arm64-mac.zip

Adversarial Review Outcome

• Reviewer CLI used: claude -p
• Lenses run: skeptic, architect, minimalist
• Accepted findings from that pass:
  • global LIMIT removal was the wrong fix; replaced with company-scoped SQL snapshot reads while keeping global caps
  • connector lookup failure needed structured CONNECTOR_NOT_FOUND handling instead of uncaught throws
  • dashboard readiness needed to use the same connector policy as onboarding and orchestration
• Rejected findings from that pass:
  • version bump concerns were procedural, not product risk
  • pure shared readiness helpers used by renderer were acceptable because they remain data-only and build-safe in the current architecture

Residual Risks Still Present After This Wave

1. Preload surface is still broad

• It is typed, but still larger than ideal for a final hardened desktop app.

2. Several modules are still too large

• The codebase still needs deeper boundary extraction in database, api-server, automation-service, renderer shell composition, and some feature panels.

3. Cross-platform packaging has not yet been runtime-verified on all target OSes in this session

• Packaging config exists for macOS, Windows, and Linux.
• This session validated macOS packaging only.

4. Signing / updater production readiness still depends on release credentials and environment

• The code and config exist, but release trust still depends on actual signing/notarization/update infrastructure material.

External References Used

• Electron security checklist:
  • https://www.electronjs.org/docs/latest/tutorial/security
• Electron context bridge:
  • https://www.electronjs.org/docs/latest/api/context-bridge
• Electron utility process:
  • https://www.electronjs.org/docs/latest/api/utility-process
• electron-builder auto-update:
  • https://www.electron.build/auto-update
• electron-builder macOS code signing:
  • https://www.electron.build/code-signing-mac