mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-14 00:26:28 +01:00
DottaandClaude Opus 5.5
e8a3f1f6f2
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - After a restart, the control plane settles in-progress records (leases, claims, intents) only once it proves their owner process is gone > - The proof compares host and PID space, so a stamp from a replaced container or a rebooted machine stays unprovable forever, and its records never settle > - Self-hosted users on Docker, Kubernetes and Fly hit this on every redeploy; a Railway deployment with an exclusive volume is covered by `deployment_replaced` (#20026) > - This pull request adds a fenced controller epoch: each boot holds a database lease, and an expired boot is fenced so its records can be proven gone > - The benefit is that work stranded by a replaced container is recovered, without keeping an idle database awake ## Linked Issues or Issue Description Follow-up to #20026 and the Phase 2 durable-ownership data. Related: #19965 (owner stamps), #19883 (process space). No duplicate PR was found. **What happened?** A record stamped by a server process in another container reports `different_process_space`. A dead PID elsewhere is never proof, so the record stays `unprovable` and is never settled. Every redeploy of a self-hosted container leaves such records behind. **Expected behavior** A record owned by a server boot that was replaced (stopped cleanly, or lost its lease and was fenced) is proven gone and settled exactly once. A live boot's records stay with it. An idle server issues no recurring queries. **Steps to reproduce** 1. Run Paperclip in a container and start work, so an environment lease is stamped by that boot. 2. Replace the container. The new container has a new PID namespace. 3. The ownership reconciler reports `different_process_space` (unprovable) for the old lease, forever. **Paperclip version or commit** `master` before this PR. ## What Changed - New `controller_instances` table (migration 0449): boot id, epoch (bigserial), process space, pid, a lease on the database clock, `fenced_at` / `fenced_by_epoch`, `stopped_at`. - `controller-instance-lease.ts`, registered with the shared delivery-work coordinator (`controller-instance-lease` queue, runs during drain): - **Holds work → renews; idle → silent.** One upsert creates the row on first use and extends the lease only if the boot holds work: a stamp within the last 90 s, or a stamp whose ownership write may still be pending (held until the server's tracked work settles, capped at 10 minutes; a renewal that sees some other held record does not clear it, so a slow ownership write cannot be outlived), or an in-progress record held by its boot id. Those records are active environment leases, in-flight cleanup claims, sandbox creation intents, workspace finalize attempts, agent lifecycle steps, native finalizer and cleanup leases (`lease_holder` bound to the token), open native coordinator claims, and running legacy runs. Renewal runs every 30 s while the boot holds work. When it finds none, the lease lapses and the worker sleeps until the next stamp (`onControllerStamp`). - **No idle trailing statements.** When the server's last tracked work settles, the worker re-checks holdings at once, at most every 5 s (the rate limit also absorbs the worker's own run). So the last check happens with the work, not 30 s later. - **Quiesce, don't crash.** Each renewal has a 10 s bound. A failed or timed-out renewal applies an internal task drain, so no new work is dispatched. A recovered renewal resumes. The boot exits only after 60 s of failure (counted from the first failed attempt's start) while it still holds work, or at once when it finds itself fenced. - **Fence on demand, by a newer epoch.** For a stamp from another host or PID space, the prover reads that boot's row: - `stopped` or `fenced`: gone. - live lease: alive. - otherwise, the boot's last sign of life is the later of its lease expiry and the record's last write plus the TTL. Within 30 s of that, the owner stays `alive` (`controller_lease_grace`), so the settle watch keeps rechecking. After that, the prover fences the boot, but only with a lease row of its own (created on demand) and only an older epoch. - A graceful shutdown records `stopped_at`. - A reconciliation pass that settles nothing (`record: false` or `settle: false`) never fences and never creates the boot's row. - `owner-proof.ts`: these proofs apply only to server-held records. A stamp with a recorded process group stays unprovable, because agent processes can outlive their server. The reconciler passes each record's `updatedAt` to the proof. - `task-admission.ts`: - the quiesce drain never replaces an operator's drain, and has no idle owner, so HTTP stays open; - a `subscribeIdleWorkSettled` hook fires when the last tracked work finishes. - Off on a Railway deployment with an exclusive volume (it has its own replacement proof). `PAPERCLIP_CONTROLLER_INSTANCE_LEASE=on|off` overrides this. A stateless Railway service keeps the lease. A server without its own lease row never fences. - `maintenance-server-routes.test.ts`: in the post-run quiet window, the lease may check once more that the run's records were released. The test now excludes those statements, then asserts that the lease issues nothing in a further window. - Docs: `doc/execution-semantics.md`; the Phase 2 data doc records the two known gaps. ## Verification - `controller-instance-lease.test.ts` (15 cases): - a replaced container with all Railway variables empty is fenced and settled exactly once over two passes; - a live lease is alive; - an owner in grace, and work written after an idle lapse, stay alive and watched; - an older epoch never fences a newer one; - no fencing without its own lease row (off or unregistered), and an idle prover creates its row on demand; - a stopped boot is gone; - process-group stamps stay unprovable; - idle issues zero statements, and one upsert renews only while records are held; - **a 45 s outage:** quiesced, no exit, resumes; - **a renewal that never answers:** bounded, and the boot exits on time; - **a 70 s outage:** exits at 60–65 s, and the successor recovers the work exactly once; - fenced: stops; - the settle re-check; - graceful stop; off on a volume-exclusive Railway deployment, on for a stateless one, and the on/off override; - a running legacy run keeps the lease live. - Red, with the proof's instance check removed: the replaced-container, live, stopped and successor cases fail. - Wider: task-drain, idle-sleep, idle-local-work, owner-proof and ownership suites, plus the maintenance quiet-window tests. Server low-memory typecheck is clean. ## Risks - **Clock skew.** The proof compares a record's `updatedAt` (often the writer's clock) with the lease (database clock). The 30 s grace absorbs ordinary skew. - **A new exit path exists.** A server whose database is unreachable for more than 60 s while it holds work now exits, after first quiescing. This is the intended safety backstop. - **Bounded trailing activity.** A lease that holds work issues one statement every 30 s, plus at most one check when its work settles. An idle server issues none. - **Boots from before this release** have no row, and their records stay unprovable. The board "mark owner gone" action for those follows in a separate PR. ## Model Used - Anthropic Claude Opus 5.5 (`claude-opus-5-5`), via Claude Code with tool use. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
172 lines
8.1 KiB
TypeScript
172 lines
8.1 KiB
TypeScript
import { signalDatabaseWork, subscribeDatabaseWork } from "@paperclipai/db/work-signals";
|
|
|
|
/** Topics for existing durable queues; register intent before their writes. */
|
|
export const DELIVERY_QUEUES = {
|
|
mcpClientMirror: "mcp-client-mirror",
|
|
mcpIngressHandoffs: "mcp-ingress-handoffs",
|
|
mcpRevocationIndex: "mcp-revocation-index",
|
|
nativeRuntimeResponses: "native-runtime-responses",
|
|
nativeCancellation: "native-cancellation",
|
|
deploymentNotifications: "deployment-notifications",
|
|
liveInvalidations: "live-invalidations",
|
|
nativeProcessSessions: "native-process-sessions",
|
|
nativeQuestionCancellations: "native-question-cancellations",
|
|
activeExecutionRecovery: "active-execution-recovery",
|
|
ownershipInvariantReport: "ownership-invariant-report",
|
|
settledNativeProcesses: "settled-native-processes",
|
|
orphanActiveLeases: "orphan-active-leases",
|
|
legacyShutdownSettlement: "legacy-shutdown-settlement",
|
|
strandedAgentStatus: "stranded-agent-status",
|
|
activeRunSilence: "active-run-silence",
|
|
deferredExecutionReceipts: "deferred-execution-receipts",
|
|
taskRetryReceiptSettlement: "task-retry-receipt-settlement",
|
|
nativeStatusWakeIntents: "native-status-wake-intents",
|
|
orphanBlockers: "orphan-blockers",
|
|
activeRecoveryActions: "active-recovery-actions",
|
|
strandedAssignments: "stranded-assignments",
|
|
resolvedDependencies: "resolved-dependencies",
|
|
taskWatchdogs: "task-watchdogs",
|
|
staleIssueLocks: "stale-issue-locks",
|
|
scheduledRetryDispatch: "scheduled-retry-dispatch",
|
|
queuedRunDispatch: "queued-run-dispatch",
|
|
statusCardEvaluation: "status-card-evaluation",
|
|
runEvidenceMigration: "run-evidence-migration",
|
|
providerTraceRetention: "provider-trace-retention",
|
|
nativeRunnerEvidenceRetention: "native-runner-evidence-retention",
|
|
skillVersionRetention: "skill-version-retention",
|
|
externalObjectRefresh: "external-object-refresh",
|
|
databaseBackups: "database-backups",
|
|
importSpoolCleanup: "import-spool-cleanup",
|
|
externalConversationSettlement: "external-conversation-settlement",
|
|
nativeRecoveryNotices: "native-recovery-notices",
|
|
nativeEnvironmentSettlement: "native-environment-settlement",
|
|
nativeRunProjection: "native-run-projection",
|
|
nativeResultCommit: "native-result-commit",
|
|
nativeWorkspaceFinalization: "native-workspace-finalization",
|
|
retainedNativeSessionCleanup: "retained-native-session-cleanup",
|
|
nativeStatusReassessment: "native-status-reassessment",
|
|
nativeReviewResponse: "native-review-response",
|
|
nativeResponsePresentation: "native-response-presentation",
|
|
nativePendingEffects: "native-pending-effects",
|
|
unsafeWorkspaceExportRecovery: "unsafe-workspace-export-recovery",
|
|
automaticCompletionReviews: "automatic-completion-reviews",
|
|
obsoletePolicyReviews: "obsolete-policy-reviews",
|
|
cancelledWorkspacePreservation: "cancelled-workspace-preservation",
|
|
instructionCollection: "instruction-collection",
|
|
directoryCleanup: "directory-cleanup",
|
|
instructionCommit: "instruction-commit",
|
|
scheduledRetryCancellation: "scheduled-retry-cancellation",
|
|
executionFinalization: "execution-finalization",
|
|
workspaceRecovery: "workspace-recovery",
|
|
executionReplacement: "execution-replacement",
|
|
executionContinuation: "execution-continuation",
|
|
executionStatus: "execution-status",
|
|
executionDisposition: "execution-disposition",
|
|
environmentCleanup: "environment-cleanup",
|
|
approvalQueueSeeding: "approval-queue-seeding",
|
|
attentionRetention: "attention-retention",
|
|
approvalRetention: "approval-retention",
|
|
joinRequestRetention: "join-request-retention",
|
|
decisionTargets: "decision-targets",
|
|
decisionEffectRecovery: "decision-effect-recovery",
|
|
decisionExpiry: "decision-expiry",
|
|
decisionContinuation: "decision-continuation",
|
|
|
|
decisionArchiveDelivery: "decision-archive-delivery",
|
|
toolConnectionHealth: "tool-connection-health",
|
|
toolReviewProjection: "tool-review-projection",
|
|
toolReviewInterruption: "tool-review-interruption",
|
|
toolReviewRecovery: "tool-review-recovery",
|
|
toolReviewExpiry: "tool-review-expiry",
|
|
gatewayCredentialExpiry: "gateway-credential-expiry",
|
|
secretProposalExpiry: "secret-proposal-expiry",
|
|
customImageExpiry: "custom-image-expiry",
|
|
historicalCleanup: "historical-cleanup",
|
|
adapterLoginCleanup: "adapter-login-cleanup",
|
|
setupTokenCleanup: "setup-token-cleanup",
|
|
localLoginCleanup: "local-login-cleanup",
|
|
budgetEnforcement: "budget-enforcement",
|
|
accounting: "cost-accounting",
|
|
taskDrainExpiry: "task-drain-expiry",
|
|
controllerInstanceLease: "controller-instance-lease",
|
|
agentLifecycle: "agent-lifecycle",
|
|
chatBoardMessages: "chat-board-messages",
|
|
chatTaskStarts: "chat-task-starts",
|
|
chatReceiptReactions: "chat-receipt-reactions",
|
|
chatSessionStops: "chat-session-stops",
|
|
chatProviderEffects: "chat-provider-effects",
|
|
chatGitHubWebhookRecovery: "chat-github-webhook-recovery",
|
|
chatGitHubIngress: "chat-github-ingress",
|
|
chatGitHubPublications: "chat-github-publications",
|
|
chatGitHubReviewProjection: "chat-github-review-projection",
|
|
chatGitHubReviewChecks: "chat-github-review-checks",
|
|
chatGitHubTerminalResponses: "chat-github-terminal-responses",
|
|
chatGitHubAcknowledgements: "chat-github-acknowledgements",
|
|
chatFailedRunRetries: "chat-failed-run-retries",
|
|
chatTelegramMaintenance: "chat-telegram-maintenance",
|
|
chatReceivers: "chat-receivers",
|
|
voiceSessionRecovery: "voice-session-recovery",
|
|
voiceReports: "voice-call-reports",
|
|
voiceInboundRetention: "voice-inbound-retention",
|
|
voiceInboundCleanup: "voice-inbound-cleanup",
|
|
voiceReplies: "voice-reply-delivery",
|
|
chatTeamsConsentExpiry: "chat-teams-consent-expiry",
|
|
chatTeamsAttemptRecovery: "chat-teams-attempt-recovery",
|
|
chatCommandRegistration: "chat-command-registration",
|
|
chatTelegramSubscriptions: "chat-telegram-subscriptions",
|
|
chatSessionSyncs: "chat-session-syncs",
|
|
chatVerification: "chat-verification",
|
|
chatInbound: "chat-inbound",
|
|
chatPublications: "chat-publications",
|
|
chatNativeProgress: "chat-native-progress",
|
|
chatInboundWakeNotices: "chat-inbound-wake-notices",
|
|
chatInteractionContinuations: "chat-interaction-continuations",
|
|
chatTerminalConfirmations: "chat-terminal-confirmations",
|
|
chatFailedRetryNotices: "chat-failed-retry-notices",
|
|
chatRunMilestones: "chat-run-milestones",
|
|
chatReceipts: "chat-slack-receipts",
|
|
browser: "browser-use",
|
|
email: "email-channels",
|
|
museMaintenance: "muse-maintenance",
|
|
mergedPullRequestConfirmations: "merged-pull-request-confirmations",
|
|
mcpEvents: "mcp-events",
|
|
dotEvents: "dot-events",
|
|
grokDispatch: "grok-dispatch",
|
|
skillSourceSync: "skill-source-sync",
|
|
skillPackages: "skill-packages",
|
|
runtimeAssetRetention: "runtime-asset-retention",
|
|
fastResponse: "fast-responses",
|
|
feedback: "feedback-exports",
|
|
chatCompletion: "chat-completions",
|
|
connection: "connection-continuations",
|
|
connectionEvents: "connection-events",
|
|
connectionContinuity: "connection-continuity",
|
|
gitRestorePoints: "git-restore-points",
|
|
remoteWorkspaceSnapshots: "remote-workspace-snapshots",
|
|
nativeWorkspaceSyncRetention: "native-workspace-sync-retention",
|
|
question: "question-responses",
|
|
pluginSchedules: "plugin-schedules",
|
|
pluginLifecycle: "plugin-resource-lifecycle",
|
|
toolAction: "tool-action-receipts",
|
|
terminalWorkspaces: "terminal-workspaces",
|
|
routineExecutionStatus: "routine-execution-status",
|
|
routineSchedules: "routine-schedules",
|
|
issueMonitors: "issue-monitors",
|
|
agentTimers: "agent-timers",
|
|
caseHandoffs: "case-handoffs",
|
|
nativeHarnessBackupExpiration: "native-harness-backup-expiration",
|
|
nativeCheckpointExpiration: "native-checkpoint-expiration",
|
|
} as const;
|
|
export type DeliveryQueue = typeof DELIVERY_QUEUES[keyof typeof DELIVERY_QUEUES];
|
|
|
|
export async function notifyDeliveryWork(transaction: object, queue: DeliveryQueue, hint?: string): Promise<void> {
|
|
await signalDatabaseWork(transaction, queue, hint);
|
|
}
|
|
// Public delivery notification observers only see settled work. The coordinator
|
|
// uses the lower-level lifecycle subscription to also fence in-flight writes.
|
|
export function subscribeDeliveryWork(owner: object, queue: DeliveryQueue, wake: () => void): () => void {
|
|
return subscribeDatabaseWork(owner, queue, event => {
|
|
if (event === "settled") wake();
|
|
});
|
|
}
|