update

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

@@ -0,0 +1,203 @@
+# 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