Files
PaperClipAI/doc
Devin FoleyandPaperclip 18978bdc1d fix(native): preserve named human unblock owners (#22438)
## 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>
2026-11-20 17:45:45 -08:00
..
2026-02-16 14:25:00 -06:00