AgentCompany/docs/2026-03-18-integrated-audit-matrix.md

AgentCompany Integrated Audit Matrix (2026-03-18)

Scope

This audit covered:

• PRD.md
• Electron main / preload / renderer source under src/main, src/preload, src/renderer, src/shared
• Packaging and runtime config: electron-builder.yml, electron.vite.config.ts, scripts/build-desktop.mjs
• Existing validation assets under tests/unit, tests/integration, tests/e2e
• Runtime validation through a live Electron launch with real IPC, onboarding, org creation, approvals, and run orchestration

Evidence Collected

Validation commands executed in this session:

• pnpm typecheck
• pnpm lint
• pnpm test:unit
• pnpm test:integration
• pnpm test:e2e
• pnpm electron-vite build

Additional runtime scenarios executed against the built Electron app:

• full first-launch onboarding to desktop shell
• navigation sweep across desktop sections
• live hire request flow with autoApproveHires = true
• live hire request flow with autoApproveHires = false
• negative-path validation that legacy saveAgent creation and pending_approval -> idle status bypasses are rejected

Current Architecture Reality

What already exists and is materially real:

• main / preload / renderer separation is implemented
• renderer uses typed preload APIs instead of raw Node access
• contextIsolation: true, nodeIntegration: false, sandbox: true are used for the main desktop shell
• orchestration worker runs in an Electron utility process
• SQLite-backed local-first state model exists
• connectors for codex_local, claude_local, gemini_local, opencode_local, kimi_local exist
• approvals, runs, costs, activity, automation, meetings, knowledge, documents, sprints, social, messages, workspaces, and onboarding all exist in code and UI

What is still structurally weak:

• several modules are still too large to be considered stable long-term coordination boundaries
• cross-feature side effects still live in a few orchestration-heavy modules instead of a smaller explicit event-policy layer
• some release/security/product rules exist in PRD and code, but not all are enforced uniformly in every write path

Largest modules by line count at audit time:

• src/main/database.ts: 3348
• src/renderer/components/execution.tsx: 1726
• src/renderer/components/communication.tsx: 1726
• src/main/api-server.ts: 1697
• src/renderer/components/automation.tsx: 1693
• src/renderer/App.tsx: 1606
• src/main/prompt-builder.ts: 1541

PRD Matrix

1. Local Profile / Company

Status: implemented, with one policy caveat

Evidence:

• local profile bootstrap, backup/restore, company switching, settings persistence all exist
• onboarding successfully creates company, workspace, goal, initial run, and opens desktop shell

Remaining risk:

• company policy toggles are present, but some governance behavior is still distributed across UI, IPC, API, and automation rather than centralized in a single policy service

2. Connector Management

Status: implemented

Evidence:

• connector registry UI exists
• connector health service exists
• model listing and auth terminal support exist
• command/env binding handling exists

Remaining risk:

• connector execution policy is still sensitive to environment-based behavior and deserves a dedicated policy surface, not scattered guard clauses

3. Agent Registry / Org Structure

Status: implemented, previously inconsistent, partially hardened in this wave

Evidence:

• org chart, agent roster, hiring pipeline, manager/report relationships, and budget fields exist
• pending-approval lifecycle exists in data model and approval resolution logic

Critical finding fixed in this wave:

• renderer previously allowed direct agent creation from the Agents page, bypassing hire_agent approval and breaking synchronization between Hiring, Approvals, onboarding, and org history
• renderer also allowed direct status edits that could move a pending hire into an active state without an approval decision

Remediation added:

• dedicated requestHire IPC contract
• transactional createHireRequest(...) persistence path
• renderer Agent creation now submits hire requests instead of active agents
• IPC saveAgent now rejects new-agent creation and rejects direct pending-hire activation

Runtime proof:

• with autoApproveHires = false, a new hire lands in pending_approval
• direct saveAgent creation returns AGENT_CREATION_REQUIRES_HIRE_REQUEST
• direct status bypass returns AGENT_APPROVAL_REQUIRED
• formal approval transitions the same agent record to idle

4. Goals / Projects / Tasks

Status: implemented

Evidence:

• onboarding creates goal and project structure
• task creation, comments, assignment, review states, kanban/list views, and run linkage exist
• task status changes feed automation/orchestration paths

Remaining risk:

• feature is functionally present, but task + review + message + automation interactions are still distributed across large renderer and main modules

5. Run Orchestration / Session Continuity

Status: implemented, with scaling caveats

Evidence:

• run creation, queueing, worker dispatch, recovery, logs, cancellation, and run status events exist
• utility-process worker is used instead of running orchestration in the renderer
• integration tests cover autonomous chain and recovery cases

Remaining risk:

• orchestration and wake logic remain heavily centralized
• cross-feature triggers are correct at current scope, but scaling behavior and event fan-out still need a slimmer event-policy boundary

6. Approvals / Governance

Status: implemented, materially improved in this wave

Evidence:

• approvals UI, decision handling, related task linkage, and automation callbacks exist
• board-side approval decisions update state and trigger follow-up automations

Critical finding fixed in this wave:

