fix(users): filter removed members from tw users by default

[lmjabreu]

Summary

tw users was listing users who had been removed from the workspace. In Doist (ws:1585) this meant 554 entries returned for what is actually a 146-member workspace, polluting tw users [--json] output and silently breaking resolveUserRefs — any command that takes a name/email user ref (tw channel add, tw groups add-user, etc.) could resolve to a tombstoned user and then 403 from the backend with User N is not part of workspace.

Root cause: Twist's v4 workspace_users/get?id=<wsid> endpoint returns both active and removed members with a removed: boolean flag. The SDK's WorkspaceUserSchema already exposes that field — the CLI just wasn't reading it. The curated --json formatter also stripped it, so the staleness was invisible.

Reproducer (before the fix):

$ tw users 1585 --json --full | jq '[.[] | select(.removed)] | length'
408
$ tw users 1585 --json | jq '. | map(select(.id == 2342 or .id == 2343))'
[
  { "id": 2342, "name": "Test User1",  "userType": "GUEST" },
  { "id": 2343, "name": "Test User 2", "userType": "USER"  }
]
$ # Both above are removed members; adding them to a channel returns 403
$ # "User 2342 is not part of workspace 1585"

After the fix:

$ tw users 1585 --json | jq '. | length'
146
$ tw users 1585 --json --include-removed | jq '. | length'
554
$ tw users 1585 --include-removed --search "Test User1"
id:2342  Test User1 <test1@doist.io> [GUEST] [removed]

Changes

Layer	File	Notes
API helper	src/lib/api.ts	getWorkspaceUsers(workspaceId, { includeRemoved? }) filters removed === true by default. One filter, fixes tw users, resolveUserRefs (src/lib/refs.ts), and resolveNotifyIds (src/commands/thread/helpers.ts) in one shot.
Command	src/commands/user.ts	New --include-removed flag. Human output appends a red [removed] chip.
JSON	src/lib/output.ts	Added removed to USER_ESSENTIAL_FIELDS so callers can distinguish the two states without --full.
Tests	src/commands/user.test.ts	Two new tests: default omits removed users, flag passes through and chip renders.

getUserById-based callers (e.g. tw groups view) were already correct because they only fetch ids that the group's userIds list references — removed users aren't there.

Why a flag, not always filter

Audit/recovery cases occasionally do want the historical roster (e.g. "who used to be in here?"). --include-removed covers that without making the common case noisy.

Side discoveries

None. Scope was kept tight to the diagnosed bug.

Checks

• npm run type-check
• npm run lint:check
• npm test — 653/653 (2 new)
• Manual end-to-end against workspace 1585 (Doist) — counts above

Follow-up to side-discovery #3 in #244.

[doistbot]

This PR thoughtfully addresses a significant issue with reference resolution by ensuring tw users filters out removed members by default, while introducing an --include-removed flag to access tombstoned users when needed. These changes greatly improve the reliability of workspace user management and correctly utilize the v4 API schema. A few minor adjustments are needed to document the new flag in the AI agent skill content, realign a misplaced test block, and strengthen the test suite to properly verify both the default filtering behavior and the updated JSON payload.

_{Share Feedback • Review Logs}

[scottlovegrove]

I'm wondering whether this should be the default of the SDK rather than this. The MCP probably has the same issue :/

I think I would prefer this to be the default of the SDK

[scottlovegrove]

I'm wondering whether this should be the default of the SDK rather than this. The MCP probably has the same issue :/

I think I would prefer this to be the default of the SDK

This has been done and is available in 2.8.1 of the SDK. @lmjabreu ask your agent to pull in that newer SDK, and then we can tidy up this PR. The PR should still make the flag available, but it doesn't need to do any of the filtering.

[lmjabreu]

@scottlovegrove done — bumped to @doist/twist-sdk@2.8.1 and reduced getWorkspaceUsers to a pass-through that forwards includeRemoved. Verified against ws:1585: default returns 146 active users (was 554 pre-fix), --include-removed returns 554 with the removed field intact in curated JSON. The four doistbot review threads are addressed inline + resolved.