PaperClipAI/doc/plans/2026-10-30-github-connection-sleep.md

GitHub connection delivery and credential continuity

GitHub event delivery and credential continuity have separate obligations. The event worker uses the shared delivery coordinator. It performs a startup reconciliation and responds to committed configuration changes or authenticated Cloud hints. Credential work registers the actual next grant expiry, provider continuity check, or saved retry deadline. The aggregate heartbeat no longer calls either service, including when the heartbeat scheduler is disabled.

Event delivery contract

The Cloud webhook target queue remains durable truth. The tenant leases sealed events, validates their bindings, persists company-scoped receipts, applies the existing installation or pull-request behavior, and acknowledges completed work. A receipt row lock prevents overlapping receivers from applying an installation delta twice. Completed receipts remain passive history. The existing normalized merged-pull-request callback keeps its normalized key. Snapshot and confirmation reads/writes share the receipt transaction, including at pool size one; existing confirmation publications and direct wakes flush only after the outer commit. The pre-existing non-chat direct-wake crash gap remains: chat-bound continuations have their existing durable outbox, while an unbound direct wake is best effort.

A new tenant sends signed event-lease claim ewv=1. A compatible Cloud broker records delivery version 1 on the existing instance registration before returning eventWakeVersion=1. Only then does the tenant stop configured-empty polling. Cloud reconstructs unacknowledged targets after restart and retries the exact registered tenant when its current queue lease permits another delivery. A successful HTTP hint does not acknowledge the target. Missing, stopped or drained tenants therefore retain their work. The hint carries no provider payload or client-selected destination. The tenant checks a signed, stack-bound, single-use connector-events:wake control assertion on the exact POST endpoint.

Old Cloud and self-hosted registrations retain scoped reconciliation with the existing backoff. No connector configuration or no registration history settles to no recurring owner SQL or provider traffic. Disabled consumers can acknowledge queued events as ignored using their trusted local registration history; they cannot apply events to an inactive connection. Removing polling does not remove the host sleep safety blockers. Worker quiet is not proof of host suspension.

Durable credential debt

A grant stores a unique bindingSync revision and removed installation IDs before Cloud registration calls. Successful delivery clears only the locked current revision. Failure retains the saved intent and an exponential retry deadline, including provider Retry-After advice. A restart loads that deadline from the grant. A retry write compares the attempted credential/installation revision under the grant lock and cannot delay work committed by a newer revision. Restoration creates a new binding revision and removes active installations from the pending retirement list; binding commands also reject legacy conflicting retirements. Binding-only retries use the existing credential refresh lease and current secret resolver without repeating account/repository discovery. The initial OAuth callback uses the same saved debt and settlement path after connection activation.

Cloud binding calls acquire the company share lock before locking the grant and its connection, matching company deletion's parent-before-child order. A deletion that wins admission leaves no registration to apply; a handoff already admitted keeps its fence through completion. The grant, connection, company status and binding revision are re-read under those locks before calling Cloud. That admission fence prevents a concurrent disable, revoke, or archive from finishing before an already-admitted registration call. The API has no remote revision fence that could safely replace those locks with two short transactions. Each HTTP request and response body has a physical 15-second abort deadline. Four calls run in an awaited batch; a failed batch leaves the saved debt and releases the transaction after all four outcomes settle. Other companies can continue through separate pool connections. Slow successful multi-batch passes can delay writes to the same grant/connection and company status changes; the schema permits up to 100 active and 100 removed installation IDs. This is not an instance-wide lock or an idle hold.

Credential expiry remains enforced by the existing use path. Scheduled continuity checks run one hour before recorded access expiry or after the existing 30-day continuity window. A successful renewal that leaves the credential short-lived or unchanged retains a one-hour retry obligation instead of causing rapid calls. Changed credential metadata invalidates the old retry revision, so an earlier new expiry can preempt it. Disabled connections and archived companies do not perform credential work. Reactivation uses the normal committed configuration signal.

GitHub owners receive only relevant credential/configuration signals, not generic health or receiver notifications. Continuity reconstruction is company-scoped after the startup scan. Event draining retains instance-wide binding matching because Cloud leases an instance queue. Event hints coalesce with a five-second minimum pass spacing; an unrelated connection PATCH cannot trigger that drain. OAuth rotation merges only its owned OAuth fields, lease acquisition compares current metadata, and cleanup atomically removes only the matching lease path, preserving concurrent GitHub installation changes and binding-removal debt.

Supported local producers are the owning connection, OAuth, grant and company services in one tenant process. Their notifications belong to the outer database transaction. A savepoint does not commit a wake, and rollback cancels the write. Arbitrary SQL writers must use these notification contracts or restart the owner; process-local signals do not promise independent-writer or replica notification. External event delivery remains durable in Cloud across processes and restarts.

Paired rollout and rollback

1. Apply the companion Cloud registration-column migration and deploy its delivery worker with the control signer present. Keep new enrollment disabled initially.
2. Deploy this tenant version. It keeps fallback polling against older Cloud.
3. Enable Cloud enrollment. Version 1 activation is durable and idempotent. Turning the new-enrollment flag off must still service all existing version 1 records.
4. Before removing the Cloud delivery worker, restart affected tenants with PAPERCLIP_GITHUB_EVENT_POLLING=1. They arm fallback before sending signed ewv=0. Confirm the Cloud registration is cleared. A failed handoff leaves fallback active and Cloud retry intact. Alternatively, restore the old polling tenant image first while retaining the compatible Cloud worker.
5. Do not deploy a Cloud downgrade that removes responsibility for still-enrolled tenants. There is no capability expiry, renewal poll, or periodic tenant hint.

Evidence

Focused tests use isolated PostgreSQL plus controlled HTTP provider simulations. They cover first service write after quiet, saved results, terminal receipts, concurrent replay, signed callbacks, outer commit/rollback, drain/resume, startup wiring in both scheduler branches, credential backoff and changed deadlines. Cloud acceptance uses its actual broker/store/notifier boundaries and a controlled HTTP tenant. These tests do not establish a deployed fleet rollout or cost savings.

Enrollment after worker startup

The event owner resolves the current connector only when a delivery or setup pass is admitted. A service created before self-host enrollment can therefore use a later completed enrollment without being recreated. The full normalized identity and target configuration keys the connector cache, preserving negotiated event wake support while it is unchanged. An absent identity clears the cache; a replacement identity or changed key creates a new connector. Explicitly injected connectors keep their original lifetime.

Enrollment does not add a timer, database scan or network probe. An ordinary credential/configuration producer, authenticated control wake or active setup request admits the next pass. Unconfigured passes return before owner SQL or HTTP. A pass already in flight keeps its connector for that lease and its matching acknowledgment; identity discovery never changes authority halfway through a pass.

The real PostgreSQL/loopback regression starts the registered owner unenrolled, completes the canonical signed enrollment flow, then applies and acknowledges an encrypted installation event. Removing the identity parks the same owner, and a second enrollment proves the replacement signing/sealing identity is used. Each applied installation update has one bounded empty follow-up from its credential hint; the test joins that saved deadline once before checking 25-minute SQL/HTTP quiet windows. This is process-local enrollment recovery, not a deployed Cloud rollout or a new cancellation policy.