• agent creation governance could be bypassed from the desktop UI and IPC write path

Remaining risk:

• other approval-governed domains, especially termination and production-deploy style flows, still deserve the same hard policy treatment across all entrypoints

7. Cost / Budget

Status: implemented

Evidence:

• budget fields, cost entries, cost dashboard, thresholds, and budget-related automation logic exist

Remaining risk:

• budgets are enforced operationally, but not all escalation policy is centralized; some cost behavior is still advisory rather than hard-stopping privileged actions

8. Activity / Audit / Logs

Status: implemented

Evidence:

• activity timeline exists
• many core mutations add activity entries
• run logs exist and are streamable into renderer console panels

Remaining risk:

• structured logging exists, but the audit trail is still assembled from multiple write sites instead of passing through a smaller domain-event backbone

9. Secrets / Config / Environment

Status: implemented, hardened in this wave

Evidence:

• Electron safeStorage is used where available
• encrypted fallback vault exists behind explicit env opt-in
• env binding resolution exists for connector runs

Security hardening added in this wave:

• NODE_OPTIONS was removed from the runtime environment allowlist so spawned agent runtimes do not inherit host-side Node injection flags by default

Remaining risk:

• preload API surface is still large, even if typed
• env policy should eventually be expressed as explicit runtime capability profiles per connector, not only a static allowlist

10. Workspace / Repo / Artifact Management

Status: implemented

Evidence:

• workspace registry, path selection, repo URL/ref fields, primary workspace logic, and lock metadata exist
• orchestration resolves workspace context into runtime env

Remaining risk:

• workspace locking and stale-lock cleanup exist, but deserve more explicit operator-facing conflict states in UI for complex multi-run contention

11. Notifications / State Awareness

Status: implemented

Evidence:

• desktop notifications exist
• tray/menu/window controls exist
• sidebar badges, inbox, and console surfacing exist

Remaining risk:

• notification strategy is present but not yet tuned as a full release-quality desktop attention model across macOS, Windows, and Linux

Electron / Security / Release Audit

Security Baseline

Status: mostly aligned

Confirmed:

• secure BrowserWindow defaults are in place
• renderer does not receive raw Node primitives
• preload uses typed IPC contract calls
• utility process is used for background orchestration work
• vault prefers OS-backed secret storage

New hardening applied:

• runtime env no longer forwards host NODE_OPTIONS
• pending-hire governance cannot be bypassed from renderer IPC

Still open:

• preload surface is broader than ideal for a production app of this size
• some domain rules are enforced in handlers rather than at a smaller dedicated policy layer

Packaging / Release

Status: partially complete

Confirmed:

• electron-builder.yml targets macOS, Windows, Linux
• build script cleans /build, stages a non-mutating build version, and outputs into /build/release
• e2e and build use the current Electron/Vite packaging path correctly

Still open:

• this audit validated runtime on the current local platform only
• cross-platform runtime differences and signing/notarization behavior still need explicit validation evidence per target platform
• updater flow currently checks availability but does not yet provide a fully operator-visible download/install lifecycle

Performance

Status: acceptable for current prototype depth, not yet release-optimized

Evidence:

• app launches and is usable in live runtime checks
• worker isolation prevents heavy agent runs from living in renderer

Remaining risk:

• renderer build currently produces an approximately 1.7 MB main JS chunk, which is too large for a polished long-term desktop shell
• mega-components still make fine-grained performance work harder than it should be

External Research Used

Primary references used for this audit:

• Electron security checklist: https://www.electronjs.org/docs/latest/tutorial/security
• Electron process model / utility process guidance: https://www.electronjs.org/docs/latest/tutorial/process-model
• Electron safe storage API: https://www.electronjs.org/docs/latest/api/safe-storage
• electron-builder auto-update guidance: https://www.electron.build/auto-update

These references were used to validate:

• secure BrowserWindow / preload expectations
• utility-process suitability for background work
• safe secret storage expectations
• updater/build configuration direction

Remediation Implemented In This Wave

Files changed in this wave:

• src/shared/contracts.ts
• src/preload/index.ts
• src/main/runtime-env.ts
• src/main/database.ts
• src/main/ipc-core-work-graph-handlers.ts
• src/renderer/components/organization.tsx
• src/renderer/App.tsx

Concrete changes:

• added typed requestHire contract and preload API
• added transactional createHireRequest(...) database path
• rerouted renderer new-agent flow into hiring / approvals pipeline
• blocked direct renderer IPC creation of active agents
• blocked direct renderer status promotion of pending hires
• tightened runtime env inheritance by removing NODE_OPTIONS

Remaining High-Value Follow-Ups

1. Split App.tsx, database.ts, api-server.ts, automation-service.ts, communication.tsx, and execution.tsx into smaller domain slices.
2. Pull wake / publish / automation side effects into an explicit domain-event policy layer instead of leaving them distributed in orchestration-heavy modules.
3. Shrink the renderer entry chunk with section-level lazy loading for heavyweight desktop panels.
4. Make updater lifecycle operator-visible beyond availability checks.
5. Validate runtime behavior on Windows and Linux rather than relying only on configured targets.