feat(service): give the triage claim gesture a Claim Case button

[os-steve]

Fixes #1144

Piece 2 of #1144, ruled Option A in decision batch #21 (2026-09-03, verbatim 「批次 #21 同意」, ruling comment 5527983203). Piece 1 — the docs — landed 2026-08-31 in PR #1409 as Part of. This one closes the card.

What ships

Claiming an unowned case already worked and had done since the claim seam shipped: an agent moves the case to In Progress, Waiting on Customer or Waiting on Support, and case_self_claim (priority 260) stamps them as owner. Nothing on the screen said so. This adds the affordance.

claim_case action	type: 'flow', locations: ['record_header', 'list_item'], refreshAfter
claim_case flow	screen flow, runAs: 'user', one update_record writing status and nothing else
guard	test/claim-case-one-owner-writer.test.ts — the flow's payload never carries owner_id
i18n	four locale packs (en · zh-CN · es-ES · ja-JP)
docs	the built-in flow table row in three locales, plus the (27) → (28) numeral

Two things measured rather than copied

① The visible predicate is the GRANT's, not the card's. The card asked for record.owner_id == null && record.is_closed == false. Re-derived from src/objects/_case-assignment.ts → src/sharing/case.sharing.ts as the ruling's execution note instructed, case_unassigned_triage_sharing reads:

record.owner_id == null && record.status != "resolved" && record.status != "closed"

is_closed is derived as status === 'closed' and never flips on resolved, so the card's version would have offered a Claim button on resolved ownerless cases the agent is not shared and cannot claim — a button that answers FORBIDDEN. The action carries the grant's expression, and the guard compares it against the shipped rule rather than a literal, so a future re-derivation of the grant moves both or fails.

② runAs: 'user' is load-bearing here, not boilerplate. case_self_claim returns early for a write with no user and again for ctx.session.isSystem. An elevated run would move the status and claim nothing — the case leaves triage still ownerless, which is worse than a refusal because it looks like it worked. House rule 9 already says a screen flow stays user; this is the case where that is functional. Declared explicitly and guarded.

Ownership keeps exactly one writer, and it is proven able to fail

The ruling asked for the guard, and the dispatch asked that its ability to fail be demonstrated before its green was believed. Two mutation legs were run at the same site — the claim node's field map — each proven on disk by blob hash before the run it justifies, each restored by git checkout HEAD -- <path> and the restore proven by the file's blob hash matching HEAD: and by an empty git diff HEAD.

mutation added beside status	claim-case-one-owner-writer	flow-case-actions
owner_id: '{$user.id}'	RED — claim (update_record).status,owner_id	GREEN
owner_id: 'agent-literal'	RED	RED — expected 'agent-literal' to be null

Restored run, both files: Test Files 2 passed (2) / Tests 22 passed (22).

⭐ The two legs did not agree, and that is written into the runtime file rather than smoothed over. The flow harness binds no user, so {$user.id} resolves to nothing and the column still reads empty — which is precisely the form an author would reach for. The metadata guard is what catches the realistic mistake; the runtime cases are its behavioural companion, not its replacement. A note in test/flow-case-actions.test.ts says so, so nobody later deletes the metadata guard on the grounds that "the runtime test covers it".

Surface: three files beyond the declared list, each mechanically forced

The dispatch scoped this to the action, the flow, four packs, three automation*.mdx, one new guard, barrels and the changeset. Three more files were required by gates, not chosen — declared here rather than smuggled:

• test/automation-docs-coverage.test.ts — a ROW_LABEL ledger entry. A shipped flow with no Chinese row label reds the ledger answers exactly the flows this app ships; the ruling itself names this file as the gate the docs rows satisfy, so the entry is the other half of the ruled work.
• test/flow-case-actions.test.ts — test/runtime-coverage.test.ts requires every registered flow to be named in a test/flow-*.test.ts. claim_case joins its two siblings in the file that already owns the case screen actions, rather than taking a PENDING_FLOWS entry — that list may only ever shrink, and a new flow's first act should not be to grow it.
• README.md + docs/STATUS.md — docs-metadata-counts and docs-declared-versions read the flow and action counts off the compiled stack. 27 → 28 flows, 30 → 31 actions, five claims across the two files.

Nothing under src/actions/lead.actions.ts (#1578) or content/docs/reference/faq* (#1402) is touched. src/objects/_case-assignment.ts is read but not edited — see below.

Verification

Union run on the final commit 63c2890 (git rev-parse --short HEAD read from that same tree), the heavy legs through the shared verify lock with OS_VERIFY_LOCK_SLOT=hotcrm-1144, every exit code captured by redirect-then-read and never across a pipe.

• Full suite — pnpm exec vitest run --maxWorkers=2 → Test Files 160 passed (160) / Tests 3391 passed | 1 skipped (3392), lock line VERDICT command-exit 0 · held the lock 169s.
• pnpm validate && pnpm typecheck → VERDICT command-exit 0. pnpm build && pnpm lint → ✓ Build complete, VERDICT command-exit 0; no lint finding names claim_case.
• Gate scripts — check-source-hygiene.mjs → ✓ source hygiene clean; check-source-token-ratchet.mjs → ✓ source token ratchet clean; check-lint-i18n-gate.mjs → ✓ i18n lint gate: 0 i18n/missing-* issues.
• Control bytes over all 17 changed files → grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]' exit 1, zero matches.

⚠️ Budget note for the reviewer. The business semantics ratchet moved ~84,018 → ~84,571 (+553), leaving ~429 tokens of headroom under the 85,000 ceiling. Clean, but the next src/objects|flows|actions|hooks addition of any size will not fit. Comments and blank lines are stripped, so this is real code; the four locale packs are outside the ratchet by ruling and cost nothing here.

One finding, filed not fixed

#1593 — #1327 closed with its acceptance criterion half met. Its header fix landed (git grep 'two layers' is empty today), but case_self_claim's guard-4 comment still says the sharing rule "draws with is_closed == false", which it has not since #1145. Same file, same two layers, one screenful below where the fix landed. #1327 is closed, so this is its residue rather than a duplicate; a targeted search returned 44 results and no open card names it. ⛔ Not fixed here — outside this card's surface, and the predicates themselves are correct and deliberately asymmetric.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated
hotcrm	Ignored		Sep 5, 2026 3:45pm UTC