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.