AgentCompany/docs/12-release-readiness.md

Phase 11: ProjectManager Release Readiness

Milestone Status

• architecture freeze: complete
• interactive prototype: complete
• internal alpha desktop shell: complete
• macOS local packaging validation: complete
• signed beta build: pending signing/notarization credentials and platform-host verification
• release candidate: pending Windows and Linux package validation
• production release readiness: pending platform signing completion and final release-channel credentials

What Is Ready

• dedicated Electron-native desktop workspace under AgentCompany
• explicit main / preload / renderer / shared separation
• local-first profile, secret storage, orchestration worker, IPC contracts, and desktop shell
• onboarding to first usable shell flow
• packaging configuration for macOS, Windows, and Linux
• warning-free local lint baseline across main/preload/renderer
• validation gate rerun on 2026-03-13 passed (lint, typecheck, test:run, build:dir)
• TODO: PR CI quality gate workflow (.github/workflows/agent-company-pr-verify.yml) has not been created yet
• TODO: Electron production fuse hardening has not been configured yet (see doc 11)
• packaging script now defaults to --publish never unless explicitly overridden (AGENTCOMPANY_ELECTRON_PUBLISH or explicit --publish)

Release Ownership Boundaries

Area	Primary owner	Backup owner	Scope boundary	Exit evidence
Release gate decision	CEO / ProjectManager	Product lead	Approves go/no-go only after all gates are green; does not bypass security/platform sign-off	Signed release checklist + release tag decision
Signing credentials	Security Auditor	Platform Release Engineer	Manages cert issuance/rotation and secret distribution; build operators never commit secrets	Secret inventory record + cert expiry check
macOS signing + notarization	macOS Release Engineer	Security Auditor	Runs signed build on macOS host and validates notarization ticket	spctl, codesign, stapler evidence
Windows signing + installer trust	Windows Release Engineer	Security Auditor	Runs NSIS build on Windows host and validates Authenticode chain	Get-AuthenticodeSignature evidence
Linux package validation	Linux Release Engineer	QA lead	Builds and smoke-tests AppImage on Linux host; verifies runtime dependencies	AppImage launch and smoke checklist
Updater endpoint trust	Security Auditor	SRE / Infra	Owns TLS/domain trust policy and update channel integrity checks	latest*.yml metadata + artifact hash verification
Cross-platform functional smoke	QA lead	Platform engineers	Verifies startup/onboarding/task-run/approval flows on each target OS	Smoke run logs + screenshots

Release Checklist (Production Candidate)

• pnpm install --frozen-lockfile completed on release host
• pnpm lint passed
• pnpm typecheck passed
• pnpm test:run passed
• pnpm build:dir passed
• signing environment variables are set from secret manager (not shell history files)
• AGENTCOMPANY_UPDATE_URL points to production or staging trusted domain (not example.invalid)
• updater checks are enabled for release validation (AGENTCOMPANY_DISABLE_UPDATES=false)
• macOS signed build + notarization validation completed on macOS host
• Windows signed installer validation completed on Windows host
• Linux AppImage validation completed on Linux host
• update metadata (latest*.yml) and published artifacts hash-match
• secrets regression check completed (existing local secrets remain readable after upgrade)
• local data migration test completed (old profile boots and migrates without data loss)
• final go/no-go approved by CEO / ProjectManager

Runbook

1. Preflight (all platforms)

pnpm install --frozen-lockfile
pnpm lint
pnpm typecheck
pnpm test:run
pnpm build:dir

Expected: all commands pass; no skipped failures are allowed unless explicitly waived in release notes.

2. Signing Material Readiness

Prepare these values in CI secret manager or local secure vault:

• AGENTCOMPANY_UPDATE_URL
• CSC_LINK
• CSC_KEY_PASSWORD
• WIN_CSC_LINK
• WIN_CSC_KEY_PASSWORD
• macOS notarization credentials (APPLE_ID, APPLE_APP_SPECIFIC_PASSWORD, APPLE_TEAM_ID) if using Apple ID flow

Sanity check before release build:

env | rg "^(AGENTCOMPANY_UPDATE_URL|CSC_LINK|WIN_CSC_LINK|APPLE_ID|APPLE_TEAM_ID)="

3. macOS Signed Build + Notarization (native macOS host)

