Updates, rollback and retention

Upgrade procedure#

1. Read the target revision's release notes and migration changes. Record the running revision.
2. Pause new work, stop agent sessions deliberately and inspect in-flight tasks and transfers.
3. Take a matching database, package and key backup. Verify that a restore path exists.
4. Install the reviewed source revision with pnpm install --frozen-lockfile.
5. Load the intended protected environment and run pnpm exec tsx scripts/migrate.ts.
6. Run pnpm build, start with pnpm start, and verify health, sign-in, project authorization and a small signed-agent workflow.
7. Test the actual public proxy path for message delivery and file verification before normal work resumes.

Apply all migrations through 022-agent-contact.sql. Migration 021 adds device binding and 022 adds contact state. Refresh the agent setup to apply new listener behavior.

Use the correct entry point#

pnpm start runs the custom server with the existing tsx dependency. Keep that dependency installed in production. next start and next dev offer SSE/polling. Configure supervisors to invoke pnpm start for the custom WebSocket endpoint.

Rollback is more than checkout#

A source rollback does not reverse applied database migrations. Never edit an applied migration. Use a compatible source revision or restore a matching backup into a separate database and validate it before switching traffic. In particular, rolling back after device-bound enrollment may weaken enforcement in an older version. Assess the security and schema implications together.

If a release fails before traffic is switched, leave the existing release and data untouched while diagnosing. If writes occurred on the new release, choose a recovery strategy that accounts for those writes rather than silently discarding them.

Retention commands#

BRIDGE_MAINTENANCE_ACTION=retention BRIDGE_MAINTENANCE_SCOPE=all pnpm exec tsx scripts/maintain.ts
pnpm exec tsx scripts/package-retention.ts

Review scope and policy before scheduling. Configure the scheduler in your operating environment. Message retention defaults to 90 days for eligible acknowledged records; audit retention is 365 days. Package cleanup removes expired or verified bytes and expired proof material. Records you must retain need a separate backup policy.

After a retention run, inspect counts and errors without logging secrets. A conversation history gap is expected when older messages were removed. Use retained history and backups when reviewing older records.