Use provider terminal evidence for completeness; an OpenCode successful EOF closes its step-based stream. Preserve immutable snapshots and propagate partial completeness through final results.
Co-Authored-By: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip manages agent work through adapters and heartbeat runs.
> - ACP adapters resolve a timeout for the selected execution target.
> - An untouched sandbox timeout uses a four-hour default.
> - Heartbeat finalization rebuilt the metadata from the stored zero.
> - This made a timed-out sandbox run report an effective timeout of
zero.
> - This change retains the adapter's resolved policy for accurate run
diagnostics.
## Linked Issues or Issue Description
**What happened?**
ACP sandbox runs with `timeoutSec: 0` use the four-hour default. Their
terminal metadata reports `effectiveTimeoutSec: 0` and `timeoutSource:
config` because heartbeat finalization only reads the stored agent
configuration.
**Expected behavior**
The result must report the policy the adapter used: `14400` and
`sandbox_default`. Explicit limits, fractional limits, explicit
unlimited overrides, and local defaults must keep their resolved values.
**Steps to reproduce**
Run an ACP adapter on a sandbox target with `timeoutSec: 0`. Compare the
start log's four-hour policy with the terminal result's effective
timeout. The new tests exercise the adapter result and the heartbeat
metadata merge without waiting four hours.
**Paperclip version or commit**
Reproduced from `6eaf218924f0a89faf1c02eb0d6877a6c5c8a2cb`.
**Deployment mode**
Self-hosted server with an ACP sandbox execution target.
Searched open timeout and metadata issues and PRs. Related #14804
exposes timeout configuration in forms; #14496 proposes a default
policy; #14833 addresses CLI session retention. This PR changes only ACP
result metadata.
## What Changed
- Retain the resolved timeout in the ACP result after settlement.
- Use validated adapter resolution when merging terminal timeout
metadata. Preserve config fallbacks for older adapters and the HTTP
millisecond policy.
- Test sandbox defaults, explicit and fractional limits, explicit
unlimited overrides, local defaults, malformed metadata, and unchanged
cancellation fields.
- Document the result fields and their meaning.
## Verification
- `pnpm -r typecheck` passed.
- `pnpm build` passed.
- Stop metadata tests: 23 passed.
- Reporter and diagnostic suites: 84 passed; two real-Sentry-SDK tests
skipped because the optional SDK is not installed.
- ACP engine suite: all 206 tests passed with a deterministic local
`gemini --version` shim. Ambient host CLI probes made the existing
Gemini session-resume fixture intermittent (one assertion failure in
each of two broad runs); an isolated 15-case rerun and the clean-base
206-test suite also passed. No assertion or timeout was changed.
- `pnpm test:run` is in progress. This PR does not claim a complete
local suite pass.
- Independent review found no blocking issues. The tests cover real
adapter emission and the real metadata merge separately.
## Risks
Low runtime risk: this changes result diagnostics. It does not change
timeout values, cancellation acknowledgement, cleanup, checkpoint
safety, retries, or provider operations. It does not fix the cause of a
quiet or long-running tool. Older stored results are not rewritten. The
new source values apply only when an adapter returns a valid resolution.
## Model Used
OpenAI GPT-6 with reasoning, repository inspection, code editing, and
test execution. The deployment-specific model ID 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
- [ ] 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
- [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>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for work.
> - New agents receive role instructions from onboarding, the hiring skill, or a team package.
> - These sources repeat harness procedures and impose generic work policies.
> - They can crowd out the task and the harness instructions.
> - This pull request reduces those sources to short role descriptions.
> - It preserves configuration, skills, authentication, reporting lines, and approval controls.
> - The benefit is less repeated instruction text with explicit coverage for the default hiring path.
## Linked Issues or Issue Description
Refs #3307. The CEO template can impose a fixed delegation route instead of letting the agent choose how to fulfill the request. This change removes that route. It does not implement autonomous goal selection.
Related work: #14920 preserves stock Codex base instructions. #14948 reduces the generic manual and shared runtime prompts. #14961 improves native completion-tool descriptions. This PR is separate from those changes.
## What Changed
- Select only the short CEO `AGENTS.md` for new default CEO bundles. Keep the three former companion files as compatibility assets.
- Reduce the first-agent chief-of-staff prompt and coder, QA, UX, and security role examples.
- Reduce seven bundled team role bodies. Preserve their role, reporting, and skill metadata. Regenerate the catalog.
- Make hiring examples optional. Replace the long generic role manual with short role drafting guidance. Preserve explicit requester instructions.
- Add configuration and import coverage for native and legacy managed bundles, custom instructions, first-agent rendering, and catalog contents.
- Add an explicit-only hiring eval that starts from the production CEO default and checks one coder hire, independently computed JSON output, saved instructions, and worker reuse.
- Include the full prompt comparison and a separate three-request drafting simulation. Neither is a live provider comparison.
Prompt differences: [before and after](doc/plans/2026-10-02-hiring-template-prompt-diff.md). The CEO default falls from 1,897 to 20 words. The coder example falls from 652 to 18 words. Word counts describe instruction size, not outcome quality or billing.
## Verification
- PASS: 99 focused server tests and eight shipped-catalog tests.
- PASS: catalog generation and validation for four shipped teams.
- PASS: hiring skill validation.
- PASS: `pnpm -r typecheck`.
- PASS: `pnpm build`.
- INCOMPLETE: the full local `pnpm test:run` was stopped before rebase. Its original log is retained. This is not a completed full-suite pass. The full current-head GitHub CI workflow passed: https://github.com/paperclipai/paperclip/actions/runs/37073372419.
- PASS: `pnpm test:e2e:runner:typecheck` and `pnpm test:e2e:runner:unit` (63 files / 843 tests).
- PASS: discovery for the two new hiring cells, 50 existing everyday cells, and the full 438-cell catalog.
- PASS after rebase: 99 server tests, 11 catalog tests, 62 selected E2E support tests, and the E2E typecheck.
- PASS: all current-head PR checks at `57dcee147ed0b2d2e3cc657cd9e50fb16bf9ec25`: 51 successful check runs, two intentional Storybook skips, and successful Snyk status. Fresh Greptile is 5/5 with zero unresolved threads.
- PENDING follow-up: matched live hiring runs on frozen integration refs. No live outcome-quality or non-regression result is claimed from the configuration checks or this merge.
The new suite has two local native cells: Codex and ACPX Claude. It expects five provider turns per cell. It compares source-derived bundles, so the historical long templates remain admissible. Missing successful source-read receipts make a pair uncomparable. They do not establish a behavior regression or equivalence.
## Risks
- New default roles have fewer prescribed procedures. Live checks must determine whether a removed instruction was needed for an outcome.
- Existing custom and saved bundles keep their contents. The retained companion assets avoid a source-file compatibility break.
- Specialized Summarizer, Reflection Coach, and Wiki Maintainer prompts remain unchanged. Their product contracts need separate review.
- The generic non-CEO fallback reduction is in #14948. This PR alone does not provide its eight-word fallback.
- Configuration tests and drafting simulations do not establish live outcome quality. QA, UX, security, and chief-of-staff hiring behavior remain outside the new two-cell comparison.
> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`.
## Model Used
OpenAI Codex, based on GPT-6, with reasoning, code editing, shell tools, and delegated verification. The runtime does not expose the exact deployment model ID or context-window size.
## 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>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - Storybook previews help contributors review the board UI.
> - The publishing workflow uses the default branch CODEOWNERS file to
authorize users.
> - Tonio and Scott need access to this workflow.
> - This pull request adds both accounts as release documentation
owners.
> - The existing workflow can then authorize both accounts without a
separate user list in code.
## Linked Issues or Issue Description
**What existing behavior does this improve?**
Access to the Storybook build and publishing workflow.
**Subsystem affected**
Repository ownership and GitHub Actions authorization.
**Current behavior**
The workflow reads individual accounts from every CODEOWNERS rule on the
default branch. Neither `tonio-alucema` nor `scotttong` is in that file.
Both accounts already have repository admin access, but the workflow
authorization check denies them.
**Proposed behavior**
Add both accounts to the `doc/RELEASING.md` ownership rule. After merge,
both can start and rerun Storybook publishing workflows. A configured
`storybook-deploy` environment reviewer must still approve deployment.
CODEOWNERS membership does not add an account to the environment
reviewer settings.
**Reason and benefit**
Contributors can publish UI previews through the same CODEOWNERS policy
as other maintainers. The authorization code has no account-specific
exceptions.
**Breaking changes**
None. The existing authorization and deployment approval checks remain
in place.
**Additional context**
Related changes: #13226 added the publishing workflow. #13231 added
stable branch bookmarks. A search found no open PR for these permission
changes.
## What Changed
- Add `@tonio-alucema` and `@scotttong` only to the release
documentation ownership rule.
- Test that accounts listed for release documentation can start and
rerun publishing workflows.
- Test that removing an account from CODEOWNERS removes its publishing
access.
- Explain how CODEOWNERS entries and environment reviewers affect
publishing access.
## Verification
- `node --test scripts/__tests__/storybook-deploy.test.mjs`: all 25
tests pass.
- `actionlint .github/workflows/storybook-deploy.yml
.github/workflows/storybook-visual.yml`: passes.
- `git diff --check`: passes.
- GitHub API checks confirm that both accounts have repository admin
access. The deployment environment requires an existing reviewer and
disables administrator bypass.
- Repository-wide typecheck, tests, and build were attempted. They
cannot complete in this worktree because workspace dependencies are not
installed. Typecheck cannot find Node type definitions. Tests and build
cannot load the workspace `tsx` package.
- After merge, run `Storybook Deploy` from `master`, select a source
branch, obtain environment approval, and check the published URLs in the
run summary.
## Risks
Both accounts gain permission to start and rerun Storybook publishing.
Deployment still needs approval from a configured environment reviewer.
No AWS permissions or live GitHub settings change in this PR.
## Model Used
OpenAI GPT-6 through Codex. The exact backend model ID and context
window are not exposed in this session. The agent used reasoning,
repository inspection, code editing, shell execution, and GitHub API
tools.
## 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
Co-authored-by: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - Sandbox agents exchange input and output through bridge control
commands.
> - A provider can stop responding to a command even when it receives a
timeout.
> - These small commands can inherit a four-hour agent lifetime and
block input or teardown.
> - The board also calls a silent run healthy for the first hour.
> - This pull request bounds bridge control waits and surfaces silence
sooner.
## Linked Issues or Issue Description
**What happened?**
A sandbox run can remain active when a bridge control command never
returns. The shared helper passes a timeout to the provider but does not
enforce it on the host. It also accepts the agent's hours-long timeout.
Output silence remains `ok` for an hour and becomes `critical` only
after four hours.
**Expected behavior**
Bound short bridge operations even if the provider never settles. Report
failed input delivery through the existing shutdown path. Warn after
five silent minutes and escalate after fifteen. Keep normal agent
command limits and require verified termination before releasing
execution ownership.
**Steps to reproduce**
1. Use a sandbox runner whose bridge read or input-upload promise never
settles.
2. Set its configured timeout to four hours.
3. Observe that the old queue client never returns or rejects.
4. Inspect a running task with 35 minutes of output silence. The old
summary still reports `ok`.
**Paperclip version or commit**
Base commit `d6d88b9de2`.
**Deployment mode**
Self-hosted server with sandbox execution.
**Agent adapter(s) involved**
Shared command-managed sandbox bridge, including Codex ACP sessions. The
informational silence thresholds apply to active runs across adapters.
Related: #14889 recovers stalled Daytona output streams; #14485 retries
explicit gateway failures during input delivery. This change bounds
short control operations whose provider promises never settle. It does
not add tool replay or automatic cancellation for output silence. #6297
proposes configurable per-agent silence thresholds; this patch only
changes the existing defaults.
## What Changed
- Enforce at most 30 seconds per bridge control shell command on the
host and provider, including callback startup and shutdown,
process-session launch, and payload setup. Preserve shorter configured
deadlines and launch environments.
- Keep the long-lived agent command outside this deadline. Use a fixed
timeout diagnostic without command payloads.
- Surface suspicious output silence after five minutes and critical
silence after fifteen minutes.
- Decouple the shared-workspace holder cutoff from warning thresholds
and preserve its existing one-hour value.
- Add regressions for hung reads, a late upload response, failed input
delivery, exact warning boundaries, and fresh output clearing warnings.
- Update the adapter guide and execution contract.
## Verification
- The three new queue-client regressions fail on the unchanged base and
pass with this patch.
- Final callback bridge and sandbox session suites: 214 passed. These
cover hung reads, writes, startup, shutdown, process-session launch,
payload setup, and the separate long-running agent limit.
- Stdin ordering and shutdown suite: 56 passed after the lifecycle
change.
- Daytona and watchdog coverage passed in the earlier focused runs.
Across the focused suites, 602 distinct tests pass.
- `pnpm -r typecheck` and `pnpm build`: passed. Server and adapter
typecheck/build also passed after their respective follow-up changes.
- `pnpm test:run`: attempted and stopped after known local failures.
Four chat/email cases used an external ancestor skill path, three
skill-cache cases failed on macOS, and one wakeup case timed out. The
wakeup case passes alone (1 passed, 27 skipped). This run spanned the
workspace-cutoff follow-up and also failed its new holder case; a fresh
final-head workspace suite passes all 19 tests. The interrupted run is
not a full local-suite pass or final-head verification.
- A filesystem queue-drain test failed once during the lifecycle rerun
and passed on the complete two-suite rerun. It uses the filesystem
client, outside the changed command-runner path.
- Complete CI on `ff2212c235`: 53 successful checks and two expected
skips, including the full test suite and canary packaging dry run. No
failed or pending checks.
- Greptile reviewed `ff2212c235` at 5/5. All review findings are
addressed, no threads remain unresolved, and the branch has no merge
conflicts with `master`.
- `git diff --check` and a scan of added text for secrets and private
identifiers passed.
## Risks
- A bridge control operation that needs more than 30 seconds now fails,
even if the caller selected a longer run lifetime. Agent commands retain
their own limits.
- Timing out a provider promise does not cancel the remote operation or
prove it stopped. Existing execution settlement still owns termination
verification. No uncertain tool action is replayed.
- Quiet healthy runs display warnings sooner. Existing snooze, continue,
and false-positive dismissal controls still apply. Silence alone does
not cancel a run, create review work, or change assignments.
- No schema or API shape change.
## Model Used
OpenAI GPT-6 through Codex, with tool use and code execution. The exact
serving model ID and context window 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 change-specific 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>
## Thinking Path
> - Paperclip helps people manage AI agents and their work.
> - Agent chat shows which agent receives each message.
> - The chat header used initials instead of the agent avatar.
> - The name and controls did not use the same center alignment.
> - This change uses the shared avatar and centers the header content.
> - Users can identify the agent and open its settings from the same
row.
## Linked Issues or Issue Description
**What happened?**
The agent chat header showed initials instead of the agent avatar. The
settings control did not align with the name and avatar.
**Expected behavior**
Show the agent avatar. Put the avatar, name, and settings control on the
same horizontal center line.
**Steps to reproduce**
1. Enable Agent Chat in Experimental settings.
2. Open a conversation with an agent that has an appearance set.
3. Check the avatar and settings control in the top bar.
Related navigation work: #14706.
## What Changed
- Use `AgentAvatar` in the conversation breadcrumb.
- Update the breadcrumb key when the agent appearance changes.
- Center breadcrumb labels that have an adjacent action. Keep task
identifier baseline alignment unchanged.
- Add regression checks for avatar props, appearance changes, and center
alignment.
## Verification
- PASS: affected Vitest suites, 129 tests.
- PASS: `pnpm check:token-gates`.
- PASS: `pnpm --filter @paperclipai/ui typecheck` on an isolated retry.
- PASS: `pnpm --filter @paperclipai/ui build`.
- PASS: browser checks at 1000 and 390 CSS pixels. Avatar, name, and
settings control all have center Y = 29.5 CSS pixels.
- Screenshots use the real header and avatar renderer with isolated
context fixtures. No screenshot or fixture is part of this diff.
- Full typecheck and build cannot complete because Cargo is not
installed.
- Full tests stopped with SIGKILL. The first UI typecheck also stopped
with exit 137. These runs do not prove full-suite success.
## Risks
- Low risk. The change only affects UI rendering. It changes no API or
database contract.
- Breadcrumbs with adjacent actions now use center alignment. Ordinary
task identifiers keep baseline alignment.
## Model Used
OpenAI Codex agent, with code editing, shell tools, and browser checks.
The runtime did not expose the exact model ID or context-window size.
## 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)
- [ ] 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
No behavior or command documentation needs an update for this rendering
fix. The execution environment requires the assigned branch name to stay
unchanged. Pending review gates are not marked complete.
Co-authored-by: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - Agents reach external services through the Apps catalog. Each
catalog entry is a reviewed `AppDefinition` that wires a provider's
hosted MCP server into Paperclip's shared vault, grants, policies,
gateway, and audit trail.
> - Neon is a widely used serverless Postgres provider with an official
hosted MCP server, but it is not in the catalog. Teams that run their
databases on Neon must use the generic "connect your own MCP server"
path, which has no branding, no guidance, and no project or read-only
controls.
> - The connector playbook requires a catalog entry for a provider like
this: the hosted server supports dynamic client registration and bearer
API keys, and the common definition fields can express every option
Paperclip can serialize.
> - This pull request adds the Neon definition, its official artwork,
the research and permission-review ledger rows, documentation, and
deterministic tests, without any provider-specific runtime code.
> - The benefit is a one-click, governed Neon connection with optional
project pinning and read-only mode, and a documented path to live
qualification.
## Linked Issues or Issue Description
**Problem or motivation**
Neon is a common Postgres host for the applications agents work on, but
Paperclip's Apps catalog has no Neon entry. Operators who want agents to
inspect schemas, run SQL, or manage branches must paste the MCP URL into
the generic remote-MCP flow, which gives no branding, no provider
guidance, no project boundary, and no read-only switch.
**Proposed solution**
Add a catalog-only Neon connection built from the connector playbook:
browser sign-in through Neon's dynamic client registration with the
reviewed `read` and `write` scopes, or a customer API key sent as an
Authorization bearer header. Both methods expose Neon's documented
`projectId` pin and `readonly` switch as optional Advanced fields. Every
discovered tool stays governed by the normal per-action policies.
**Alternatives considered**
A plugin was not needed because no custom UI, tables, workers, or
webhooks are involved. A separate read-only method was not added because
the playbook treats read-only switches as advanced fields rather than
methods. Neon's repeatable `category` query filter was left out because
tenant fields serialize lists as one comma-joined value, so it cannot be
sent correctly without new runtime code; per-action policies cover
catalog narrowing instead.
**Roadmap alignment**
This extends the existing self-serve remote-MCP connection catalog and
does not overlap planned core work.
## What Changed
- Added the `neon` provider to `scripts/ingest-app-definitions.mjs`
(category, API-key placement, methods, tenant fields, guidance,
warnings) and regenerated
`packages/shared/src/app-definitions/neon.json` plus the generated
registry.
- Added the Neon row to the self-serve MCP research ledger with
`dcr_or_api_key` auth and risk tier S4.
- Added permission reviews for `neon/mcp-oauth` (explicit scopes `read`,
`write`, taken from Neon's live authorization-server metadata) and
`neon/mcp-api-key` (provider key), with evidence links.
- Added Neon's official tile icon (`ui/public/brands/apps/neon.png`,
copied byte-for-byte from the icon linked by neon.com) and the brand
manifest entry.
- Added prosumer gallery copy for the Neon card.
- Added `doc/connections/NEON.md` (service involvement, endpoints,
administrator setup, capabilities and policy, manifest, brand
provenance, validation hook) and linked it from the connections README
and the permission audit.
- Tests: Neon definition shape, store visibility and artwork, URL
recognition, reviewed scopes with scope-widening rejection, URL
projection of the project pin and read-only flag, invalid project ID
rejection, the connect form's API-key gating, and the pinned catalog
counts.
## Verification
- `pnpm exec vitest run packages/shared/src/app-definitions.test.ts
packages/shared/src/app-definitions-url.test.ts` — 34 passed.
- `pnpm exec vitest run
server/src/__tests__/tool-access-service.test.ts` — 367 passed.
- `pnpm exec vitest run ui/src/pages/apps/AppsConnect.test.tsx
ui/src/pages/apps/Browse.test.tsx ui/src/lib/app-brand-assets.test.ts
ui/src/pages/apps/AppLogo.brand-assets.test.tsx` — all passed.
- `node scripts/check-app-brand-assets.mjs` and `node --test
scripts/app-brand-validation.test.mjs` — passed.
- `pnpm --filter @paperclipai/shared typecheck`, `pnpm --filter
@paperclipai/server typecheck`, `pnpm --filter @paperclipai/ui
typecheck`, `pnpm check:token-gates` — clean.
- Manual: in a local instance, open Apps → Browse, confirm the Neon card
and icon, open `/apps/connect?source=neon`, confirm both methods, the
Advanced project pin and read-only toggle, and that Connect enables
after an API key is entered. The operator completed a live connection
against a Neon account on this build.
- Live metadata probed on 2026-10-02: both `.well-known` documents at
`mcp.neon.tech` return the recorded endpoints and scopes; an
unauthenticated `initialize` returns 401 with `resource_metadata`.
## Risks
- Low risk to existing providers: the change is additive catalog data
plus tests. The generated registry only gains one import.
- Neon's hosted server grants broad project and database management. The
definition carries two warnings, recommends a development project, and
keeps every write under the normal action policies; the read-only switch
is enforced by Neon's server, not locally.
- The permission-review ledger records live proof for both methods as
not run; the full lifecycle checklist in `doc/connections/NEON.md` still
needs a documented pass before the entry is considered fully qualified.
> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.
## Model Used
- Claude Fable 5.1 (`claude-fable-5-1`) in Claude Code, with extended
thinking and tool use (shell, file editing, browser verification).
## 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>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - The heartbeat service records each agent turn and releases its
working files.
> - A turn can save its work and finish before instruction-copy cleanup
runs.
> - A cleanup exception can replace that completed result with an
adapter failure.
> - This also loses result accounting and can prevent environment lease
release.
> - This pull request records a cleanup warning and keeps the original
run outcome.
> - The existing recovery sweep retries cleanup from the durable
working-copy record.
## Linked Issues or Issue Description
Related cleanup and lock work: #14866 and #14869. Related, distinct
work: #14695 retains warm-process files; #12021 handles provider-process
SIGTERM after a terminal result.
**What happened?**
An agent saved its plan, posted a comment, and requested approval. The
provider completed its turn. Instruction-copy cleanup then timed out on
a directory lock. Its exception escaped a `finally` block and replaced
the provider result, so the completed turn showed `Run failed`.
**Expected behavior**
Keep the provider outcome, usage, cost, saved work, and pending
approval. Record a cleanup warning and let the existing recovery sweep
retry. A real provider failure must keep its original error. A failed
file save must keep its failed-save receipt.
**Steps to reproduce**
1. Complete a legacy adapter turn that saves work and requests approval.
2. Make instruction-copy release throw a directory-lock timeout.
3. Read the run result. Before this change, the cleanup error replaces
the provider outcome.
The new heartbeat tests reproduce the failure without a live provider or
external service.
**Paperclip version or commit**
The regression reproduces on `c83df091b1a5207375eaf23466bb5c62e4e1518e`.
This branch is rebased onto `cf8ad63c80`.
**Deployment mode**
Server-managed agent execution with persistent instruction working
copies.
## What Changed
- Catch instruction-copy release failures in both heartbeat teardown
paths. Stop repeating a failed cleanup attempt within the same run.
- Write a sanitized `instruction_cleanup` warning. A warning-write
failure also preserves the run result.
- Test successful, failed, and throwing providers; both teardown paths;
warning-write failure; accounting; approval state; and execution-control
release.
- Extend the held-lock test to prove a fresh recovery worker removes the
deferred copy and preserves its failed-save receipt.
- Document deferred cleanup and the run-log event.
## Verification
- Red proof: all five new heartbeat regression cases fail with the
original release calls.
- At head `20bea4f431c916d2f5db1970213aab85f5daa34c`, all 417 tests
passed across heartbeat process recovery, agent directory working
copies, and directory merge locks.
- Full local `pnpm -r typecheck`, `pnpm build`, and `git diff --check`
passed.
- [GitHub
CI](https://github.com/paperclipai/paperclip/actions/runs/37031119795)
passed at this head. All 53 reported checks passed; the two Storybook
checks were correctly skipped. This includes general and serialized
tests, browser shards, runner verification, build, typecheck, and the
canary dry run.
- Greptile reviewed this head with 5/5, no code comments, and no
unresolved review threads. The branch has no merge conflicts.
- The local `pnpm test:run` attempt was stopped after it reported eight
failures in unchanged suites. Four Slack/AgentMail cases selected an
unrelated ancestor skills directory and failed with `ENOENT`; the two
Slack cases passed with a temporary local skill-root link, which was
then removed. Three company-skill cases reproduced macOS `EACCES` errors
when renaming read-only cache directories. One gateway case passed when
rerun alone. No full local-suite pass is claimed; the complete CI test
jobs passed.
## Risks
- Cleanup errors now leave recovery work pending. The durable
working-copy record remains available for the existing retry sweep.
- This change preserves provider failures and failed-save receipts. It
does not claim that unsaved file edits were saved.
- Native instruction reservation errors retain their existing behavior
because they guard process ownership.
- No schema, lockfile, workflow, API, or UI changes.
## Model Used
OpenAI Codex, based on GPT-6, with reasoning, repository tools, and code
execution. The exact backend model ID and context-window size are not
exposed by 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>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - Each agent runs on an adapter, and the operator picks the agent's
model from the list the adapter advertises.
> - The `codex_local` adapter advertises a static, curated list. The
server returns that list as written, but the list itself is not in a
useful order: the default `gpt-5.6-sol` sits above the whole GPT-6
family (#14878).
> - This pull request orders the list the way the ChatGPT app orders
Codex models: newest model version first, then by decreasing capability
inside each version, with older models at the end.
> - It is stacked on #14917, which makes the model dropdown show a
hand-ordered list as the adapter advertises it. Without that change the
picker shows every list alphabetically.
> - The benefit is that a user who knows Codex finds the right model at
once, and older models sit at the end of the list.
## Linked Issues or Issue Description
Fixes#14878.
Related: #14917 (the Claude counterpart, #14877) carries the dropdown
change this PR relies on. This PR contains that commit until #14917
lands; after that it rebases to the Codex commit alone.
## What Changed
- `packages/adapters/codex-local/src/index.ts`: reorder the advertised
`models` list. GPT-6 (`astra`, `sol`, `luna`) first, then GPT-5.6
(`sol`, `terra`, `luna`), then `gpt-5.5`, `gpt-5.4`, `gpt-5.4-mini`,
`gpt-5`, `gpt-5-mini`, `gpt-5-nano`, then the o-series and
`codex-mini-latest` in their existing relative order.
`DEFAULT_CODEX_LOCAL_MODEL` is unchanged.
- `packages/adapters/codex-local/src/index.test.ts`: the metadata test
now asserts the full order of the GPT entries.
The ChatGPT app also lists GPT-6.1 Sol first. That model is not in
Paperclip's list today. Adding a model needs reasoning-effort and
fast-mode entries as well, so it is out of scope for an ordering fix.
## Verification
Run from the repository root:
```sh
pnpm exec vitest run packages/adapters/codex-local server/src/__tests__/adapter-models.test.ts
pnpm --filter @paperclipai/adapter-codex-local typecheck
```
Red on `master`, green here: the updated metadata test fails against the
unmodified list because `gpt-5.6-sol` comes first.
Manual check: open an agent that uses `codex_local` and open the model
dropdown. The list reads gpt-6-astra, gpt-6-sol, gpt-6-luna,
gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna, gpt-5.5, gpt-5.4,
gpt-5.4-mini, gpt-5, gpt-5-mini, gpt-5-nano, o3, o4-mini, o3-mini, Codex
Mini.
## Risks
- Low risk. The list content and the default model do not change; only
the order does. The server returns this list as-is for the built-in
Codex adapter and the server test compares against the exported list, so
no server change is needed.
- The first entry is no longer the default model. Nothing reads the
first entry as a default: `DEFAULT_CODEX_LOCAL_MODEL` is resolved
separately.
## Model Used
Anthropic Claude Fable 5.1 (`claude-fable-5-1`) through Claude Code,
extended thinking on, with tool use for reading the repository, running
vitest and tsc, and editing files. The account holder reviewed the
change and owns the commit.
## 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
---------
Co-authored-by: abderbj <115119179+abderbj@users.noreply.github.com>
