## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Contributors and agents typecheck this repository, often on machines with limited memory > - paperclipai/paperclip#18737 made `pnpm -r typecheck` fit in 4 GiB because the server now checks in layers > - The test projects outside `pnpm -r` still import server source through relative paths, so each one checks most of the server as one program > - These projects peaked between 6.9 GiB and 14.9 GiB, so they fail on a 4 GiB machine > - This pull request makes these projects read the server layers as declarations, and adds a CI step that keeps them that way > - The benefit is that every TypeScript project in the repository can now be checked in 4 GiB, and a later change cannot silently undo this ## Linked Issues or Issue Description Refs paperclipai/paperclip#18737, which is merged. This pull request builds on the server layers that it added. No issue exists for this gap. **What happened?** `tsc -p tests/runner-e2e/tsconfig.json` peaked at 14.9 GiB at default settings. `tests/speko-native` peaked at 12.2 GiB, `server/src/__tests__/helpers/maintenance` at 9.6 GiB, and `tests/lifecycle-baseline` at 6.9 GiB. On one thread, `tests/runner-e2e` still peaked at 7.7 GiB. **Expected behavior** Each project passes with 4 GiB of memory. **Steps to reproduce** Run `tsc -p tests/runner-e2e/tsconfig.json` in a Linux container with `--memory=4g --memory-swap=4g`. The kernel stops the process. ## What Changed - Added `tsconfig.layers.json` to the four projects. Each file extends the project's `tsconfig.json` and references the generated server declarations. - Added `scripts/typecheck-test-projects.mjs`. It builds the server declarations and then checks the named projects, or all four. It takes `--low-memory`. - Changed `test:e2e:runner:typecheck` and `test:lifecycle-baseline:typecheck` to call that script. `docker-runner-check.yml` calls the first script by name, so that workflow needs no edit. - Added `--declarations-only` to `server/scripts/typecheck-layers.mjs`. The script now also generates `tsconfig.declarations.json`, so hand-written configs do not name individual layers. - Exported `runPnpm` from `scripts/typecheck-low-memory.mjs`, so the new script can use it. - Added a step to the `Typecheck + Release Registry` job. It runs straight after the server typecheck and reuses its declarations through `--reuse-declarations`. - The script now fails if a project loads server source, even when the types pass. Test support files, declaration files and JSON files do not count. This check does not enforce a memory limit. - Added a unit test that fails if a new project under `tests/` is neither in `PROJECTS` nor named as a single program. `tests/runner-acceptance` is the one named project. - Added `server/src/types/express.d.ts` to `tests/lifecycle-baseline/tsconfig.json`. That plain config failed alone with 11 TS2339 errors, and it now passes. - Exported `isTestFile` from `server/scripts/typecheck-layers.mjs`, so the source check uses the same rule as the layers. - Turned off `declaration` in the layered configs. These projects emit nothing, and declaration checks gave a false TS2883 error when `tests/runner-e2e` read the server as declarations. - Added tests, one of which runs the real compiler. Updated `doc/DEVELOPING.md` and `tests/lifecycle-baseline/README.md`. The references are not in each project's `tsconfig.json` because Vitest reads that file. A test showed that Vitest fails when a referenced config does not exist yet. The `tsconfig.json` files do not change, so editors and Vitest see the same configs as before. No new `package.json` scripts were added, as `.greptile/rules.md` requires. ## Verification I tested commit `9763880fab`, which is based on `1c9ca5829f`. I copied the commit into a named Docker volume and ran a fresh install. Each row ran in its own Linux arm64 container with `--memory=4g --memory-swap=4g` and 8 CPUs. The first row started with no build output. All rows used `--low-memory`. CI does not set a memory limit. I used the limit only for this measurement. | Project | Errors | Peak (cgroup) | Max process RSS | OOM kills | Time | | --- | --- | --- | --- | --- | --- | | `tests/runner-e2e` | 0 | 3.34 GiB | 3.06 GiB | 0 | 57 s | | `tests/speko-native` | 0 | 3.60 GiB | 3.27 GiB | 0 | 51 s | | `tests/lifecycle-baseline` | 0 | 3.43 GiB | 3.15 GiB | 0 | 50 s | | `server/src/__tests__/helpers/maintenance` | 0 | 3.39 GiB | 3.13 GiB | 0 | 52 s | `PAPERCLIP_TYPECHECK_LOW_MEMORY=1 pnpm test:e2e:runner:typecheck` and `PAPERCLIP_TYPECHECK_LOW_MEMORY=1 pnpm test:lifecycle-baseline:typecheck` also passed in the same limit, with peaks of 3.55 GiB and 3.52 GiB. I also ran the CI sequence in one container with the same limit: `pnpm --filter @paperclipai/server typecheck`, then `node scripts/typecheck-test-projects.mjs --low-memory --reuse-declarations`. Both passed, with a peak of 3.46 GiB. The new step took 16 s. The server layer build sets the peak in each row. Against the declarations, the projects peaked between 0.9 GiB and 2.2 GiB at default settings on macOS. Server source files that each project loads, without test support, declaration or JSON files: | Project | Plain `tsconfig.json` | `tsconfig.layers.json` | | --- | --- | --- | | `tests/runner-e2e` | 1,345 | 0 | | `tests/speko-native` | 1,647 | 0 | | `tests/lifecycle-baseline` | 1,343 | 0 | | `server/src/__tests__/helpers/maintenance` | 1,716 | 0 | I counted these on `3f0f31b2f9`. The source check in the script confirmed 0 for all four projects on this commit. **Limits of this proof:** - Without `--low-memory`, the 4 GiB run does not pass. The kernel stopped the layer build for `tests/runner-e2e` on `3f0f31b2f9`, and the script exited with status 1. I did not repeat this run on the final commit. The script does not turn on low-memory mode by itself. - The Linux runs used arm64, not x64. - The new CI step has not run in CI. `pr-trusted.yml` runs from `@master`, so the step first runs after this pull request merges. Check its first run. **Other checks on this commit:** - `server/scripts/typecheck-layers.test.mjs`: 38 tests pass. One test uses the real compiler to show that the source check tells a layered config from a config with no references. - With the references removed from `tests/speko-native/tsconfig.layers.json`, the script exits with status 1 and reports 1,644 server source files. - With the declarations removed, `--reuse-declarations` exits with status 1 and reports TS6053. - A type error in a test project makes the script exit with status 1. - `tests/lifecycle-baseline/tsconfig.json` passes with 0 errors. - `tests/lifecycle-baseline` Vitest suite: 533 tests pass. - Workflow tests that read `pr-trusted.yml` and CI routing: 114 tests pass. **Earlier checks:** - `server/src/__tests__/server-package-build-script.test.ts` passed 10 tests on `3f0f31b2f9`. This test failed in `ci / General tests (server (9/12))` on an older head. It tested a build script split that the final #18737 removed. - A changed signature in `server/src/services/run-liveness.ts` failed `tests/lifecycle-baseline/authority.test.ts` through the rebuilt declarations, before the rebases. When I restored the signature, the check passed. **Not run locally:** - `pnpm test:run` and `pnpm build`. CI covers these. **Failures that this pull request does not cause:** `pnpm test:e2e:runner:unit` has 13 failures on this commit, in `cursor-cloud-replay-fault`, `first-task`, `operating-receipts`, `pi-controls-evidence` and `workflow-security`. The same 13 tests fail on `master` at `6ef37398c8`. A comparison of the test names shows no differences. PR CI does not run this suite. ## Risks - Low risk to runtime behavior. No shipped code changes. - **Slower check:** `pnpm test:e2e:runner:typecheck` now builds the server layers on each run. Before the rebase, it took 30 s on macOS at default settings, about the same as the old single program for that project. On this commit it took 57 s in low-memory mode in the 4 GiB container. The new CI step reuses the declarations, so it took 16 s. - **Narrower check:** Server source is now checked only by the server's own layers, not again under each project's compiler options. The projects also skip declaration-portability checks. These projects emit nothing, so those checks had no output to protect. - **Unchanged path:** `tests/runner-e2e/native-completion-checks.mjs` still runs `tsc -p tests/runner-e2e/tsconfig.json` as one program. It needs about 15 GiB at default settings. I did not change it because that file and its inputs are part of a fingerprinted source contract, and no workflow calls it. - **Layer growth:** The new checks do not measure memory. If the layers or the import cycle grow, the checks still pass and the peak rises. This is intentional. Crossing 4 GiB does not fail a build. - **Project list:** The CI step checks only the projects in `PROJECTS`. The unit test covers new projects under `tests/`, but not a new project in another directory. - **Reused declarations:** `--reuse-declarations` trusts the declarations on disk. CI uses it straight after the server typecheck on the same commit. If that typecheck fails, the job stops first. Stale declarations can pass locally, so `doc/DEVELOPING.md` warns against this. - **Job dependency:** A type error in a test project now fails `Typecheck + Release Registry`, and so `ci / verify`. - **Not covered:** The new step runs no tests. `node scripts/typecheck-low-memory.mjs` and the Docker image build also have no new guard. > 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 - Provider: Anthropic. Model: Claude Opus 5.5 (`claude-opus-5-5`), through Claude Code with tool use and code execution. ## 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 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Lifecycle behavior baseline
This suite establishes a measurement before removing narrative/regex authority from lifecycle decisions. The original baseline changes no production policy. Assertions describe intended behavior; observed failures are retained rather than blessed as expected outcomes. Subsequent fixes and fresh measurements are recorded separately.
Recorded results moved to paperclip-evals
The 16 saved result JSON files and seven dated measurement reports now live in
the lifecycle authority archive
in the private paperclip-evals repository. Links below pin the archive commit.
The migration manifest
records original paths and checksums. JSON measurements are unchanged, including
failed and partial attempts; report edits only repair links to application files.
Executable tests, fixtures, graders, run commands, and the scenario inventory
remain here. These tests do not require the archive or access to the private
repository. New runs still write ignored local output under .lifecycle-baseline/;
archive retained measurements in paperclip-evals, with their source revisions
and coverage, instead of committing result snapshots to the app repository.
| Measurement | Archived report (private) | Published Product E2E report |
|---|---|---|
| September 21 — deterministic baseline | Report | Deterministic tests; run locally below |
| September 21 — initial live baseline | Report | Campaign 35672810261 |
| September 21 — cancellation and fixture fixes | Report | Campaign 35680906634 |
| September 22 — continuation authority | Report | Campaign 35747200170 |
| September 22 — explicit work mode | Report | Campaign 35806360797 |
| September 22 — accounting baseline | Report | Campaign 35813099816 |
| September 23 — accounting fixes and PR verification | Report | Campaign 35881382080 |
The public reports remain available without private-repository access. Each campaign measures its recorded source and selected cells; this index does not combine them into one score or qualify later revisions. Large logs, traces, videos, and browser reports stay in existing campaign artifact storage.
Run and inspect
From an installed Paperclip checkout:
pnpm test:lifecycle-baseline --list
pnpm test:lifecycle-baseline unit
pnpm test:lifecycle-baseline runner
pnpm test:lifecycle-baseline integration
pnpm test:lifecycle-baseline grading
pnpm test:lifecycle-baseline
pnpm test:lifecycle-baseline:support
pnpm test:lifecycle-baseline:typecheck
All four lanes are credential-free. The integration lane uses disposable embedded Postgres and scripted providers. No command above invokes a model, starts a paid campaign, or changes an existing Paperclip instance. Tests are outside default server/workspace discovery; Product E2E matcher calibration remains in its normal opt-in support suite. The baseline command returns nonzero on failed assertions, missing evidence, or unavailable selected coverage. Ordinary CI is unaffected.
Each invocation retains an independent directory under .lifecycle-baseline/:
baseline.mdandbaseline.json: scenario inventory joined to actual assertions;- per-lane Vitest JSON: complete assertion results, durations, and failures;
- observation JSONL: fixture inputs/classifications and actual authority effects, including both sides of narrative pairs and persisted heartbeat outcomes;
source.diff: tracked implementation delta from the recorded commit.
The commit plus fingerprint covers tracked differences and untracked authored
files. Keep the worktree or commit its tests with retained measurements when
comparing revisions. The scripted report marks live coverage not_run; use the separate live Actions
record for provider measurements. Authored definitions and passing grader
calibration are not proof of real provider behavior. A test
suite that cannot load is an evidence/harness failure, not a product finding.
Skips are unavailable coverage, never a pass. Failed assertions require triage;
raw runner/provider text is not uploaded by this command.
Scenario inventory
inventory.mjs is the executable mapping. References to existing suites reuse
their actual assertions rather than duplicating test bodies or counting catalog
entries as executed tests. The report records which matching assertions ran.
| ID | Scenario | Contract |
|---|---|---|
| LCA-01 | Ordinary completion | Valid completion, delivered response, no extra execution |
| LCA-02 | Productive multiple turns | Continue appropriate work without repeating completed operations |
| LCA-03 | Human question | Durable question, matching response, one causal continuation |
| LCA-04 | Approval/decline | Correct actor and approval; other admission gates still apply |
| LCA-05 | Planning/revision | Work mode and exact accepted revision authorize execution |
| LCA-06 | Dependencies | Satisfied dependency condition wakes the parent once |
| LCA-07 | External monitor | Durable eligible wait, one-shot wake, bounded expiry/retry |
| LCA-08 | Conversation | Deliver the reply without forcing task completion or repair loops |
| LCA-09 | Missing disposition | Bounded explicit repair; comments/restarts do not reset attempts |
| LCA-10 | Stop/pause/budget | Preserve distinct semantics; no unauthorized continuation |
| LCA-11 | Terminal ordering | Completion report, provider terminal, and cleanup remain distinct |
| LCA-12 | Replay/restart/ownership | Preserve receipts and budgets; fence stale finalizers |
| LCA-13 | Review | Concrete reviewer/owner and authoritative review outcome |
Troublesome combinations included in the inventory and reused suites:
- Completion followed by failure/cancellation or stream closure without terminal.
- Approval while paused/over budget; response arriving during input handoff/cleanup.
- Reassignment/closure before late finalization; restart between commit and delivery.
- Exhaustion followed by commentary versus an authorized new user request.
- Stale plan revision approval; duplicate question/dependency/reconciler events.
- Wrong company/task or unauthorized resolution; productive versus failure retries.
Narrative pairs and positive controls
authority.test.ts records the legacy classifier for diagnostic comparison and
executes the production structured continuation decision. Assertions compare
scheduling decisions rather than requiring diagnostic labels to be identical.
The persisted legacy authority tests cover replay, restart, exhaustion and
dispatch gates; they also run in the ordinary server suite. Native pairs exercise the actual
status arbiter. The heartbeat cases cross the real persistence/finalization
boundary for both runtimes, including explicit native continuation and the legacy
missing-disposition path. Observations precede cleanup; a second queue/drain pass
checks for additional dispatch. This is not proof about arbitrary future timers:
the existing monitor/retry/reconciler suites separately exercise due-time policy.
Vary summaries/results, existing comment bodies, continuation summaries, stdout, stderr, titles, and descriptions. Variants cover negation, historical quotation, Spanish, optional next steps, unsupported completion claims, encouraging prose, and empty narrative. Commentary-only evidence must not manufacture progress. Keep authority identical for each pair. Positive controls change real status, approval, continuation, budget, or ownership with identical prose. New authenticated user messages are separate causal events, not interchangeable text.
Scripted runner tests validate actual session/event behavior and structured-result contracts. They do not prove OS termination or real provider compliance. Native replacement tests inject verifier evidence at their documented boundary. Route unit tests mock services; database suites test persisted application behavior. These proof boundaries must remain visible when interpreting the baseline.
Live evals
The dedicated live lifecycle suite adds
40 explicitly selected real-LLM/browser cells on both runtime generations.
It was authored after the initial scripted baseline and has now run on GitHub
Actions; see the separate live record for measured outcomes. Use
pnpm test:e2e:runner -- --list --suite lifecycle-baseline to inspect it.
Product E2E uses the existing continuation, agent-chat, and
everyday-workflows catalogs. Continuation now retains an explicit lifecycle
snapshot at each browser checkpoint and grades pending question identity, plan
revision binding, original run receipts, and the absence of execution/recovery
paths after completion. The grader has valid/wrong/missing-evidence calibration.
The continuation definition version advances so measurements are distinguishable.
Validate/discover without spending:
pnpm test:e2e:runner:typecheck
pnpm test:e2e:runner:unit
pnpm test:e2e:runner -- --list --suite continuation
pnpm test:e2e:runner -- --list --suite agent-chat
pnpm test:e2e:runner -- --list --suite everyday-workflows
The sibling paperclip-evals change adds the opt-in
rosters/live-lifecycle-narrative-baseline.json: ordinary finish/block controls, two
misleading-summary variants, and question/review/dependency/wake cases. It does
not expand the maintained paid campaign. Both cases and the roster are validated
without providers; successful, wrong-state, missing-tool, and extra-wake evidence
calibrate their actual grader.
For subsequent live execution use existing explicit selectors and record exact
App/Evals revisions, profile/environment, retries, usage/cost, and artifact IDs.
See doc/evals.md. Do not combine mock-authority Runner Eval scores with Product
E2E scores, or claim full qualification from a partial selection.
September 22 follow-up: legacy continuation implementation and verification, including preserved failed campaigns and the remaining backlog.
The continuation accounting matrix adds ACCT-01 through ACCT-04 for separate allowances, false progress, late gates and restart/replay. Its real-provider companion is the explicit-only continuation-accounting Product E2E suite.
The September 22 measurement records the
enabled failures and preserves both initial and corrected live campaigns.
The September 23 fixes and fresh verification
retain the original measurements and cover separate persisted allowances, delayed
repair promotion and the current native question/response continuation contract.
The inexpensive browser regressions use real Chromium without a provider or Paperclip instance. They check screenshot readiness and development service-worker module revalidation across repeated reloads:
pnpm exec playwright test --config tests/runner-e2e/playwright-support.config.ts
Set PAPERCLIP_PLAYWRIGHT_CHANNEL=chrome to use an installed Chrome browser.