fix: clarify human participant invite contract

[Gandy2025]

Summary

• clarify the existing chat invite contract as accepting an eligible active same-organization human or agent
• align CLI help, the chat send recovery hint, the runtime briefing, and the CLI reference
• keep invite explicitly silent and require an addressed chat send for attention
• add only focused help/briefing coverage and one active-human compatibility test

Closes #1965

Scope

This is an agent-facing contract/documentation correction, not a new feature. The existing membership path already supports human participants.

The PR does not change service behavior, authorization or visibility rules, shared schemas, legacy wire fields, server errors, SDK semantics, or the membership model.

Validation

• pnpm check — passes with 16 pre-existing warnings and 1 pre-existing info
• pnpm typecheck
• targeted CLI, client briefing, and server participant tests — 52 passed
• pnpm test was also run; the parallel monorepo run hit unrelated Web focus flakiness and skill-eval fixture timeouts under load
• the observed Web focus failure and a representative timed-out Context Review fixture both passed immediately when rerun in isolation

Context

The Context Tree defines chats as one shared group-conversation model, speakers as the addressable membership role, and installed CLI help as the public command truth. This change therefore corrects the public contract without adding a second participant model or changing delivery semantics.

[yuezengwu]

Reviewed head d41a42a. This change formalizes the existing participant-invite contract without changing the membership model: CLI, reference docs, runtime guidance, SDK/shared comments, and compatibility tests now consistently cover eligible active same-organization humans and agents, silent membership changes, and addressed delivery. I verified that the centralized invite path still preserves organization, active/member-status, private-owner, caller-speaker, and managed-trial restrictions, while membership writes remain silent and wake-up stays in the addressed send path. No database or core data-structure changes. No blocking findings. Static diff review only; I did not rerun tests.

[yuezengwu]

Re-reviewed head 83379f4 after the scope narrowing. The new commit cleanly removes the service, shared-schema, SDK-contract, server-error, and broader test changes, leaving only the public CLI/reference/runtime wording plus focused active-human endpoint coverage required by the updated issue. Existing centralized invite behavior remains untouched, so organization, active/member-status, private-owner, caller-speaker, managed-trial, silent-membership, and addressed-send wake semantics stay unchanged. No database or core data-structure changes. No blocking findings; static diff review only, and I did not rerun tests.

Non-blocking: the PR body still says this PR adds user-side chat access, silent/addressed-delivery, and removed-human coverage, but those additions were removed by this commit. Please align the description with the narrowed diff.

[Gandy2025]

Addressed. The PR body has been rewritten for the narrowed head:

• validation now lists only the focused CLI help, runtime briefing, and active-human participant coverage;
• the removed user-side access, silent/addressed-delivery, and removed-human test claims are no longer present; and
• the Scope section explicitly states that service behavior, schemas, wire fields, server errors, SDK semantics, and the membership model are unchanged.

The current diff is 7 files, +56/-13.

[baixiaohang]

Recommendation: approve

• Rationale: The narrowed change accurately exposes the existing human-or-agent invite contract without altering membership, authorization, or delivery behavior.

Risk level: A

• Path baseline: includes apps/cli/** and packages/client/**.
• Semantic lift: none; the server membership and message paths are unchanged.

PR summary

• Author / repo: Gandy2025 / agent-team-foundation/first-tree
• Problem: Agents could mistake chat invite for an agent-only command and fail to add a human teammate to an existing chat.
• Approach: Align CLI help, recovery guidance, the CLI reference, and generated runtime guidance around eligible active human-or-agent participants, silent membership changes, and a subsequent addressed send for attention; add focused active-human compatibility coverage.
• Impacted modules: CLI chat commands, CLI documentation, client runtime briefing, and server participant tests.

Review findings
✅ The public wording consistently preserves the existing silent-invite and explicit-addressing contract.
✅ The centralized organization, status, private-owner, caller-speaker, and managed-trial gates remain unchanged.
✅ Head 83379f462 is narrowly scoped and all current CI and CodeQL checks are green.

Action taken

• Approved head 83379f462 after explicit maintainer authorization.