mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-22 20:29:18 +01:00
## Thinking Path > - Paperclip manages work carried out by agents and people. > - Native finalization converts a runner result into a durable task status and follow-up effects. > - A blocked result can name the person who must decide what happens next. > - The classifier discarded that identity, and the arbiter saved a generic board owner. > - This could replace an explicit user owner saved through the task API and leave the decision outside that person's inbox. > - This pull request resolves human owners against active company membership and preserves them through commit. > - The named person receives the existing blocker card, and the blocked worker does not get another wake. ## Linked Issues or Issue Description **What happened?** Native finalization replaced a named human unblock owner with `board`. It also overwrote an explicit user owner saved through the task API during the turn. **Expected behavior** Keep a valid human unblock owner and route the blocker card to that person's inbox. Use the board when the reference is unknown, inactive, ambiguous, or outside the company. **Steps to reproduce** 1. Create an active company member with a distinct display name. 2. Have a native worker report a human blocker using that name. 3. Finalize the run and read the task's unblock owner and the member's inbox. Related: #21265 covers named agent handoffs and retains board ownership for people. This change covers human member routing and does not add agent handoffs. ## What Changed - Resolve a human owner from an explicit user ID, an API-bound user, or one matching company member by ID, full name, or email. - Preserve the user owner for both blocker scopes and durable dependency waits. - Recheck the accepted result and active membership under the status commit lock, including board fallbacks. Rebuild the assessment on every status retry so a newly saved owner or revoked membership cannot be overwritten by stale evidence. - Enforce `canAssignTasksToHumans` before binding a human owner, including dependency waits that do not emit a `bind_blocker` effect. - Validate the result before retiring automatic completion reviews. Invalid results leave existing reviews pending; valid results retain the normal cleanup path. - Keep human blocker routing out of the agent wake queue. - Add embedded Postgres regressions for finalization, replay, personal attention, invalid owners, late API ownership changes, membership revocation, permission denial, and answer continuation for human-owned blockers. - Make the answer-continuation fixture persist the same result it classifies, so commit-time evidence validation sees realistic saved evidence. Assert the resolved user owner in both blocker scopes. - Let the recovery census clock advance at real-time pace during delivery I/O waits. This handles callbacks and nested timers without jumping to maintenance deadlines. Preserve the existing real-clock timeout and recovery assertions, and name pending queues in failures. - Document human blocker resolution and compatibility. ## Verification - Red-green reproduction: three ownership regressions failed on the original implementation and passed with the fix. - Red-green race reproduction: late API ownership changes and membership revocation failed before the commit recheck and per-retry reassessment fixes. Each finalization invocation now has to commit; a later replay cannot hide an exhausted retry. - Red-green review-retirement reproduction: a new invalid result cancelled a proven automatic review before throwing `native_result_invalid_disposition`. The new invalid/valid regression pair verifies that invalid results preserve the pending review and task decision, while valid completion still retires the card. - Red-green answer-continuation reproduction: both human-owner cases failed with `native_status_race` while saved evidence was empty. Persisting the classified result and asserting `{ userId }` restored all 13 answer-continuation cases, including worker resumption. - Red-green permission reproduction: an agent with `canAssignTasksToHumans: false` could bind a human blocker before the permission check. Direct and dependency cases now refuse finalization without creating a personal blocker card. - On refreshed head `a6d37916546`, `pnpm --filter @paperclipai/server exec node scripts/typecheck-layers.mjs` passed on macOS with Node 24. - On refreshed head `a6d37916546`, from the repository root, `CI=true node node_modules/vitest/vitest.mjs run server/src/services/native-runtime/native-agent-blocker.integration.test.ts server/src/services/native-runtime/status-arbiter.test.ts server/src/services/native-runtime/evidence-classifier.test.ts server/src/__tests__/native-status-reassessment-work.test.ts server/src/__tests__/routable-blocked.test.ts server/src/__tests__/native-status-arbiter-corpus.test.ts server/src/services/native-runtime/native-environment-blocker.integration.test.ts server/src/__tests__/heartbeat-blocked-question-answer.test.ts server/src/__tests__/issue-recovery-live-run-agent-census.test.ts` passed: 292 tests in nine files on macOS with Node 24. - Red-green census reproduction: both post-I/O callbacks and nested timers must settle without jumping to a future maintenance deadline. The nested case timed out under a zero-only clock pump; the shared automatically advancing census clock handles both. - Final CI at `a6d37916546`: [run 44848053016, attempt 2](https://github.com/paperclipai/paperclip/actions/runs/44848053016/attempts/2) completed successfully. Build, Canary Dry Run, policy, every server and workspace test shard, Runner checks, serialized suites, e2e, and verify are green. Greptile review 7 is 5/5 on the same head, Superagent and other security checks pass, and no review threads remain unresolved. A local merge-tree check against master `621c5577cdf` also passed with no conflicts. - Current CI at `a6d37916546`, [run 44848053016](https://github.com/paperclipai/paperclip/actions/runs/44848053016): attempt 1 finished with 13 interrupted nonaggregate jobs, each with an explicit runner shutdown signal in its log. Nine signals occurred within three seconds on separate m6a.xlarge hosts in us-east-1a; Build and Canary also shut down later. Aggregate e2e and verify failed on those dependency results. The underlying termination cause remains unknown. Shared CI settings are unchanged. - The [automatic recovery run](https://github.com/paperclipai/paperclip/actions/runs/44849704877) skipped retry because Build had only the annotation `Process completed with exit code 143.` The classifier reads logs for cancellation annotations, but did not read this job's log. That log explicitly records a runner shutdown at 01:10:49 UTC. The other 12 failed jobs were recognized as runner loss. After verifying all 13 logs, manually requested failed-job attempt 2; it completed successfully without source or configuration changes between attempts. The shared recovery classifier is unchanged; this false negative remains a documented follow-up. - Historical CI at `cf601ba`: all server shards (including the census), Runner checks, typecheck/release registry, serialized suites, e2e, and canary dry run passed. Build received runner shutdown signals on attempts 1–7; aggregate verify failed because Build failed. Attempt 5 diagnostics show shutdown while the job lease was valid. Attempt 7 stopped after server dependency preparation, without a compiler error. The termination cause remains unknown. Three recent PRs completed Build on the same AWS fleet; this is not evidence of a fleet-wide outage. Shared CI settings are unchanged. - Diagnostic comparison at `cf601ba`: the server compiler passed locally on macOS with four checkers, full typechecking, and declaration/JavaScript emission (`node ../scripts/run-tsc.mjs --checkers 4 --extendedDiagnostics` under Node 24). The monitored process group peaked at about 10.5 GiB RSS and finished in 25.8 seconds. This does not establish the cause of the Linux runner shutdowns. - Refreshed the branch onto master `611dc68581c` without conflicts; the PR source diff is unchanged. Greptile review 7 scored head `a6d37916546` 5/5 with no new actionable findings and no unresolved review threads. All applicable CI gates passed on attempt 2. - Full local workspace build at `cf601ba` passed on macOS using Node 24 and the documented single-thread compiler mode: `PAPERCLIP_TYPECHECK_LOW_MEMORY=1 npx --yes --package=node@24 --package=pnpm@9.15.4 pnpm build`. This includes typechecking and artifact emission. The tracked working tree stayed clean. - `pnpm verify --explain` returned exit 2 because this documentation path requires broad CI coverage. Fresh CI will supply that coverage; the full local test suite was not run. - Earlier CI build and canary jobs received runner shutdown signals. The server shard also exposed an answer-continuation fixture that saved an empty result while classifying a named human. That mismatch was reproduced locally, and the fixture now persists the classified result and checks the user owner. Fresh CI is required for this revision. - `git diff --check` and the staged gitleaks scan passed. The diff was also checked for private issue references, identifiers, URLs, and personal data. ## Risks - Name and email matching ignore case. Several matches fall back to the board. Invalid explicit IDs never fall through to another person. - Resolution adds bounded reads only when a native result reports a human blocker. It adds no worker, timer, or idle scan. - No database or result-schema migration is required. Existing board and agent decisions remain readable. Committed historical decisions are not rewritten; new finalizations use current membership. - This changes human routing only. It grants no access and changes no merge, approval, or dependency policy. ## Model Used - OpenAI GPT-6.1 Sol (`gpt-6.1-sol`) through Codex in T3 Code, with xhigh reasoning effort, code editing, shell tools, and test 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 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>