Files
PaperClipAI/packages/paperclip-runner/scripts/copilot-profile-identity.mjs
T
4c56702e06 fix(server): schedule retained native-session cleanup (#17717)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - Native runs can retain a local session after an interrupted durable
suspend.
> - The orphan reaper repeatedly scans completed history for that
cleanup duty.
> - Idle scans keep the database active. Removing them requires complete
wake and ownership paths.
> - This pull request moves retained-session cleanup to committed
signals, local release events and saved deadlines.
> - Existing physical proof checks still decide whether cleanup is safe.
The shared scheduler does not grant execution authority.
> - The benefit is quiet retained history with recoverable cleanup and
owned shutdown.

## Linked Issues or Issue Description

Refs #17709 and #18135. This is slice 51 of the existing
recurring-server sleep stack. Both referenced dependencies have merged.
The target is `master`.

**What happened?**

The periodic orphan pass scans retained native sessions even after their
cleanup is complete or no automatic action is safe. Some eligible
sessions also depend on a local session, environment lease or original
maintenance callback releasing ownership. An earlier decision
notification can be consumed before the run's later terminal projection
commits.

**Expected behavior**

Reconstruct existing work at startup. Wake from committed writes and
actual owner release. Register the saved claim expiry or a probe for a
specific live process. Stop recurring discovery when no obligation
remains. Preserve original callback ownership and all existing cleanup
proof checks.

**Steps to reproduce**

1. Retain completed native runs with a durable-suspend close failure.
2. Let the periodic orphan pass run with no new work.
3. Observe repeated cleanup discovery. Separately, delay terminal
projection after its decision notification is consumed and observe the
missing cleanup wake.

**Paperclip version or commit**

Parent #17709 at reviewed head
`3b75f4bc1da1370304f069fc287af3d693575716`, landed as
`df6156c2e37f542a69f393dde31e357b82b7cac1`. Current integrated master:
`31b927e3013a8a4b3266854b740cf40a24753788`.

## What Changed

- Move scoped, paged discovery to the retained cleanup owner. Preserve
explicit manual recovery.
- Register the duty with the shared scheduler and remove it from the
periodic orphan pass. Keep concrete lease expiry and live-process probe
obligations.
- Use typed outcomes for settled/refused work and process, session,
environment, maintenance or lease waits. Keep physical proof and
quarantine decisions in the executor.
- Wake from committed finalization and terminal projection writes,
durable process/lease release, and local session or callback settlement.
Routine company-only finalization hints leave dormant cleanup quiet.
- Join duplicate cleanup and serialize inspections on one database lane.
Keep original Runner callbacks owned until settlement and shutdown.
- Preserve all master profile fixtures and the branch's historical
identities. Save the colliding sleep profile 79 separately. Generate
combined Copilot profile 80 from its source and retain master's other
provider profiles.
- Add the owner audit and regression coverage. No new table, migration
or independent maintenance timer is added.

## Verification

- Server acceptance: **2,342 distinct passing cases in 18 complete
files**. The 14-file unaffected group contributes 1,532 passes. Full
startup contributes 76, process recovery 410, environment service 51,
and external-chat response 273. The 29-case cleanup worker suite and
977-case executor suite run in full. No case in these files is skipped.
- Controlled scope regression: removing only the ordinary finalization
issue/run guard wakes dormant retained cleanup; the same assertion
passes after restoring it. A real local owner release still resumes the
durable candidate.
- Preserve the first broad failure: 1,607 passed and one startup
shutdown case failed because the coordinator mock lacked `stop()`. Add
only that mock method. All 76 unchanged startup cases then pass. Do not
treat the first broad command as green.
- Dedicated PostgreSQL 17 databases use the existing migration 413
schema. Embedded-only fixtures use the existing recovery helper with
fresh per-call databases. All temporary imports are restored byte-exact.
No assertion or timeout is relaxed.
- Current-master integration preserves both complete source histories.
The server, UI and database trees are identical to the server-tested
source. All master historical profile fixtures remain byte-exact. The
prepared sleep profile 79 remains independently inspectable.
- Current runtime validation at
`d08f764e3efe75e96929173afe7ee8739121ad9f` passes all 12 commands (22
installed ACPX/Grok contract cases and 26 native-provider Rust cases):
`pnpm install --frozen-lockfile --ignore-scripts`; Copilot/Grok identity
and generated profile checks; Runner and server typechecking; server
build; Copilot/Pi installation, profile compatibility and transport
settlement files (130 passed; one opt-in closed Pi snapshot case skipped
because its distribution root is not configured); installed ACPX
model/reconnect package contract and Grok identity tests; Rust
native-provider backend tests; module boundaries and migration order.
- Earlier 94-case installation/settlement acceptance applies to the
prepared profile 79 source. It is retained as history and does not
substitute for the current profile 80 validation above.
- Failure history and duty-specific evidence remain in
`doc/plans/2026-10-26-retained-native-session-cleanup-sleep-audit.md`.
Exact-current-head acceptance: all 60 checks are clean, including
protected CI and security; Greptile gives 5/5 for
`281d579de0d08e907194b8b790a0597b07d16b7b` with no actionable findings.
No Ponytail review is present under the authorized missing-review
policy.
- These checks do not claim a full local repository suite, live Copilot
or Daytona qualification, deployed host/database suspension, or measured
cost savings.

## Risks

- Missing a supported producer could strand cleanup. Tests exercise real
finalizer, heartbeat, environment and process writers. Process-local
signals cover in-process writers; no multi-replica or external SQL
notification transport is added.
- A timeout can leave an original callback active. Cleanup and shutdown
must keep waiting for it. The existing global maintenance drain is
conservative across roots.
- A retained live process still has a scoped 30-second absence probe. A
saved lease keeps its actual deadline. Operational errors retain retry
work. Immutable proof refusals and operator-required histories do not
gain automatic retry authority.
- Cleanup keeps all existing artifact, identity, claim, no-launch and
quarantine checks. Terminal status alone does not authorize physical
cleanup.
- This PR does not expand Cloud alarm coverage or relax host sleep
eligibility. It proves worker behavior, not deployed app/database
suspension.
- The Copilot source identity has changed; these checks do not claim new
live provider qualification.
- The parent has merged. This PR is merged only after its current-head
protected CI and review gates pass under the existing campaign
authorization.

## Model Used

OpenAI Codex, GPT-6 family, with code execution and repository tools.
The exact serving variant and context-window size are not exposed in
this session.

## 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
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>
Co-authored-by: Codex <noreply@openai.com>
2026-10-29 04:24:57 -05:00

114 lines
7.6 KiB
JavaScript

// Regenerate after changing any bound implementation; live qualification must
// restart whenever the resulting identity changes. Historical identities remain.
import { createHash } from "node:crypto";
import { execFileSync } from "node:child_process";
import { readFileSync, writeFileSync } from "node:fs";
import { fileURLToPath } from "node:url";
import { resolve, dirname } from "node:path";
const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
const fixture = resolve(root, "test/fixtures/copilot-profile-v80-identity.json");
const historical = JSON.parse(readFileSync(resolve(root, "test/fixtures/copilot-profile-v12-identity.json"), "utf8"));
const declaration = { ...historical.declaration, agentProfileVersion: 80 };
delete declaration.permissionIdentitySourceSha256;
const sources = {
displayEventSourceSha256: "src/drivers/acpx/copilot-events.ts",
displayProjectionSourceSha256: "src/drivers/acpx/copilot-extension-adapter.ts",
configuredEnvironmentSourceSha256: "src/configured-environment.ts",
configuredEnvironmentRustSourceSha256: "runner/crates/runner-core/src/configured_environment.rs",
profileActivitySourceSha256: "src/drivers/acpx/profile-activity.ts",
profileExtensionsSourceSha256: "src/drivers/acpx/profile-extensions.ts",
profileInstallationSourceSha256: "src/drivers/acpx/profile-installation.ts",
attachmentPolicySourceSha256: "runner/crates/runner-core/src/acpx_provider_capabilities.rs",
singleReadEvidenceSourceSha256: "src/drivers/acpx/single-read-evidence.ts",
nativeSessionRuntimeSourceSha256: "src/native-session-runtime.ts",
nativeRuntimeContextSourceSha256: "src/contracts/runtime-context.ts",
nativeRuntimePromptsSourceSha256: "src/contracts/runtime-context-prompts.ts",
nativeSessionContractSourceSha256: "src/contracts/native-session-backend.ts",
harnessSessionContractSourceSha256: "src/contracts/harness-driver.ts",
harnessBackendSourceSha256: "src/backends/harness-driver-backend.ts",
harnessSessionSourceSha256: "src/drivers/codex/codex-harness-session.ts",
transportContractSourceSha256: "src/drivers/codex/app-server-transport.ts",
nativeBackendSourceSha256: "src/backends/codex-native-backend.ts",
nativeBackendFactorySourceSha256: "src/backends/native-backend-factory.ts",
nativeInstructionsSourceSha256: "src/backends/runtime-context.ts",
providerLaunchSourceSha256: "src/live/runner-provider-launch.ts",
launchPreparationStoreSourceSha256: "src/live/runner-launch-preparation-store.ts",
runtimeRequestBridgeSourceSha256: "src/live/runnerd-codex-transport.ts",
runtimeRequestFacadeSourceSha256: "src/drivers/codex/codex-session-notifications.ts",
runtimeRequestNotificationSourceSha256: "src/drivers/codex/codex-thread-normalization.ts",
guardedInstallationSourceSha256: "src/drivers/acpx/installation-integrity.ts",
nativeExecutionSourceSha256: "src/contracts/native-execution.ts",
profileCompatibilitySourceSha256: "src/drivers/acpx/profile-compatibility.ts",
installationSourceSha256: "src/drivers/acpx/copilot-installation.ts",
assetOwnershipSourceSha256: "src/drivers/acpx/provider-assets-root.ts",
assetInstallerSourceSha256: "scripts/install-copilot-assets.mjs",
credentialBindingSourceSha256: "src/drivers/acpx/environment.ts",
admissionDiagnosticsSourceSha256: "src/drivers/acpx/admission-diagnostics.ts",
grokAdmissionSourceSha256: "src/drivers/acpx/grok-effort.ts",
sidecarErrorSourceSha256: "src/cli/acpx-sidecar-input.ts",
profileSourceSha256: "src/drivers/acpx/copilot-profile.ts",
metadataProbeSourceSha256: "src/drivers/copilot-metadata-probe.ts",
acpxPatchSha256: "../../patches/acpx@0.13.1.patch",
policySha256: "src/drivers/acpx/copilot-policy.ts",
distributionSourceSha256: "scripts/materialize-copilot-binary.mjs",
innerDistributionSourceSha256: "scripts/copilot-inner-distribution.mjs",
permissionContextSourceSha256: "src/drivers/acpx/copilot-permission-context.ts",
permissionAdapterSourceSha256: "src/drivers/acpx/acp-permission-adapter.ts",
permissionToolIdentitySourceSha256: "src/drivers/acpx/cursor-plan-tool-identity.ts",
permissionLocationsSourceSha256: "src/drivers/acpx/safe-locations.ts",
permissionRedactionSourceSha256: "src/semantic-tools/redaction.ts",
permissionClassifierSourceSha256: "src/drivers/acpx/generated-sidecar-contract.ts",
semanticReceiptSourceSha256: "src/drivers/semantic-tool-receipt.ts",
semanticBridgeSourceSha256: "src/drivers/runner-tool-bridge.ts",
toolEvidenceSourceSha256: "src/drivers/acpx/copilot-tool-evidence.ts",
semanticSidecarSourceSha256: "src/cli/acpx-runtime-sidecar.ts",
semanticContinuationSourceSha256: "src/drivers/completion-continuation.ts",
semanticDirectDriverSourceSha256: "src/drivers/acpx/codex-acpx-driver.ts",
semanticValidationSourceSha256: "src/protocol/replay-contract.ts",
semanticNormalizationSourceSha256: "src/protocol/result-normalization.ts",
semanticCompletionContractSourceSha256: "src/contracts/completion-result.ts",
semanticValidatorsSourceSha256: "src/protocol/generated/standalone-validators.ts",
semanticSchemaBundleSourceSha256: "src/protocol/generated/schema-bundle.ts",
semanticSidecarProtocolSourceSha256: "src/drivers/acpx/sidecar-protocol.ts",
preparedHarnessHomeSourceSha256: "src/drivers/preconfigured-home.ts",
runtimeHostSourceSha256: "src/drivers/acpx/runtime-host.ts",
runtimeAdapterSourceSha256: "src/drivers/acpx/codex-runtime-adapter.ts",
runtimeSandboxSourceSha256: "src/drivers/acpx/runtime-sandbox.ts",
cancellationSourceSha256: "src/drivers/acpx/turn-cancellation.ts",
agentFilesSourceSha256: "src/drivers/acpx/agent-files-binding.ts",
nativeDistributionSourceSha256: "src/drivers/acpx/native-distribution-integrity.ts",
};
for (const [field, path] of Object.entries(sources)) {
declaration[field] = createHash("sha256").update(readFileSync(resolve(root, path))).digest("hex");
}
const sorted = Object.fromEntries(Object.entries(declaration).sort(([a], [b]) => a.localeCompare(b)));
const commandDigest = `sha256:${createHash("sha256").update(JSON.stringify(sorted)).digest("hex")}`;
const identity = `${JSON.stringify({ commandDigest, declaration }, null, 2)}\n`;
// The shared manifest now generates both TypeScript and Rust admission. Update
// only Copilot; other providers retain their upstream release attestations.
const manifestPath = resolve(root, "acpx-profiles.json");
const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
if (process.argv.includes("--check")) {
if (manifest.profiles.copilot.commandDigest !== commandDigest
|| manifest.profiles.copilot.agentProfileVersion !== declaration.agentProfileVersion) {
throw new Error("Copilot identity is stale in acpx-profiles.json");
}
} else {
manifest.profiles.copilot.commandDigest = commandDigest;
manifest.profiles.copilot.agentProfileVersion = declaration.agentProfileVersion;
writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
}
// The builder reads the active manifest; no duplicate digest literal is allowed.
const distributionSource = readFileSync(resolve(root, "scripts/build-copilot-distribution.mjs"), "utf8");
if (!distributionSource.includes("profiles.profiles.copilot.commandDigest")) {
throw new Error("Copilot distribution builder must use the active manifest identity");
}
// The shared generator validates this exact attestation before emitting admission.
if (process.argv.includes("--check")) {
if (readFileSync(fixture, "utf8") !== identity) throw new Error("Copilot source identity is stale");
} else writeFileSync(fixture, identity);
execFileSync(process.execPath, [resolve(root, "scripts/generate-acpx-profiles.mjs"),
...(process.argv.includes("--check") ? ["--check"] : [])], { stdio: "inherit" });
console.log(commandDigest);