1. Enable release-mode updater behavior and set trusted update URL.
2. Build signed artifacts.
3. Validate signature + notarization ticket.

export AGENTCOMPANY_DISABLE_UPDATES=false
export AGENTCOMPANY_UPDATE_URL="https://updates.<your-domain>/agentcompany/stable"
export CSC_LINK="file://$HOME/.signing/agentcompany-mac.p12"
export CSC_KEY_PASSWORD="<from-secret-manager>"
export CSC_IDENTITY_AUTO_DISCOVERY=true
export APPLE_ID="<apple-notarization-account>"
export APPLE_APP_SPECIFIC_PASSWORD="<app-specific-password>"
export APPLE_TEAM_ID="<team-id>"

pnpm build -- --mac dmg zip --publish never

spctl -a -vv "build/release/mac/AgentCompany.app"
codesign -dv --verbose=4 "build/release/mac/AgentCompany.app" 2>&1 | rg "Authority=|TeamIdentifier="
xcrun stapler validate "build/release"/*.dmg

Notes:

• For public macOS distribution, switch mac.hardenedRuntime to true with proper entitlements before final GA build.
• Keep ad-hoc signing only for local development and internal unsigned testing.

4. Windows Signed Installer Validation (native Windows host)

$env:AGENTCOMPANY_DISABLE_UPDATES = "false"
$env:AGENTCOMPANY_UPDATE_URL = "https://updates.<your-domain>/agentcompany/stable"
$env:WIN_CSC_LINK = "C:\signing\agentcompany-win.pfx"
$env:WIN_CSC_KEY_PASSWORD = "<from-secret-manager>"

pnpm build -- --win nsis --x64 --publish never

Get-ChildItem .\build\release\*.exe | Get-AuthenticodeSignature |
  Format-Table Path, Status, @{Name='Signer';Expression={$_.SignerCertificate.Subject}}

Expected:

• Status is Valid
• signer subject matches the intended publisher identity

5. Linux AppImage Validation (native Linux host)

export AGENTCOMPANY_DISABLE_UPDATES=false
export AGENTCOMPANY_UPDATE_URL="https://updates.<your-domain>/agentcompany/stable"

pnpm build -- --linux AppImage --x64 --publish never

chmod +x build/release/*.AppImage
./build/release/*.AppImage --appimage-version

Then run manual smoke validation on Linux:

• app launches and reaches main shell
• company/workspace/agent CRUD works
• task run + approval flow works
• settings toggle for updater works

6. Updater Endpoint Trust Verification

1. Validate update metadata endpoint and schema.
2. Verify published artifact hash against metadata.
3. Validate app update check in runtime.

curl -fsSL "$AGENTCOMPANY_UPDATE_URL/latest.yml" -o /tmp/latest.yml
rg "^(version|path|sha512):" /tmp/latest.yml

Hash verification (replace placeholders with actual artifact path/hash from metadata):

node -e "const fs=require('fs');const crypto=require('crypto');const [file,expected]=process.argv.slice(1);const got=crypto.createHash('sha512').update(fs.readFileSync(file)).digest('base64');if(got!==expected){console.error('sha512 mismatch');process.exit(1)}console.log('sha512 ok');" \
  build/release/<artifact-file> \
  "<sha512-from-latest-yml>"

Runtime verification:

• launch packaged app with AGENTCOMPANY_DISABLE_UPDATES=false
• trigger Check for updates from Settings
• confirm request goes only to trusted AGENTCOMPANY_UPDATE_URL domain
• confirm unsigned/untrusted update payloads are rejected by platform signing checks

7. Windows/Linux Native-Host QA Gate

Required evidence per platform:

• startup success + no crash in first 5 minutes
• create company + create workspace + create task + assign agent + run once
• approve one pending approval item
• inspect logs for uncaught errors
• close/reopen app and confirm local data persistence

8. Release Close-Out

• publish artifacts and corresponding latest*.yml only after all platform owners sign off
• attach evidence bundle (command output, screenshots, hash checks, signatures)
• mark release decision in changelog/release note with approver and timestamp

Outstanding Risks Before Public GA

• current config keeps mac.hardenedRuntime: false; must be enabled with release entitlements for notarized public mac builds
• no trusted production updater endpoint is configured by default (example.invalid fallback)
• Windows and Linux validation still requires native host execution each release cycle