Skip to content

Latest commit

 

History

History
1718 lines (1487 loc) · 113 KB

shared-crew.md

File metadata and controls

1718 lines (1487 loc) · 113 KB

Shared Crew

Owner: config.sections_shared_crew (the dashboard.shared_crew section). The sections below are filled in as each part of Shared Crew lands.

1. Purpose and boundaries

Shared Crew lets several people who can already reach one Crew work in it together. It attributes what each person does, charges execution to the person who asked for it, keeps one person from exhausting the host, and shows collaborators to each other.

It is an attribution and fairness layer, not an access layer. The network (Tailscale) and the existing dashboard auth in dashboard.token_auth, including the direct tailnet listener's whois (section 2, Who gets in), decide who may connect; Shared Crew never admits a request auth refused, and never refuses one auth admitted because an identity lookup failed. Every authorized collaborator has the same application rights. There are no roles and no per-session ACLs. The one in-Crew membership action is the owner's Tailscale invite (§2 Tailscale invites), which shares this machine through Tailscale and admits the login that accepted, in Tailscale mode only. Tailscale is the only access authority: Crew approves nobody and nobody types the set of people who get in.

No permission scoping in this release: every collaborator a Crew admits has the same rights, and no code path reads a role or an ACL.

A Crew is a machine identity, not a group of people. Its synthetic principal is the Crew acting as itself; the people who may work in it are individual grants, and several Crews may have overlapping member lists.

Status: proof of concept. shared_crew.wiring and shared_crew.lifecycle connect the sections below at gateway start (dashboard.server). With every switch at its default the gateway behaves as a single-operator Crew, and the direct tailnet listener binds nothing.

Release gate

Shared Crew is behind one release gate until the owner ships it, the Feature preview (shared_crew.preview.preview_enabled). Either of two things turns it on: the gateway environment variable KIROCREW_SHARED_CREW_PREVIEW=1 (true only for exactly 1), or the owner's stored choice in the keystone <data home>/shared_crew_preview.json ({"enabled": true}, only a JSON true counts; a missing, unreadable or malformed file reads as off). It is not a config field and not a change-card or FEATURE_PREVIEW_FLAGS entry. The file is written only by the owner-only PUT /api/shared-crew/preview (routes_preview), and it is sealed like decisions_consent.json: on _CREW_SECRET_LEAVES, sandbox._CREW_READONLY_LEAVES, _CREW_PRECREATE_READONLY_FILE_LEAVES and _CREW_CHILD_WITHHELD_LEAVES, so an agent can neither write it nor edit its way to opening the Crew.

The stored choice is read once when the gateway starts (preview.snapshot_at_start, taken on the first preview_enabled() call) and preview_enabled() answers from that snapshot, or from the variable, for the life of the process. Routes, the direct listener and the lifecycle hooks are wired at start, so a PUT applies on the next start.

GET / PUT /api/shared-crew/preview are registered whether or not the preview is on (never 404 for the owner; a caller who is not the owner gets 403 through the invite routes' owner gate). The answer is {enabled, active, env_override, restart_required}: enabled the stored choice, active what this process runs, env_override true while the variable forces it on, restart_required true when the next start will answer differently. A PUT body is {"enabled": bool}; anything else is 400 invalid_body. Each PUT is written to the SEL (shared_crew.preview.set).

  • Gate off (the default): config.sections_shared_crew.load_shared_crew_config, the runtime's one reader of the section, returns SharedCrewConfig() whatever config.json says. admission_enabled, hard_limits and every other dashboard.shared_crew switch read as their default, fair admission stays a pass-through and the gateway behaves as it did before Shared Crew. The stored values are not rewritten: only the runtime read is gated, so a save keeps them.
  • Gate off also keeps question cards owner-only: collaborators.is_collaborator_actor admits no one and no collaborator socket receives a card, so /api/ask-question reads, answers and dismissals refuse non-owners as before.
  • Gate on: config decides, as every section below describes.

GET /api/shared-crew/capabilities reports the gate as shared_crew_preview (true or false). Each field's help in the Settings schema says it needs Shared Crew turned on in Feature Previews.

Advanced settings write through the existing config PATCH, PATCH /api/config/kirocrew with {"path": "dashboard.shared_crew.<key>", "value": ...} for admission_enabled and tailnet_direct (booleans) and principal_concurrency (1 to 256), crew_concurrency (0 to 1024), typing_idle_seconds (3 to 60) (integers; bounds from SHARED_CREW_BOUNDS). Advanced saves through the shared per-path optimistic overlay and its restart pills come from the config schema. hard_limits and containment_enabled are not in the editable set. The section reads as its defaults while the gate is off, and tailnet_direct takes effect on the next start.

2. Identity

Principal

contracts.Principal is the identity work and records are attributed to. Its id is principal_id_for(provider, issuer, subject): a deterministic, opaque digest, so one person maps to one id on every device and tab without a registry, and the id does not reveal the login. Email and display name are never inputs; two providers asserting the same email are two principals. DisplaySnapshot is a label captured when the principal was seen. A rename changes it and leaves id alone. It carries no avatar URL, because a remote URL in a shared record is an outbound fetch someone else chose.

PrincipalKind separates a person (human), a device with no personal identity (machine, such as an ACL-tagged tailnet node, keyed by node because every tagged node reports the same login), Crew automation (system, one bounded principal per named component from Principal.system), and unknown.

Derivation

identity.publish_actor derives the principal once per request, after token_auth_middleware admitted it and before the handler, and publishes an ActorContext under request[ACTOR_REQUEST_KEY]. Handlers read it with identity.actor_of (viewer_principal for the principal); a request with no published actor reads as Unknown, never as the operator. The WebSocket upgrade passes through the same middleware, so a socket's actor is the upgrade request's. The browser never names itself: a principal is never read from a body, query, header or display name, and from_dict exists only to read records this server wrote.

Evidence, strongest first (identity.derive_principal):

Request Principal Provenance
An app identity (an app token, or an internal caller the middleware derived an app for) system, component app:<name> internal
The internal loopback secret (kiro-cli, MCP, doctor) system, component internal internal
Loopback peer forwarded by local tailscale serve, resolved and allowlisted by tailnet.resolve_forwarded_peer human keyed by tailnet login; machine keyed by node for a tagged node tailscale_serve
Tailnet peer on the direct tailnet listener, admitted by daemon whois of its own TCP ip:port (tailnet_direct.DirectGate) human keyed by tailnet login (the stable user id is an alias); machine keyed by node for a tagged node tailscale_listener
Tailnet peer reaching a widened bind on its tailnet address, no forwarding header, resolved by daemon whois of the socket address (tailnet.resolve_direct_peer) human keyed by tailnet login; machine keyed by node tailscale_direct
Loopback socket with no forwarding header at all human, the local operator, keyed by the token subject; labelled with this machine's name when the subject is one of the owner's (see Owner label) local_operator
Anything else auth admitted Principal.unknown() none

A tailnet principal's subject is the lowercased daemon login under provider tailscale and issuer tailnet; a tagged node's is node:<name>, because every tagged node reports the login tagged-devices. The display snapshot is the login (or node name) as the daemon reported it, so a rename never changes the id.

A person is keyed by their tailnet login on every transport, never by a display name. tailscale serve names only the login, while the direct listener's whois also names the stable user id (UserProfile.ID); the user id is an alias of the login, never the key, so one person reaching the Crew through Serve and through the listener is one principal with one admission budget. Every node of one user, a re-created node and a node shared in from another tailnet (Node.Sharer set; the principal is the node's owner, never the sharer) map to that principal. The display name is a label only. The device a person was seen from is the node key.

Direct tailnet listener

Release gate (requires KIROCREW_SHARED_CREW_PREVIEW=1): with the gate off, tailnet_direct_listener reads dashboard.shared_crew.tailnet_direct as off whatever config.json says, so the listener never starts, and no derived set is installed, so allowed_logins decides the tailscale serve path as before. The invite, credential and avatar routes under /api/shared-crew/tailscale/ and the /api/shared-crew/access routes answer 404 (routes_invites.preview_only), and the invite poller does not run. The boot path imports none of the preview-only modules either (no-new-work-on-gateway-boot-path): the route slice registers those routes through _preview_only wrappers that import routes_invites / routes_access on a preview request, token_auth imports tailnet_direct only once a direct gate exists, and start_dashboard / start_api_server skip lifecycle and tailnet_direct_listener entirely. test_shared_crew_preview_gate_p2.py pins this in a fresh interpreter. With the gate on, everything below applies unchanged.

Invites follow the tailnet governance pin. Invites share this machine over Tailscale, so they answer to the same capabilities.tailnet_origin ceiling as the direct tailnet listener (tailnet.is_governance_pinned_off). While an enterprise policy pins it off, the invite and credential routes (status, create, resend, revoke, connect, disconnect) answer 404 (routes_invites.governed), and the accept poller does not start. A pin that lands while the poller runs also stops it: tailscale_invites.sync reads the pin again before it reads Tailscale, and once more, audited, under the commit lock before it admits anyone. The People page hides invite data it read before the pin. The capabilities read reports invites: {state: "unavailable", reason: "governance_pinned_off"}, and the People page then reads no invites and shows no Invite… control. Each route but the status read writes its decision to SEL, as the poller start does; the status read and the capabilities read are not audited. The avatar routes stay open, because People names and pictures use them. There is no new scope or policy key for this.

With dashboard.shared_crew.tailnet_direct on (it is off by default; a value that is not a boolean reads as off) and Tailscale running, the gateway also listens on this machine's own tailnet addresses (100.64.0.0/10 and fd7a:115c:a1e0::/48, from the daemon's status) on the dashboard port (dashboard/tailnet_direct_listener.py). It never binds a wildcard, a LAN address or any non-tailnet interface, and it does not start beside a widened bind (KIROCREW_BIND), under a governance ceiling that pins capabilities.tailnet_origin off, or when the daemon names no address or no owner login. Loopback is unchanged. Off keeps the loopback-only listener; a change applies at the next gateway start. The bind is fixed at start; a Tailscale that starts later, or an address change, needs a gateway restart.

A request is on the direct listener when the local end of its TCP connection is one of those addresses (DirectGate.owns). token_auth_middleware decides it before any token is read:

Check Refusal (403, code: tailnet_direct_refused)
Socket peer is a tailnet address not_tailnet_peer
Socket peer is not one of this machine's own tailnet addresses (a local process uses loopback) self_connection
No Forwarded, X-Forwarded-* or X-Real-IP header forwarded_header
Daemon whois of the peer ip:port names a node key and a user with a stable id whois_failed
Same node key as the connection's earlier answer node_changed
Tagged node: one of its tags is a tag:<name> entry the seed carried over tagged_node_not_allowed
Person: any person the whois names, untagged with a stable user id none; Tailscale already decided

Only the whois answer is cached; the admission rule runs on every request, so a person Tailscale stops naming is refused on the next request, with no restart. An admitted request needs no dashboard token. The owner (stable user id and login both match this machine's node, tailnet_direct.is_owner) carries the owner's dashboard subject (owner_id, else the bootstrap local-app) and auth_owner_whois, so every owner-gated route answers it (dashboard.tailnet_owner). Two irreversible actions, DELETE /api/shared-crew/tailscale/credential and DELETE /api/sessions, also need X-Kirocrew-Confirm: irreversible, which the dashboard sends only after its own confirm dialog; without it the answer is 428 confirm_required. Anyone else is the dashboard user tailnet:uid:<id> (a tagged node tailnet:node:<name>), which never matches the owner subject, so owner-gated routes refuse it. A token or cookie it carries is ignored, except an app token, which runs the ordinary token flow so the app keeps its scope. Strict internal paths and the internal secret are refused on this listener. It cannot mint a bearer link (_caller_bounds lends no lifetime), and /api/auth/me reports auth_method: tailnet_direct. A Tailscale-User-* header is never read here. Browsers get the refusal as a page, everything else as JSON.

whois is not run per HTTP request. It runs once per connection and is cached per ip:port for WHOIS_TTL_SECS (30 s; a failure for 2 s; at most WHOIS_CACHE_MAX_ENTRIES entries). A WebSocket upgrade always asks again, and an open WebSocket is re-verified every WEBSOCKET_REVERIFY_SECS and closed when its peer stops verifying. Any whois failure rejects the request; there is no Unattributed fallback on this listener.

The daemon is reached with tailnet_localapi, LocalAPI first, then the CLI. Every location is one the gateway user cannot write: a socket or token file must be root-owned in a root-owned directory, and a CLI found on PATH is used only when it resolves to a vetted install location (tailnet._CLI_CANDIDATE_PATHS). Nothing is installed. The method used is reported in the capabilities (tailnet_direct.method). The CLI fallback spawns through tailnet.run_cli_json, and answers are parsed by tailnet.whois_identity, tailnet.dns_name_from_status and tailnet._self_login, the same code the tailscale serve path uses, so both paths give a peer the same login and node name (Node.Name first).

Platform Order Status
Linux LocalAPI unix socket (/var/run/tailscale/tailscaled.sock, /run/tailscale/tailscaled.sock), then the CLI code path and tests; live check on a host with Tailscale pending
macOS open-source daemon socket (/var/run/tailscaled.socket), standalone app LocalAPI (/Library/Tailscale/ipnport and sameuserproof-<port>), CLI on PATH, CLI in /Applications/Tailscale.app/Contents/MacOS/Tailscale code path and tests with fakes; unverified on macOS
Windows CLI in C:\Program Files\Tailscale code path and tests with fakes; unverified on Windows

whois names the user who owns the Tailscale node, not the operating-system user at that machine. Several people sharing one node are one principal; each of them needs the token path to be told apart. People says so.

Supported topologies:

Topology Names people Admission
Direct tailnet listener (off by default), Linux yes, by stable user id whois, no token
Direct tailnet listener, macOS and Windows yes (code path, unverified on those systems) same
tailscale serve to loopback, Linux with tailscaled as root yes, by login token plus derived set
tailscale serve to loopback, macOS, Windows, Linux with a non-root tailscaled no, Unattributed token plus derived set
Widened bind reached on a tailnet address yes, by login, attribution only token

The serve and widened-bind rows require the existing identity-trust opt-in (dashboard.tailscale.trust_identity with a non-empty allowed_logins, i.e. TailnetTrust.enforces_identity). Without it no daemon lookup runs on those paths and tailnet callers are Unknown. The serve row reuses the middleware's existing resolution, allowlist deny and pin unchanged. The widened-bind row is attribution only: its lookup runs after the auth decision, shares the whois cache and executor, and is read by neither the pin (a direct peer stays ip:-pinned) nor the allowlist, so it cannot admit or refuse a request.

Loopback alone is not proof of a trusted proxy: a loopback request carrying any forwarding header (origin.is_proxied_request) is never the local operator, and its forwarded address is attributed only through the daemon. Under the preview it is read only after the kernel proves the client end of the loopback socket belongs to tailscaled (tailnet_proxy_proof.loopback_client_is_daemon, Linux only; elsewhere the serve row never resolves and such a caller is Unknown). Without the preview the proof does not run, so the daemon still names the peer and an off-list login is denied on every platform, as before. Only a tailscaled running as root is that proof (any user can name a process tailscaled), so a local token holder adding X-Forwarded-For is Unknown, not the person it names. Under the preview, without the proof the allowlist still decides admission (tailnet.forwarded_peer_refusal): a forwarded tailnet request is admitted, as Unknown, only when the daemon's whois of its single forwarded address names an allowlisted login, and refused otherwise, so access never widens where names cannot be proven. Without the preview the serve path is as before: an unresolved peer falls through to token auth (fail-open on availability, rfc-tailnet-dashboard-access).

Supported matrix for the serve row: Linux with tailscaled running as root names people; Linux with a non-root tailscaled, macOS and Windows admit allowlisted people as Unknown. macOS gives an unprivileged process no owner for another user's loopback socket, Windows has no such check in this build, and tailscale serve does not register its loopback connections for a whois by port. The direct tailnet listener names people on every platform. When it is active, attribution is available and the capabilities carry attribution_via: tailscale_direct and tailnet_direct (state, reason, method, urls, owner_login, addresses). Otherwise, when identity trust is on and the gateway listens on loopback only, host_power.probe_after_start runs tailnet_proxy_proof.proof_support() in a background task after the listener accepts requests and records it (access.note_proof_gap); attribution reports degraded (not_checked) until then, and afterwards unavailable (platform_unprovable, daemon_same_user) or degraded (daemon_not_found). A Tailscale-User-Login header that disagrees with the daemon drops the attribution. A non-loopback peer that sends X-Forwarded-For is a proxy on another node and is Unknown. Funnel, other reverse proxies and unverifiable forwarding headers resolve to Unknown.

Failure never changes access. Derivation runs only on an admitted request, and an exception anywhere in it publishes Unknown. A request auth refused publishes nothing.

ActorContext.auth is a copy of what the middleware decided, kept for audit. It is not a second decision. correlation_id is the client's X-Correlation-Id when it is a short plain token, else the server's request_id.

Owner label

The owner is the person at this machine. owner holds who: the bootstrap subjects local-app and local-startup, the configured owner id (owner.set_owner_subject, set by wiring.install from state.owner_id; default local-app) and the owner's tailnet login (access_set.owner_login) are one person (owner.owner_principal_ids). Principal ids never change: they come from the token subject or the login alone.

The label shown for the owner's local principals is this machine's name (owner.machine_name, applied in identity.local_operator_principal to the owner's subjects only): macOS ComputerName read once through the fixed path /usr/sbin/scutil (never PATH), else the Tailscale daemon's Self.HostName (SelfNode.host_name, published when the owner is learned), else the OS host name, else the token subject. It never raises. The scutil lookup never runs on an event-loop thread: wiring.install warms the cache on a daemon thread (owner.warm_machine_name), and a label read on the loop before it lands answers from the fallbacks. An owner who reaches the Crew through the direct listener keeps the tailnet identity whois named. Another local subject keeps its subject as its label.

Observed collaborators

people keeps a bounded in-memory record (MAX_OBSERVED principals, LRU) of the human and machine principals seen on authorized requests, with first and last sighting and a device count (a digest per node, at most MAX_DEVICES). Unknown and system principals are not recorded. people.people_view builds the People body: it merges that record with the creators recorded on persisted sessions and with the people the local Tailscale daemon lists, in that order, so a person keeps the first row they have. Each row names its sources (observed, session_creator, tailscale_share), so an observation is never presented as membership, and carries is_owner (the row's principal is one of owner.owner_principal_ids). An owner viewing always has a row, and the owner's local-token rows fold into one, matched by principal id because a creator read back from public attribution carries no provenance. Only the owner's People lists tailscale_share rows: the daemon names every user this machine can see, ordinary tailnet members included, so the route reads it for the owner alone and a collaborator's People never carries the login of someone who did not come in. tailscale_share rows (tailscale_sharees) are users who own a node in the daemon's status with peers (tailnet_localapi.status_with_peers, parsed by tailnet_direct.parse_tailnet_users) and who are not this machine's owner; a tagged node has no person and is skipped. The parser retains at most MAX_TAILNET_USERS people in first-seen peer order and logs one warning per status snapshot with the count of otherwise eligible people omitted by that cap. One row per retained user is keyed by tailnet login through identity.tailnet_principal, so the id is the one the same person gets when they connect and the row then merges into the observed one. An unobserved row has null first_seen_at and last_seen_at, devices 0 and sessions_created 0, and carries tailscale_user_id and, when the daemon gave a plain https one, member.profile_pic_url. They need no Tailscale API key and no allowed_logins. The daemon read runs off the event loop under a 6 s budget and is cached 15 s (CACHE_TTL_SECS); a failure yields no such rows and never fails the route. directory.state is unavailable because this build has no authoritative assigned-user directory. Per-person usage is null, and usage_available false, until the admission layer registers a reader (people.register_usage_source).

People and setup modes

crew_mode puts every Crew in exactly one mode, served by GET /api/shared-crew/mode (dashboard user only, 403 otherwise). The People surface, setup guidance and session list follow it, and the modes never mix:

Mode When People shows Session list
personal no setup path is available or degraded, and no principal but the local operator viewing has been seen (the operator's bootstrap subjects local-app, local-startup and the configured owner are the same person; session creators are matched by id, never by a stored provenance) setup guidance with each adapter's honest status, personal Remote Control no creator bylines, no All/Mine control
network a Tailscale path is on, or a network person or another operator has been seen the share card with the Tailscale path's status (first on the page), who has been seen (labelled as seen), personal Remote Control bylines, filter
invalid the tailnet login allowlist could not be read one error state with the reason code bylines, filter

The session list's bylines and filter, message bylines, decision attribution and presence chips are all part of the Shared Crew preview. They show only when the preview is on (shared_crew_preview), the mode is read and not personal, and someone besides the owner has joined: a non-owner People row this Crew saw on an authorized request since it started (sources holds observed; sharedCrewUi.someoneJoined). A row known only as a session's creator (a Slack sender), an unused invite or a directory entry has not joined. The observed list is in memory, so after a restart these surfaces return once a teammate connects again. One rule decides it for every surface (sharedCrewMode.showsTeamAttribution, read through useTeamAttribution and useSharedCrewListView); with the preview off the browser reads no mode or People for them. Until then the dashboard looks as it does for one person.

A team configuration is refused (crew_mode.team_config_problem) with reason network_identity_config_unreadable while the tailnet login allowlist could not be read (config.resolution.tailnet_identity_unknown, recorded by access.note_tailnet). The gateway logs the refusal at start (crew_mode.validate_at_startup, from wiring.install) and lifecycle.team_config_middleware refuses every tailnet person with 403 {error, code: team_config_invalid, reason} while it holds. The local operator keeps working and sees the error in People. An invalid team setup never falls back to personal mode, and the browser treats an unreadable mode route as an error, not as personal.

The mode body: mode, crew_id (the gateway id; it keys the browser's remembered list filter), viewer, team_config (state not_configured | invalid, with reason, capability, cause), console (always not_offered), adapters (the setup paths) and workload_identity_ref (always unavailable). The Tailscale link is a fixed public documentation page. Identity is never inferred from the OS user or a typed label, and loopback alone yields the local operator only together with a dashboard token.

People has no role control in any mode. Its one invite and revoke control is the Tailscale invite card below, shown in personal and network mode to the owner only. Inviting adds a person to the tailnet, which is the sharing step. People has no access card and no waiting list, Approve, Dismiss or Remove control.

Settings reports a failed capabilities read with an error notice and retry even when the unknown preview gate hides People. With cached preview capabilities, People owns that notice while open, keeping its drafts mounted. The network share card owns invite-status failures (including a successful response with a sync error); an open invite dialog owns the same notice instead, with retry and its draft retained. Failed invite reads never become an empty People list. Missing optional routes and initial owner-only refusals still hide invite controls.

Who gets in

Tailscale is the only access authority: the tailnet ACL and device sharing decide who can reach this machine, and Crew approves nobody itself. The direct listener admits every whois-verified untagged person, and Tailscale still names them, so identity, attribution and owner rights come from whois as above. A tagged node is refused unless a tag: entry was carried over in the seed below. The not_tailnet_peer, forwarded_header, whois_failed, node_changed and self_connection refusals are unchanged. Removing a person is done in Tailscale: revoke their invite in Crew (which deletes the share) or remove them from the tailnet.

The tailscale serve path and mobile setup check a login against a derived set (shared_crew.access_set), never typed:

Member Matched by Source
the owner stable user id and login of this machine's node daemon status at start
a person who accepted a Crew invite the accepting login (acceptedBy.loginName) tailscale_invites members
the migration seed login, or tag:<name> for an ACL-tagged node dashboard.tailscale.allowed_logins, read at the first start, only shrinks

Before the dashboard binds, the gateway publishes an owner-only placeholder (access_set.install_placeholder, no I/O); tailnet_direct_listener.start reads the set after the bind. At the first gateway start with a readable tailnet section, access_set.install copies allowed_logins (logins and tag: entries) into the set as its seed and marks it seeded. After that the seed only shrinks: at each start an entry no longer in allowed_logins leaves the seed, and an entry added later admits nobody. People lists the carried-over entries. With the set installed, tailnet.login_allowed reads the set and ignores the list it is handed. The invite flow still mirrors an accepted login into allowed_logins, because trust_identity needs a non-empty list for the serve path to resolve identities at all. The mirror is written only after the member row is durable, so revoke always finds whoever a seed could hold; a failed mirror write keeps mirror_pending on the row and the next sync retries it. The dashboard has no control that edits the list.

Owner routes (shared_crew.routes_access, the invite routes' owner gate):

Route Does
GET /api/shared-crew/access carried-over entries, first_share
POST /api/shared-crew/access/first-share/ack record the first-share acknowledgment

Revoking an invite deletes it at Tailscale, which ends the share, takes every login the person came in under (current, recorded at each accept, and named by the daemon since start) out of the set, the seed and the config mirror, refuses them live on the serve path, and closes their open dashboard sockets and any forwarded socket nobody could name (routes_invites.close_revoked_sockets). Crew stops no work itself. Revoking and tailscale_invites.sync commit one at a time (_commit_lock): sync reads the invite state again under the lock, and an invite Crew made that was revoked after the list was read admits nobody. Every revoked id is also kept in the store (revoked_invite_ids, the newest 512), so a sync that holds a reusable link as accepted by someone new admits nobody by it, even while a removed member's row still names that link. A refused read on these owner-only routes, and on the team-config gate, is written to SEL (routes_invites.audit_read_refusal); a refused write stays one record, from the request audit.

First share. While nobody but the owner is in the set and the owner has not acknowledged it, the first invite (with a key connected) answers 409 first_share_ack_required. People shows a confirm first: they will see all N sessions and Crew memory (M items), counted from the session catalog and the global memory store; on a laptop host it adds that teammates lose access while the host sleeps. The acknowledgment is stored once per Crew.

Keep awake. host_power.detect_laptop reports a battery from /sys/class/power_supply (a Battery that is not a peripheral's Device scope), /usr/bin/pmset -g batt on macOS, or GetSystemPowerStatus on Windows; anything else is unknown, never a laptop. The gateway's prevent-sleep poll has a third reason, host_power.shared_use_wants_awake: a collaborator (a Tailscale person who is not the owner) has a dashboard socket open, or work charged to an invited person or anyone whois named on the direct listener is queued or running. The existing power.SleepInhibitor holds the host awake (caffeinate -i -w <gateway pid>, systemd-inhibit --what=idle:sleep, SetThreadExecutionState), each helper resolved from a fixed system path, and releases it when that stops. Nothing is installed.

Storage. <data_home>/.vault/shared-crew-tailscale/access.json (0600), beside the invite records, masked from every sandbox mode. A file that cannot be parsed leaves the set unreadable: the serve path admits only the owner, and the access card says so. A failed write drops the in-memory copy, so the next read is the file again.

Tailscale invites

The owner invites a teammate in one step: emails, or a link, with an optional alias and avatar. Crew calls Tailscale's device-invite API, and when the teammate accepts it learns their real Tailscale login and admits it. This replaces a separate member list and a hand-edited trust list (shared_crew.tailscale_invites, shared_crew.routes_invites).

Credential. A user-owned Tailscale API access key (tskey-api-...), made by an Owner, Admin or IT admin. An OAuth-client token cannot create or resend device invites (the share belongs to a user), so no OAuth path exists. The key is entered once through POST /api/shared-crew/tailscale/credential and stored in a dedicated SecretVault at <data_home>/.vault/shared-crew-tailscale/ (shared_crew.tailscale_invite_store); never in config.json, never logged, never in a response. The status read reports connected, the tailnet name, the key's expires (from GET /tailnet/-/keys/{keyId}) and key_expires_soon (within 7 days) or key_expired. DELETE .../credential removes it.

This machine's device. connect matches the local daemon's Self.PublicKey against devices[].nodeKey, then Self.TailscaleIPs against devices[].addresses, and keeps the nodeId. Never by name; no match refuses device_not_found.

API calls. Only to https://api.tailscale.com/api/v2, basic auth with the key, redirects refused (shared_crew.tailscale_api):

Call Use
POST /device/{id}/device-invites body a JSON array of {email?, multiUse, allowExitNode}; allowExitNode is always false, multiUse is false unless the owner turns on a reusable link (email invites are always single-use)
GET /device/{id}/device-invites read back each invite's accepted and acceptedBy {id, loginName, profilePicUrl}
POST /device-invites/{id}/resend Resend; Tailscale allows one per minute
DELETE /device-invites/{id} Revoke; a 404 counts as already gone

Accept. sync runs when the owner opens People (at most every 15 s) and from a gateway poller while any invite is pending (60 s, doubling on failure to 15 min, never sooner than a 429's Retry-After; a backed-off sync makes no call). Each newly accepted invite binds acceptedBy.id (the stable Tailscale user id) to loginName and the invite's alias and avatar, adds the login to dashboard.tailscale.allowed_logins with enabled and trust_identity on and the machine owner's own login kept (shared_crew.tailscale_allowlist), and grants it live (dashboard.tailnet_live_allowlist, read by tailnet.login_allowed), so no restart is needed once identity trust was already on; the first accept that turns it on reports restart_required. The accepting login is used even when it differs from the invited email: Tailscale lets an invite be accepted from any account. An invite made in the admin console that Tailscale reports accepted is admitted the same way. An unaccepted invite Tailscale no longer lists is dropped. Live access is granted only after the membership write is durable, so a revoke always finds the person. A reusable link stays due for a sync after its first accept, so each later person who accepts it is admitted.

Display only. Alias (printable, 64 characters) and avatar (PNG, JPEG, GIF or WebP by magic bytes, at most 256 KiB, named by digest, served same-origin with nosniff and a sandbox CSP) never decide access. The avatars folder holds at most MAX_AVATAR_FILES (512) files. A full folder first deletes pictures no invite, member or display record shows and that are over an hour old (a draft may still save a newer one), then refuses a new upload with avatar_limit. A replaced picture is never deleted at once. People rows whose provenance is a verified tailnet peer show the alias and avatar bound to that login; a session creator read back from stored attribution never borrows one.

Revoke. Delete the invite at Tailscale; for every person it admitted (each one who accepted a reusable link), take every login they came in under out of the set and the config mirror (never the machine owner's own), refuse them live and close their dashboard sockets (Who gets in). Revoking an accepted invite is assumed to end the share (Tailscale's sharing guide says so; the API schema does not); Crew's own refusal holds either way.

Owner gate. Every route but the avatar read requires a dashboard user, a non-restricted session, is_owner_dashboard_request, and a viewer who is the local operator, the owner proved by the direct listener's whois (auth_owner_whois), or this machine's own tailnet login, so an admitted teammate cannot invite or revoke. An upstream Tailscale failure answers 502 tailscale_<code> (429 tailscale_rate_limited with Retry-After), never 401.

Without a key. The card explains the manual step and links the admin console's Machines page; nothing else changes.

Audit. Every connect, create, resend, accept and revoke writes one SEL shared_crew.invite.<op> record with the actor, email_sha256:<16 hex> of the invited email (never the address) and the outcome.

Share link. While the direct tailnet listener is active, People (network mode) and the phone dialog show its plain URL in capabilities.tailnet_direct.urls order (tailnet_direct.direct_urls): the IPv4 tailnet address first, which needs no MagicDNS, then http://<magicdns-name>:<port>/, then the IPv6 address, with a copy button (TailnetDirectLink). The URL carries no token. The phone dialog keeps its token-carrying QR and sign-in link under an Advanced fold for devices without Tailscale. People adds the device-owner caveat under the list, and the macOS empty state (platform_unprovable) points at the direct link.

3. Session attribution and records

SessionAttribution is stored under the metadata-line key SESSION_ATTRIBUTION_META_KEY (attribution). It is not created_by, which already names the creating slot key. It is write-once: keep_creator returns the stored value whenever one exists, so a later message by someone else never changes the creator.

The slot holds it on _attribution (attribution.slot_attribution). attribution.stamp_creator records the creating actor where a session is created; stamp_creator_if_fresh records the sender of the first accepted user message of a slot no creation path stamped, and only when the slot holds no user turn yet. The metadata codec's attribution row writes it on both save forms and reads it back on every hydration purpose. No writer lists the key as owned, so a save that does not write it carries the stored value through history.carry_unowned_metadata, and the whole line is replaced atomically by the existing full save.

Missing human attribution is displayed as Unattributed on every surface (session list, filters, bylines, People, decisions and presence). Storage keeps the unknown principal kind and the p_unknown id; nothing is rewritten.

A session with no attribution key reads as legacy_missing. A persisted one was made before sharing existed, so it is the owner's: its public attribution's creator is the owner principal (owner.owner_principal, labelled with this machine's name) while availability stays legacy_missing. This is display only. A legacy session that names a trigger keeps the trigger and no person. Two legacy values stay Unattributed instead (attribution._owner_fallback_for_slot, _owner_fallback_for_meta): a live slot nobody has stamped yet, and a channel-origin session (a channel_origin flag, a live channel session key, its persisted filename-stem spelling, the pre-migration bare Slack thread_ts stem, or a linked_session_key in any of those shapes), which a teammate may have started on Slack or Discord. The session list's mine filter includes legacy sessions for the owner (under any of the owner's ids, owner.viewer_ids), unattributed excludes them, and People counts them to the owner. It stays legacy: the codec never writes a legacy value back, no stamp replaces it, and nothing back-fills it, least of all from the current viewer. Attribution was on but no principal could be established reads as unattributed. A damaged attribution object, or a torn metadata line, reads as legacy, because authorization never reads it and a damaged record may only lose its label. Keys inside the attribution object this build does not know are kept (extra) and written back.

The metadata line is a file an agent's own tools can write, like created_by. The creator is therefore a label for discovery, never an input to an access decision.

Browser-bound copies use attribution.public_attribution: availability, creation time and Principal.to_public_dict (id, kind, display; no issuer or subject). The slot payload (slot_projection) and every session catalog row (history_search.SessionCatalogProjection.list_sessions) carry it as attribution.

A message's author rides in the message meta under MESSAGE_AUTHOR_META_KEY (author), in the public principal shape, stamped by the server when it accepts the message (attribution.stamp_message_author). A client-supplied author key is discarded at ingress and overwritten at the stamp. Every other live user row an authorized request's handler appends (regenerate, rewind, task-runner hand-offs, the OpenAI shim) names that request's actor (attribution.with_request_author, bound by identity.publish_actor to the request's own task, so a turn the handler starts never inherits it). Channel rows name the bounded Unknown principal and automation rows the automation principal (stamp_principal_author). A message written before authors reads as Unknown (attribution.message_author).

Sender in the prompt. The agent is told who sent a message with one line before its text, [from: <display name> (<login>)] (attribution.sender_line, added in prompt_assembly._turn_build_prompt). It is added when the turn's user row is by a person other than this machine's owner (the local operator's subjects and the owner's tailnet login), or when more than one person has written in the session, in which case the owner's rows read [from: owner (<owner login>)]. It reads the server-stamped author already on the row; a merged queue row whose entries name different people names no one and gets no line. Brackets, parentheses and control characters are stripped from the label. Only the prompt carries it: the stored row, the transcript the UI shows, the channel mirror and the system prompt are unchanged.

Trigger attribution. A session a schedule, a webhook or the Crew started names that trigger instead of a person (trigger.trigger_of): created_by of cron:<job id> (stamped only for a transport-attested cron caller), a key in the cron or hook namespace in either separator spelling, or slot origin system. The public attribution then carries trigger {kind: scheduled | webhook | system, ref, name}, and never for a human creator. The UI reads Scheduled: <job name>, Webhook: <name> or Crew automation. The job name comes from the cron service's in-memory snapshot (wiring.cron_job_namer), so a label costs no I/O; without it the label omits the name. A trigger is a label derived from editable records and grants nothing.

External attribution output is suspended pending product reconciliation: no tool call, outbound post or other downstream system receives "Requested by " text. The human stays in Crew records; a downstream system sees only the Crew. test_no_external_requested_by_attribution_is_emitted pins it.

Session list query

session_query.query_sessions runs over the whole persisted catalog: machine transcripts are dropped, then the search (q, case-insensitive over title and key) and the creator filter, then the page is cut. Order is newest modified first with a key digest as the tiebreak. The cursor is a keyset position, so one walk never returns a row twice; a session modified during a walk moves to the top and appears on the next walk. total_matching counts every session passing the search and the filter. hidden_by_filter counts the sessions passing the search that the creator filter excluded. The list covers persisted sessions; a slot that has never been saved is not in it. The route answers only the dashboard user, and refuses an app token or an internal caller with 403, so it reaches no session the existing list does not.

The unattributed filter (the older unknown value is accepted and echoed as unattributed) lists sessions with no human creator and no named trigger; a persisted legacy session has the owner as creator, so it is never listed there (a channel-origin legacy session is). A triggered session lists under All with its trigger. mine widens through every principal id naming the viewer. An explicit creator id normally matches only that id; when it names any local owner principal folded into the People row, it matches every local owner principal id represented by that row. Filters change visibility only; every session stays reachable with All.

The browser shows All by default, Mine, each person seen and Unattributed, labels the verified viewer You, and remembers the choice per Crew in local storage keyed by the mode route's crew_id (kc.shared-crew.creator-filter.<crew id>). A personal Crew, one that cannot attribute, one with the preview off or one nobody else has joined hides the control and the bylines (useSharedCrewListView, SharedCrewBylineContext; see People and setup modes). A creator-filtered row matches its catalog key against the full local live-slot roster by normalized session identity, including slots outside the chat-only sidebar projection. A live crewmate conversation opens its owning surface through opensElsewhereOf; a live chat switches with the actual slot key and passes that key to the host. Only a catalog row with no live match goes through resumeFromHistory.

Audit

ActionRecord audits a consequential shared action: session create, message, approval, question answer, steer, cancel, retry, control actions and memory changes. It names the initiator, the responder where one exists, the runtime reference, the outcome and a causal link. It carries ids, never prompt text or credentials.

audit.record_action writes it to the existing tamper-evident security event log (kiro_crew.sel) as one shared_crew_action event: caller_identity is the initiator's principal id, operation is shared_crew.<action_type>, resources is the target, request_id the correlation id, and metadata holds the action ids and a reduced principal (id, kind, provenance, login). That log's HMAC chain, size rotation and age retention bound it; there is no second audit store.

Every record also carries, in ActionRecord.extra and the event metadata, workload_identity_ref, always unavailable in this build, so the human and the Crew workload are named separately. Work no person started (a system or Unknown initiator in a cron or hook session) adds trigger {kind, ref, name}; a human initiator never gets one. The causal join is the record's target (the work id for work actions), session_key, turn_id, causal_action_id and initiator id, and the initiator stays distinct from the work's owner (budget_key) when a collaborator acts on someone else's work.

The write is the log's fail-closed critical mode, off the event loop, bounded by AUDIT_TIMEOUT_SECONDS. record_action returns whether the record is confirmed. When it is not, the action still applies and its response says it was not audited (audited: false). A refused audit must not wedge a turn, and it must not be reported as recorded. An action whose own durable row already names its actor (a message row carries its author) is audited with schedule_action_audit, which does not make the caller wait and makes no audit claim in the response; a failed write is logged.

Audited sites, all through schedule_action_audit:

Action Site Initiator Responder Outcome
session_create chat_api.slot_create request actor accepted
message chat_api.chat_send request actor accepted
cancel routes_admission.api_work_cancel, target the work id request actor applied, or conflict on a stale or illegal revision
approval, question_answer DecisionRegistry.resolve (decisions.audit_decision_response), target the decision id the decision's initiator the verified responder applied for the winner, conflict for a different response that lost, including one that reaches the settled decision after its wait ended (DecisionRegistry.classify_late, from the question answer and approval routes); a replay of the winner and a response to nothing pending add no record
memory_change cron.api_lessons_create (memory_changes.announce_replacement), target lesson:<category> the lesson's writer applied; only for a write that replaced stored lessons
person_display routes_people.api_set_display, target person:<user_id> the person who made the change applied; display_change in extra and the event metadata: {user_id, login, old_name, new_name, avatar_changed}

Memory changes

Crew memory is fully shared. A lesson, correction or preference any admitted person teaches (the learn_add tool, the dashboard, the CLI) is written to the Crew's one store and applies to everyone, the owner included. The owner gets no priority. memory_changes (shared_crew/memory_changes.py) owns the three things around that write.

Writer. writer_principal derives who the write is attributed to, never from the request body: the verified actor of a person's own dashboard request; for an agent write (learn_add posts through the internal caller), the author of the latest user turn in the calling session (decisions.turn_initiator); else Unknown. A known writer is stored on the row as written_by {id, kind, name} in both lesson stores. A row without one (every lesson written before this) loads unchanged.

Newest wins. The lesson stores decide what conflicts. The vector store (V1) replaces an older lesson on topic overlap (shared keywords at least half the larger set) or cosine similarity above 0.85, whoever wrote either, since every route write is user_explicit. The JSONL store replaces a stored preference that overlaps a new explicit preference the same way. A member's private V2 store deletes only on an exact key. Two contradicting rules are never both kept, and the route reports what it replaced in superseded.

Everyone is told. When superseded is not empty, announce_replacement:

  1. Schedules one memory_change audit record: initiator the writer, target lesson:<category>, and in extra / the event metadata memory_change {category, old: [summary], new: summary}. Summaries are redacted (_redact_memory_field) and clipped to one line of SUMMARY_MAX (120) characters, at most OLD_MAX (5) old ones. No full lesson body, prompt text or secret.
  2. In a shared Crew only (crew_is_shared: the writer came over a network path, a sharing path is on, or anyone but the operator has been seen), appends a system notice to the session the write came from and sends a shared_crew.memory_change frame {type, schema_version, change} to the owner and every collaborator (broadcast_to_collaborators). The notice is an assistant row with meta.kind = "memory_change" (a SYSTEM_NOTICE_KINDS member on both sides) and meta.memory_change = the change payload {actor: {id, kind, name}, session_key, category, new, old}. Its text is English ("Bob changed a Crew preference: ..."); the dashboard renders the localized sharedCrew.memory_change_* line from the payload.

A personal Crew has one person: the newer lesson still replaces the older one and the audit record is still written, but no "changed by" notice or frame is sent. A notice or audit failure never fails the write.

4. Admission and accepted work

Operation state machine

admission.TRANSITIONS is the one state machine every entry point reports through.

submitted -> queued | admitted | rejected
queued -> admitted | cancelled | expired | reconciling
admitted -> running | queued | cancelled | expired | reconciling | failed
running -> cancelling | completed | failed | reconciling
cancelling -> cancelled | completed | failed | reconciling
reconciling -> queued | running | completed | failed | cancelled | unknown_outcome

submitted exists only in the client. rejected is reachable only from it, and AcceptedWork refuses both: a rejected request was never accepted. admitted -> queued is a start-time revalidation that found capacity gone; admitted -> cancelled is one that found the grant or policy revoked, so a queue record is never standing permission. reconciling -> queued requires proof the work never started. Ambiguous execution after a crash ends in unknown_outcome and is surfaced, never replayed.

TASKQ_STATE_MAP maps every kiro_crew.taskq.model state onto this machine; the durable queue stays the store of record and this is its projection.

Capacity accounting

Work counts against active capacity in CAPACITY_HOLDING and against queue depth while queued. AdmissionService._maybe_release returns capacity only for terminal work whose runtime is proven stopped and whose children have all settled. Restart, disconnect or lease expiry therefore never frees a slot while a child lives.

RuntimeOwnershipRef points into the existing ownership registry (runtime_ownership lease, RuntimeTenancy epoch, taskq generation, systemd scope unit). It is not a second registry. Its liveness is what the reconciler proved, never what a client reported.

Requests and idempotency

AdmissionRequest.budget_key is the initiator's principal id. It is never the session creator and never a per-device token, so tabs, devices, reconnects and child tasks of one person share one budget. Work in a shared session is charged to whoever started it.

The client sends an Idempotency-Key header per logical send and reuses it on retry. The deduplication scope is idempotency_scope(budget_key, session_key, key), retained for IDEMPOTENCY_TTL_SECONDS. A replay with the same request_digest returns the existing AcceptedWork; a different digest is idempotency_conflict. A retry never runs a prompt twice.

A chat send asks admission_entry.chat_replay before it writes anything, so a retry under a key already accepted, whether the first send started a turn, queued behind a busy session or already finished, answers JSON with replayed: true, the recorded admission and, for a queued message, its queue_id. It appends no row, queues nothing, starts no turn and opens no stream. Only a client-supplied key can match; every chat path records the same digest (admission_entry.chat_digest), so a retry matches whichever path the first send took. A replayed Admission handle closes its coroutine unrun.

Responses

A lost send race is settled before admission and is not an admission refusal: it answers 409 send_race with the winner (section 5, First submit wins) and creates no AcceptedWork. The race-versus-queue boundary is open; the POC settles races by revision compare-and-set and leaves capacity to admission.

A refusal or conflict answers admission.error_body: the dashboard's {"error", "code"} envelope, plus capacity on a limit and current (the public AcceptedWork) on a conflict, so a stale UI action reconciles against server truth. The status comes from REASON_HTTP_STATUS, and a refusal with a retry hint sends Retry-After (retry_after_header). CapacityResponse reports both scopes' limits and usage and the effective EnforcementLevel. It has no wait-time field, because the scheduler cannot back one.

Fairness

Owner: shared_crew.scheduler (pure; one lock, so a race at the limit admits exactly as many as there are slots) behind shared_crew.admission_gate.AdmissionService.

Two work classes. A ROOT (chat turn, task run, workflow run, cron run) is admitted while its principal holds fewer than principal_active and the Crew fewer than crew_active root slots; otherwise it waits in its principal's FIFO, bounded by principal_queue and crew_queue, and a submission past either is refused principal_queue_full / crew_queue_full. A CHILD (subagent) never queues here: the durable task queue is its queue, so the gate bounds what a principal and the Crew have outstanding (principal_children, crew_children) and refuses past it. Background runs (task runner, workflows) cannot wait in a request, so they start now or are refused with the active-limit reason.

A message sent to a session whose turn is running (or held behind its running subagents) waits for that turn, not for capacity. It is accepted as parked work (admit(park=True), FairScheduler.park): durably queued, charged to its sender, bounded by principal_queue and crew_queue and max_request_bytes like any root, and counted in queued capacity, but never dispatched. The queue entry carries its work id (admission_entry.QUEUED_WORK_META_KEY); the session's drain runs the turn as that work (turn_gate.queued_work, AdmissionService.start_parked), which takes its place in the fair queue then. Messages a drain merges into one turn end with that turn's outcome (extra.merged_into). A parked message's expiry is a check-in: while its queue card exists it waits on; once the card is gone it ends cancelled (queue_entry_gone). A card cancelled through the work API, or whose sender was removed, does not run.

Capacity lives in memory (the scheduler and the live table); the store is the durable record. When any admission write fails (promotion, the pre-start running write, settle, cancel, expiry, attach; the task store is locked past its timeout), AdmissionService._fail_closed ends the work in memory at once: it stops the child (_stop_child), wakes every waiter and logs a warning. The work keeps its slot and stays tracked with its last durable record (_Live.unpersisted); every ticker pass retries the terminal write (admission_settle.persist_pending) and frees the slot only once the store records it, so capacity is never released ahead of the durable transition. A merged queued message whose settlement write fails is kept the same way. A deadline whose cancelling write fails still stops the child. A caller cancelled before its work starts (a queued chat closed while it waits) ends that work cancelled (admission_parked.end_unstarted); any other error before the start fails it closed, so its ticket holds a slot only until its terminal write lands.

A background run admitted now can be cancelled while its start is still in flight. _end remembers the ended, not-yet-attached work with its operation's cancel hook, and attach_child then finds no live record and stops the new execution through that hook, so cancelled work never keeps running outside admission.

A task run is registered and persisted by the task runner before attach_child, and the task runner resumes a run it finds running after a gateway stop. So the task runner's entry points (/api/taskrunner start, retry and execute) first write the run id as extra.execution_id on the still-admitted record (admission_run_link.link_run); start chooses that id itself (mint_task_id) and hands it to start_background(task_id=...). If the record cannot take the id, the run is refused and nothing starts. The gateway installs the task runner's probe before reconciliation (HostHooks.run_probes), so a restart holds such a record until the probe settles it. The probe answers a planned or paused run with no live start as cancelled (it holds no runtime). A start in flight (_start_ids_in_flight), a live run task, and a run the restart recovered as paused or planned whose resume the task queue's adoption sweep has not decided yet (TaskRunner._recovery_pending) all answer "still running". The wait ends (end_recovery_wait) when the sweep finishes or fails, when the queue is detached, and at boot past the store-ready pass when no sweep was armed.

A child spawn's subagent row becomes dispatchable inside the spawn call, before attach_child. So every child spawn path (/api/spawn, /api/spawn/{id}/continue, the retry, an app's background spawn) first mints the run id, writes it as extra.execution_id on the still-admitted record and binds the run key subagent:<id> to the admitted budget (admission_link.link_spawn, which writes the id through admission_run_link.link); the spawn then runs under that id (_preassigned_id). A start the subagent queue releases later (a queue drain, an approval, a parentless spawn) reads that binding, so it lands in the admitted person's slice. If the record cannot take the id, the spawn is refused and nothing starts.

Across principals the scheduler is deficit round robin. Principals with queued roots sit in a ring; a visit adds the quantum (1) to the principal's deficit and admits while the deficit covers the head ticket's weight (1) and both scopes have room. A principal blocked by its own limit is skipped with its deficit reset, so no credit is banked while ineligible. Within one principal the queue is FIFO, so order within a session is kept. The subagent pump's existing lane round-robin becomes per person too: taskq.lanes.set_lane_resolver maps a root session to principal:<id> while admission is on.

Starvation bound: with P principals holding eligible queued work, a continuously eligible principal is admitted within (P - 1) * (quantum + max_weight - 1) admissions of others, which is P - 1 with the defaults. Every admitted root ends within its run deadline, so the wall-clock wait is at most ceil(P / crew_active) root deadlines; work that would wait past queue_expiry expires queue_expired, reported, never hidden.

Who is charged. The initiator, read from request[ACTOR_REQUEST_KEY] (admission_gate.actor_budget); never the session creator. Every caller without a principal is p_unknown, one shared bucket. A child inherits the budget and root of the work running in its parent session (budget_for_session), so a collaborator steering or spawning inside someone else's turn charges that turn's initiator. Cron and loopback automation with no recorded initiator charge Principal.system("automation"), which has the same limits as anyone. Work an agent starts from inside a turn reaches the gateway on the internal transport naming its calling session (X-Session-Key, set by the in-process MCP broker). The header alone is the caller's word, so the session counts only once proven (admission_gate.attest_internal_session): the auth layer kernel-attested the declared key (peer_verified), or a per-session token the gateway signed (X-Session-Token, session_token_sig) names it. The work is charged to the principal admission bound to that session server-side (internal_initiator, budget_for_session). An internal request whose session is unproven or holds no work is charged to the bounded Unknown bucket, never to automation, so a person cannot gain a second budget through automation.

Native Slack's capacity entry uses its dispatcher's _is_control_message predicate, so bang commands such as !yolo off and modifier-only messages reach their existing sender and channel-policy checks without waiting for model capacity. Mention and privacy-token parsing are shared with dispatch; a privacy modifier with a remaining prompt still faces admission. Model messages re-enter the full handler after admission, preserving its start-time checks. Telegram and ChannelTurns callers dispatch commands before entering their turn gates.

A turn started from another turn's end (the chat queue drain, a Side Chat follow-up, a channel wake or held retry) starts outside its predecessor's admission (turn_gate.independent_turn) and is admitted on its own; work nested inside a turn stays in that turn's admission.

Accepted work, revalidation and recovery

shared_crew.work_store keeps each AcceptedWork as one accepted_work row in tasks.db (taskq.store_work, created by taskq.migrate; additive, so the schema version stays and an older build leaves the table in place). The row is committed before the caller hears admitted or queued. Idempotency is the unique scope column; a replay returns the stored record and a replayed handle never runs twice. Terminal rows are purged after IDEMPOTENCY_TTL_SECONDS.

Admission.run waits for a slot, then revalidates right before starting: queue expiry, policy_version (a change to admission_enabled, hard_limits or containment_enabled since acceptance is policy_changed), the hard-limit probe, and the entry point's own check (a chat slot must still be live). running is written before the work launches, so admitted proves it never started, unless it names a run id: a child's, or one an operation's probe can find. A queued chat turn holds the slot reservation; while it waits a later send on that slot cannot steer into it (admission_entry.admission_pending) and queues instead, so a queued prompt is never delivered as a steer.

Disabling admission affects new submissions immediately. Maintenance keeps running until accepted live work settles: queued work (including parked messages) ends cancelled with policy_changed, waking its waiters without running its coroutine; attached executions keep their reservations until their owner reports them terminal. Messages merged into a running turn keep that turn's outcome. The ticker stops once disabled admission has no live work left.

The gateway's own stop (a signal or an in-app restart, read through host_hooks.shutdown_probe) never records completed for work it cut: a running turn that returns once the stop began ends cancelled with extra.reconcile_detail = host_stopped_while_running, and admitted or queued work that would start then ends cancelled with host_stopped_before_start, unrun.

Deadlines: root_deadline_seconds for roots, child_deadline_seconds for children and background runs, enforced by AdmissionService.tick (once a second): it cancels the work and records cancelled with run_deadline. A root's slot is released only after its own task ended and every child it started settled; a child's slot only after its owner (subagent manager, task runner, workflow registry) reports it terminal.

Both server entry points (the dashboard and the API-only server) register the same startup lifecycle. Before the socket binds, startup_check runs only the bounded containment probe and publishes the hard-mode refusal; reconciliation and the stale slice sweep run as a maintenance task after the socket is ready, and the shutdown cancels it. Before the first admission or capacity read of a process, ensure_ready reconciles every non-terminal row. The gateway also awaits it before it opens the durable subagent queue (admission_link.release_after_reconcile), so a recovered child's run key is bound again before its dispatch can start. It opens only once every surviving linked child is held and bound: a child whose reconcile raised (ensure_ready logs it and still marks itself ready) is reconciled again first, and under hard limits each such child's slice must be applied, as a live admission requires. Until then the queue stays held and the check retries every DISPATCH_RETRY_SECONDS (30 s); with admission off the queue opens at once:

Found Becomes Capacity
queued, admitted (no linked run id) reconciling, then queued and relaunched when a relauncher is registered for its operation and payload, else cancelled with extra.reconcile_detail = host_restarted_before_start held only if requeued
running, cancelling with no unit of its own reconciling -> unknown_outcome (cancelled if a cancel was asked) released once proven stopped
running with a live scope unit, or a principal slice holding a populated kirocrew-rt-*.scope reconciling; the scopes found are stopped (extra.orphans_reaped), and the row ends unknown_outcome once systemctl is-active says each stopped held
child or probed background run, including a queued or admitted one that names its run id reconciling; its owner reconciles the run and the probe settles the row; a child's run key subagent:<id> is bound to its budget again and its slice prepared, so a recovered dispatch lands in that person's slice held

Nothing that may have run is replayed. No relauncher is registered for chat turns in this build, so a chat turn queued across a restart ends cancelled, and the session says so in an error row (host_hooks.reconcile_note, also for unknown_outcome). A parked message is the exception: its queue entry is saved with the session and drains again after the restart. A session that has never been saved gets its metadata line before its first work is accepted (host_hooks.ensure_slot_recorded), so a crash right after the accept cannot leave a work record for a session that is gone. A false persistence result refuses the chat send before admission; child cancellation uses the manager's off-loop queued stop under its refill hold, and a finished user_stopped child settles as cancelled rather than completed.

A chat turn's work carries its accepted prompt and author as its payload (admission_entry.CHAT_PROMPT_PAYLOAD_KEY, CHAT_AUTHOR_PAYLOAD_KEY) until it ends; reconciliation reads it before the terminal write clears it and hands it to the note. Notes wait until the startup restore has built its slots (host_hooks.mark_sessions_restored). A session no slot holds is opened from disk, so a session the crash left without an open-tab record can be opened; when it never saved the accepted prompt, the prompt is put back as its user row ahead of the note. The prompt is only shown, never run again.

Containment

Owner: shared_crew.containment, reusing sandbox_cgroup and sandbox_slice. Each principal's runtimes start in kirocrew-agents-<instance>-p<sha256(id)[:12]>.slice, a child of the instance slice, sized by systemctl --user set-property --runtime (principal_cpu_quota_percent, principal_memory_max_mb, principal_tasks_max); the instance slice gets crew_cpu_quota_percent. sandbox_slice.cgroup_scope_argv picks the principal slice from the principal_scope context the gate sets around admitted work and around subagent run tasks. A principal slice nothing of its principal has used for SLICE_IDLE_SECONDS (600) is stopped and its runtime drop-ins removed (systemctl --user stop then revert), only while no runtime scope in it holds a process; the gateway's stop releases every one at once, including the slice of a turn the stop interrupted, repeating the sweep a bounded number of times (SHUTDOWN_SWEEP_ROUNDS) while a runtime scope it ended still empties, then the instance slice once its own control group is empty (release_instance_slice). The gateway's hard-exit path runs the same release after it reaps orphaned sessions, so a graceful shutdown that ran out of time does not skip it. Its start releases those an earlier process left (AdmissionService.sweep_slices, shutdown_cleanup, release_stale_slices). The slice is forgotten before it is stopped, so a spawn racing the release lands in the instance slice. A shared session's runtime is one process, so it stays in the slice of the initiator whose turn started it; later turns by others are bounded by admission counts, not that slice.

The guarantee is best_effort and is reported that way: the kernel enforces the CPU, memory and pids ceilings for cooperative or buggy work, but every runtime runs as the gateway's uid, which can reach the user bus and the delegated subtree, so adversarial escape is not closed (adversarial_escape_closed: false). IO is not delegated on the supported profile and is unavailable. Disk is app_accounting: shared_crew.accounting charges accepted request bytes per principal to the durable principal_storage ledger and refuses past principal_storage_bytes with storage_limit; it is not a filesystem quota.

hard_limits turns any missing prerequisite (not_linux, systemd_run_untrusted, systemctl_untrusted, no_user_session, user_bus_unreachable, not_cgroup_v2, controllers_not_delegated, controllers_unreadable, or containment_probe_failed when the probe or the startup check raised) into containment_unavailable (503) at admission. In hard mode slices must be enabled and both the Crew slice and the principal slice must apply; an accepted turn whose slice setup fails settles without running instead of starting in the instance slice. In either mode, an unreadable or malformed config.json keeps the limits already in force, and a process with no valid limits yet fails closed. With a prerequisite missing, runtime_start refuses every runtime spawn and session/new with ContainmentUnavailable (the backstop for entry points that do not reach the gate). With it off the gate admits and the capacity answer says what holds. hard_limits needs fair admission, which applies the limits: with admission_enabled off and hard_limits on, nothing would apply them, so the gateway fails closed with admission_disabled (every admission and every runtime start refused, logged at ERROR at start) rather than running unlimited.

Defaults and API

dashboard.shared_crew (config.sections_shared_crew), bounded at parse (shared_crew_config_from) and resolved by effective_limits:

key default meaning
admission_enabled false fair admission; off is the single-operator default
principal_concurrency 4 root executions one person runs at once (1 to 256)
crew_concurrency 0 root executions Crew-wide; 0 is the session start gate's automatic width (0 to 1024)
containment_enabled true per-person slices, applied only while admission is on
hard_limits false refuse work when the slices cannot be enforced
tailnet_direct false also listen on this machine's Tailscale addresses; only a literal true turns it on
typing_idle_seconds 10 idle seconds before another person's composer unlocks (3 to 60)

An out-of-range integer is clamped and a wrong-typed value reads as its default, so an edit can narrow or widen a limit but never remove one. The other limits are module constants in config.sections_shared_crew: 8 subagents per person (twice the Crew width Crew-wide), queue depth 16 per person and 64 Crew-wide, queue expiry 300 s, deadlines 1800 s (root) and 600 s (child), 4 MiB per request, 30 session creates per minute, 2048 MB accounted storage per person, and slice limits of 800% CPU, 24576 MB memory and 8192 tasks per person and 2400% CPU Crew-wide. These are proof-of-concept test targets measured on one host, not product commitments.

5. Collaboration

Presence (collab.PresenceEntry) is telemetry. It is bound to the connection's verified actor, folds every tab of one principal into one entry, expires after PRESENCE_TTL_SECONDS without a refresh, is rate-limited to one activity frame per ACTIVITY_MIN_INTERVAL_SECONDS per connection (the one step down from a reported typing in the same session is exempt and goes at once, so a send ends typing for everyone), and is never persisted. It never grants access or frees a slot. Draft text is never sent.

presence.PresenceRegistry implements it in memory. dashboard.ws reads the connection's principal once, from request[ACTOR_REQUEST_KEY] on the upgrade request (Unknown when none was published), and hands each shared_crew.activity frame to presence.handle_activity_frame, which reads only session_key and activity, admits dashboard-user sockets only, and only for a session the gateway has open. A refused frame (too soon, malformed, registry full) changes nothing and is never answered with an eviction of someone else's entry. Disconnect and expiry push a fresh shared_crew.presence frame for every session they changed; the socket's status tick sweeps stale entries.

In the browser, typing is reported from the composer's user-edit handler (typingSignal.useComposerEditWithTyping, which ChatInput calls only for the user's own edits), not from the draft store: the store keeps one identity and a session switch writes it too. The collab strip's usePresenceReporter listens to that content-free signal and sends typing, then viewing after TYPING_HOLD_MS without a keystroke.

A shared decision (collab.SharedDecision) is a tool approval or agent question that every collaborator sees and any one may answer. classify_response decides a response under the resolver's lock: the first response to see pending wins, a retry with the winning response_id replays the same outcome, and any other response receives the resolved decision with already_resolved. A resolved decision always names its responder.

decisions.DecisionRegistry is that resolver: one in-memory, bounded record per decision, with the classification, the side effect that settles the waiting future, and the state write under one lock. A decision id is derived from what the card already shows (approval:<len>:<slot>:<request id>, approval-state:<id>, question:<ask id>), so every tab computes it without a lookup. A decision opens the moment its card shows: a slot permission prompt in chat_runner (unless it was declined at its append), a background approval in ApprovalCoordinator.request, and a blocking or agent question in QuestionCoordinator. The initiator is the author of the turn that asked (the latest user message's author stamp) or, for a background approval, the Principal.system of its source; the responder is the request's verified actor. Every existing gate on the approve and answer routes runs before the registry sees a response. A client that sends response_id gets 409 already_resolved with the decision on a lost race; a client that sends none keeps the existing 404. A wait that ends through a path with no verified responder closes the decision with an Unknown responder and settled_by: "host", and an unanswered one closes as expired or withdrawn. settled_by (person or host) is on every decision: host when settle_after_wait resolved it (an approval mode such as trust or YOLO, the no-request-id path, a channel resolver) or the responder is not a verified human (an app token), person otherwise, an owner's dashboard click included. A record without the field reads as person. Approval decision frames ride broadcast_ws like approval frames.

An agent question belongs to every collaborator. collaborators.is_collaborator_request admits the owner (is_owner_dashboard_request) and a dashboard-user session whose verified actor is a person a membership boundary admitted: provenance tailscale_serve (allowlisted and pinned by the middleware), tailscale_listener (admitted by the direct tailnet listener's whois). A tailscale_direct peer (attribution only, on a widened bind), a Slack-allowlist dashboard token, an app token, an internal caller and Unknown are not collaborators and keep the owner gate's 403. GET /api/ask-question/pending, POST /api/ask-question/{id}/answer and POST /api/ask-question/dismiss accept every collaborator; opening a question (POST /api/ask-question) stays owner-only. The card frames (question_card, question_card_resolved) and the question decision frame go to the owner sockets and to every collaborator socket (collaborators.broadcast_to_collaborators, which reads the socket's _shared_crew_actor), the same audience the pending read has. Nothing else the owner set receives reaches a collaborator socket. GET /api/shared-crew/presence and GET /api/shared-crew/decisions (in routes_collab) answer the same state for a reconnecting tab.

Message attribution. The session's creator is its default owner, shown on the session row in the list (SessionCreatorByline). In the transcript a user message the viewer wrote carries no extra label; a message anyone else wrote, the session's creator included, carries the sender's name (MessageByline, sharedCrewUi.bylineFor), so a right-aligned message without a name is always the reader's own. Until the viewer read lands, the session's recorded creator stands in for the viewer (sharedCrewUi.bylineSelfId); with neither known nothing is labelled. A single-operator transcript is unchanged, and a personal Crew, one with the preview off or one nobody else has joined shows no bylines at all. An Unknown author reads as Unknown.

Typing lease

Product owner's decision (2026-10-18), replacing the earlier "no input lock" non-goal: while one collaborator types in a shared session, every other collaborator's composer is read-only, the way a shared document shows who is editing a line. Owner: shared_crew.typing_lease.

Rules:

  1. One lease per session (keyed by slot), held by one person: the verified connection principal the socket handler stamps, never a value from a frame. A person's tabs fold into one holder (typing_lease.same_person: the same principal id, or the local operator's machine-local subjects from crew_mode.operator_ids), so their other tabs stay unlocked.
  2. The first collaborator whose tab sends an accepted typing report with a non-empty draft acquires a free lease. Each later accepted typing report from the holder renews it. A typing report never takes a held lease away. Unknown and system principals never hold one.
  3. The lease ends when the holder's send is accepted (send_race.commit_request calls note_sent), when a holder tab reports its draft empty ("draft": "empty"), when no holder tab has reported typing for the idle window, or when every holder tab that was typing closes its socket (tab close or disconnect). A plain step down to viewing (the tab's typing hold ran out) keeps it: the draft is still there and the idle window decides.
  4. The idle window is dashboard.shared_crew.typing_idle_seconds, default 10, clamped to 3..60 (SHARED_CREW_BOUNDS). typing_lease_for reads it once, when it builds the registry, so the field is marked restart-required and the People Advanced row shows the restart badge. A timer armed on the event loop at the earliest lease's idle end (arm_idle_timer) ends it on time; the socket status tick's presence sweep also sweeps leases.
  5. The host enforces it. chat_send._composer_locked_answer runs before the send race: a dashboard user's send while someone else holds the lease answers 409 {"error", "code": "composer_locked", session_key, holder (public), lease} and nothing is accepted. A steer into a running turn passes, and Stop is a separate route, so a locked collaborator can still steer or stop the turn that is running. An app or automation send has no composer and is not held. First-submit-wins (below) stays the backstop for the moment a lease ends.
  6. A personal Crew never locks: the only person is the operator, who is always the holder's own person. The session creator has no priority; there are no roles.

The lease rides the presence channel and its rate limit: a typing report renews only when PresenceRegistry accepted it, and an empty-draft report only releases, so it applies even inside the spacing. Every change (acquired, ended) pushes one whole-value shared_crew.typing_lease frame to every dashboard socket; GET /api/shared-crew/typing-lease?session_key= answers the same body for a reconnecting tab: {schema_version, session_key, holder (public) | null, holder_ids, expires_at, idle_seconds, ended}. holder_ids lists every id that counts as the holder, so a tab tells its own lease from someone else's without a second read; ended names why a lease just ended (sent, cleared, idle, disconnected, taken_over). Nothing is persisted: no draft text and no keystroke, only who holds the lease, which of their connections are drafting, and when each last reported.

Takeover requires KIROCREW_SHARED_CREW_PREVIEW=1; without it the route is absent (404) and no frame carries a takeover field. A locked collaborator may take the lease over with POST /api/shared-crew/typing-lease/takeover {session_key}: a dashboard user (the same check as the lease read) whose actor can hold a lease (can_hold), in a session the gateway has open. TypingLeaseRegistry.take_over gives the taker the lease as if they had just typed: a fresh idle window from that moment, held by a drafting entry takeover:<principal id> until one of the taker's own tabs reports typing, which then stands for them (clearing that draft ends the lease as usual). The previous holder's drafting connections stop counting, so their later typing reports leave the lease alone. A free lease, or one the caller already holds, changes nothing and answers the current state. The frame that announces a takeover is the normal whole-value body with ended: "taken_over", taken_over_from (the previous holder, public) and taken_over_from_ids (every id that counts as them); the route answers the same body. No other frame and no lease read carries those two fields. The draft is never read, sent or cleared, on either side.

In the browser (usePresenceReporter), a keystroke repeats typing once per spacing while keystrokes continue, so a trailing report lands after the last one; an edit that leaves the draft empty, and a send, report draft: 'empty' at once. useComposerTypingLock reads the lease and the viewer; when someone else holds it, ChatInput's typingLock turns the box read-only (not disabled: the draft stays as it was, and so does focus), replaces the button row with TypingLockBanner (initials and " is typing…"), and keeps only Stop and Steer for a running turn. When the lease ends the box unlocks in place. A send refused composer_locked restores the draft and records the refusal (api/typingLease.noteComposerLocked), which starts a fresh lease read; the lock shown is always the server's latest answer, never the refusal's copy. With the preview on (sharedCrewPreviewOn), the banner also has Take over; pressing it posts the takeover and then re-reads the lease, so the taker's box unlocks on the server's answer. The takeover reply is never cached itself: a newer lease frame can arrive before it and must win. A failed takeover shows an inline ErrorNotice with the agent hand-off under the banner. A tab whose viewer is in the frame's taken_over_from_ids shows " took over typing" in the banner instead of " is typing…"; its box locks like any viewer's and its draft stays.

First submit wins

POC choice, not an approved product contract: revision-based compare-and-set (shared_crew.send_race). With the typing lease in place it settles the sends the lease does not hold: a send at the moment a lease ends, an app or automation send, and a steer into a running turn. The boundary between a refused race and accepted work waiting for capacity stays open; this is the shape the POC ships to exercise it.

Each session (keyed by slot) has a send revision, the count of accepted sends. GET /api/shared-crew/send-state?session_key= answers {schema_version, session_key, revision, last} and every accepted send pushes the same body as a shared_crew.send_state frame. A send carries the revision its tab last saw as base_revision and a per-send Idempotency-Key. A send's base is the revision its tab knew at the press, for a steer into a running turn too, so a frame that lands after the press never raises it. A tab reads the send state for every open session whatever the capabilities, and a send whose revision was unknown at the press joins that read (ensureSendRevision, up to 1.5 s), then goes without a base. A session the send itself creates starts at revision 0. A frame or a read only raises the tab's revision; a send_race conflict answer replaces it with the host's current_revision, even when lower, so a tab open across a host restart (the host counts from zero again) recovers on its first conflict and Send now goes at the host's revision.

chat_send settles the race (_settle_send_race) after the empty-message guard and before the responsive, steer, busy-queue, sub-agent-hold and new-turn branches, so a losing send reaches none of them. SendRaceRegistry.claim decides, in order:

  1. while another claim on the session is pending, wait for it to settle (bounded by SETTLE_WAIT_SECONDS; past it the pending sender wins);
  2. a key this principal already won with is a replay: the admission replay answers when it has one, else {ok, replayed, send_revision, message_id}; nothing is accepted again, so a retry after a lost winner response never runs twice;
  3. no base_revision (app token, script, old client): not compared;
  4. a session with no accepted send since process start accepts any base, and its next revision continues above that base;
  5. otherwise the earliest send accepted after the base by a DIFFERENT principal makes this send lose. One person's own tabs never race each other, so a single-operator session behaves as before.

A granted claim is pending until the branch that records the send commits it (the user row, the queue entry, the steer or the responsive accept); api_chat releases an uncommitted claim in a finally, so a send refused for capacity, a closed session or any other reason never makes a collaborator lose to nothing. Commit bumps the revision by one and records {revision, principal, message_id, accepted_at}. message_id is the user row's mid, else the queue id, else the client sendId.

A loser answers 409 {"error", "code": "send_race", session_key, current_revision, winner: {revision, principal (public), message_id, accepted_at}}. Nothing was accepted: no row, no queue entry, no steer, no turn.

The browser restores a refused send_race or composer_locked draft to its session's draft store. StableChatInput subscribes to that store and passes the text as a value prop across the memoized editor boundary, so recovery redraws the textarea even when its other props stay unchanged.

Send now is a new send with send_now: true and base_revision set to the conflict's current_revision. send_now forces steer off, so it goes through normal fair admission and may queue behind the running turn or a capacity limit; it can lose again if yet another send landed first.

Everything is in memory and bounded (MAX_SESSIONS, HISTORY_PER_SESSION). A tab that never learned a revision sends none and is not compared.

6. Wire shapes

HTTP

Route Answer
GET /api/shared-crew/capabilities Capabilities
GET /api/auth/me gains principal (Principal.to_public_dict)
GET /api/shared-crew/sessions?creator=&q=&cursor=&limit= SessionPage; each item carries attribution
GET /api/shared-crew/people observed collaborators with usage (is_owner per row, tailscale_share rows), and the directory state
GET / PUT /api/shared-crew/preview {enabled} owner only, registered with the preview off: {enabled, active, env_override, restart_required} (Release gate)
GET /api/shared-crew/capacity CapacityResponse for the viewer
GET /api/shared-crew/work?session_key= public AcceptedWork list
POST /api/shared-crew/work/{work_id}/cancel {expected_revision} the next AcceptedWork, or 409 with current; a planned task or schedule run is owner only (403 owner_only), as on its own cancel route
a chat send 200 when admitted, 202 with work when queued, 429 / 413 / 503 with error_body
an approval or answer, with response_id the SharedDecision; 409 already_resolved with it on a lost race
GET /api/shared-crew/presence?session_key= the session's PresenceEntry list (dashboard users only)
GET /api/shared-crew/decisions?session_key= the session's SharedDecision list (dashboard users only)
GET /api/shared-crew/send-state?session_key= the session's send revision and last accepted send (dashboard users only)
a chat send with base_revision 409 send_race with winner and current_revision when another principal's send was accepted after it
GET /api/shared-crew/typing-lease?session_key= who holds the session's typing lease (dashboard users only)
POST /api/shared-crew/typing-lease/takeover {session_key} requires KIROCREW_SHARED_CREW_PREVIEW=1 (else 404): the caller takes the lease; the new lease body, with ended: "taken_over", taken_over_from and taken_over_from_ids when it moved; 403 forbidden (not a dashboard user) or not_admitted (actor cannot hold a lease), 400 invalid_session_key, 404 unknown_session
a chat send while someone else types 409 composer_locked with holder and lease; a steer into a running turn is not held
GET /api/shared-crew/tailscale/invites owner: connected, tailnet, key expiry, invites, members, sync (§2 Tailscale invites)
POST /api/shared-crew/tailscale/invites {emails, multi_use, alias, avatar_id} owner: the created invites
POST /api/shared-crew/tailscale/invites/{id}/resend owner: {resent: true}
DELETE /api/shared-crew/tailscale/invites/{id} owner: {revoked, member_removed, closed_connections}
POST / DELETE /api/shared-crew/tailscale/credential owner: connect {key} or remove the key; the status body, never the key
POST /api/shared-crew/tailscale/avatars {data_base64} owner: {avatar_id}
GET /api/shared-crew/tailscale/avatars/{avatar_id} any dashboard user: the image
PUT /api/shared-crew/people/{user_id}/display {alias, avatar_data_base64?, clear_avatar?} a person the direct listener admitted, or the owner (no app token, no restricted session, no non-owner dashboard link session): {user_id, alias, avatar_id, audited}; 404 unknown_person for a user id this Crew has no login for; avatar refusals as for invites (avatar_type, avatar_too_large, avatar_limit)

Browser-bound principals use to_public_dict (no issuer or subject); browser-bound work uses AcceptedWork.to_public_dict (no idempotency scope, lease or fencing ids).

Session list filter

SessionQuery.from_query parses creator (all, mine, unattributed, its older spelling unknown, or a principal id), q, an opaque cursor and limit (clamped to SESSION_PAGE_MAX). The filter runs on the server before pagination. mine resolves against the authenticated viewer, and never matches for an Unknown viewer. The filter is discovery, not access control. SessionPage.total_matching counts every session the filter passes across all pages; hidden_by_filter counts the sessions it excluded.

WebSocket

The server pushes whole-value frames: shared_crew.presence, shared_crew.work, shared_crew.decision, shared_crew.capacity, shared_crew.send_state, shared_crew.typing_lease, shared_crew.memory_change and shared_crew.people ({type, user_id}: someone changed a person's display name or picture, and People refetches) (collab.SERVER_FRAMES). With KIROCREW_SHARED_CREW_PREVIEW=1, the shared_crew.typing_lease frame announcing a takeover adds taken_over_from and taken_over_from_ids beside ended: "taken_over". The client sends shared_crew.activity with a session, an Activity and, when the tab's draft is empty, draft: "empty". The activity frame carries no principal and no text; the server stamps the connection's actor and ignores anything else. On reconnect the client refetches the HTTP state and treats the next frames as authoritative. Send-state snapshots are not cancelled by send-state frames: a send already waiting on the snapshot keeps its original revision, while revision-aware structural sharing retains the newest value in the query cache. Presence and work frames invalidate People, and sidebar slot, history and catalog changes invalidate People and every creator-filter page, including inactive cached queries. The client never resubmits a send on its own.

7. UI states

The sharing surfaces require the Feature preview on the gateway (the variable or the owner's stored choice): the Settings > People tab (with its invite and share cards) and the direct tailnet link in the phone dialog render only while GET /api/shared-crew/capabilities reports shared_crew_preview: true (sharedCrewUi.sharedCrewPreviewOn). A missing field, an older gateway or a failed read keeps them hidden, and no browser setting turns them on.

Shared Crew query failures render through ErrorNotice. A failed refresh keeps cached content mounted, including invite emails, name, picture and API-key drafts, creator filters, queued sends and collaboration state. An initial failure without data shows the error alone; optional routes returning 404/null still mean unavailable, not failed. An unreadable mode remains an error.

People and the invite card offer retry beside cached form content and omit the agent hand-off to protect its drafts. Initial failures and read-only surfaces offer the hand-off. The phone dialog owns its capability-read failure; the creator-filter bar owns capabilities, mode and People failures for the sidebar. The open chat's collaboration strip also owns those reads for message bylines and the viewer/typing-lease reads for the composer, including when the sidebar is closed, so notices never repeat per message. The one queued-send label owns work and capacity failures whether or not its last successful read contains queued work. SharedCrewReadFailures.test.tsx exercises these query consumers together. The People Remote Control card reports a failed connection-method read with an error and retry, retains cached methods, and reserves unavailable copy for a successful empty response. Its hand-off stays off beside the invite/key drafts. The shared phone hook exposes its query without changing the navigation rail.

Invite and credential inputs cannot change during submission. Removing a key also locks the invite draft until the confirmed disconnection settles. An avatar upload must settle before an invite can be submitted, and cannot replace a picture while that invite is pending. Invite creation and key removal acquire a synchronous submission latch before their asynchronous guard or confirmation. The latch releases on cancellation or mutation settlement; failed submissions keep the draft for retry.

No list of accepted work renders above the composer, in any state or Crew mode. A running turn shows as the chat's own running turn (its stop button), and a finished or ended one as its transcript. The one Shared Crew work state with its own line is a chat turn the host holds for capacity: while the session has no queue-stack rows, its newest user message carries a small "Queued" line with its own Cancel (QueuedSendLabel), whose tooltip names the personal or Crew-wide limit. Cancel sends POST /api/shared-crew/work/{id}/cancel at the shown revision once; a stale click adopts the current record. A busy session's queued sends stay the queue stack's rows.

State Shown as Draft
submitted the sent bubble sent
queued (chat turn, no queue-stack rows) "Queued" and Cancel on the newest user bubble sent
admitted, running, cancelling, reconciling the chat's running turn sent
completed, failed, expired, cancelled, unknown_outcome the transcript; no extra label sent
rejected refusal notice by the composer, with whose limit and the next step restored
lost send race (send_race, never an OperationState) notice above the composer: "X sent first", "Send after X's message" (the Send now action), Dismiss; no bubble or error row restored
someone else typing (typing lease, never an OperationState) composer read-only, button row replaced by "X is typing…"; Stop and Steer stay for a running turn; with KIROCREW_SHARED_CREW_PREVIEW=1, a Take over button kept, read-only
someone took the lease over from this person (preview only) composer read-only, "X took over typing" in the banner, Take over to take it back kept, read-only
this person took the lease over (preview only) composer unlocks once the lease is re-read kept, editable
a takeover fails (preview only) inline ErrorNotice with the agent hand-off under the banner; still locked kept, read-only

A memory change in a shared Crew shows in its session as one info notice row ("Bob changed a Crew preference: Always reply in English"). The frame is kept in the client cache, newest first, at most 20 (sharedCrewKeys.memoryChanges).

People names everyone by their Tailscale identity under Seen in this Crew and has no waiting list and no Approve, Dismiss or Remove control: Tailscale access rules decide who gets in. The owner-only invite card (TailscaleInvites, theme tokens, rows wrap at narrow widths):

State Shown as
first invite while nobody else has access a one-time confirm naming who can open the Crew (anyone Tailscale access rules let reach this machine), the session and Crew memory counts, a laptop note on a laptop host, and where to stop sharing (revoke the invite or remove them from the tailnet)
the first-share acknowledgement fails the invite still runs; its row shows the server's first_share_ack_required refusal
the direct link's Copy is refused by the browser an inline ErrorNotice with the agent hand-off; the link stays selectable in its field
Remove key a confirm, then DELETE .../credential with the irreversible-confirm header
teammate or a gateway without the routes nothing

8. Capabilities

Capabilities reports what this Crew can back. Every field defaults to unavailable, so a build that wires nothing claims nothing. containment_level states the effective guarantee (hard, best_effort, none), never the configured intent. membership_link is an id from the closed MEMBERSHIP_LINKS set, never a URL taken from config or a peer.

Aggregation

capabilities.register_capability_source(name, fields, source) is how a behaviour module speaks for a field; the gateway wires the registrations at startup. aggregate_capabilities combines them conservatively:

  • A source answers only for the fields it declared. A name registers once.
  • A source that raises, or returns anything but a CapabilityContribution, makes each declared field unavailable with reason source_failed.
  • Two sources on one field: the weaker state wins (unavailable < disabled < degraded < available), and the weaker containment_level wins.
  • containment_level is none unless containment is available or degraded.
  • Two different membership links leave the link empty.

A source answers from state it already holds; it does no I/O on the request path.

GET /api/shared-crew/capabilities (routes_capabilities) answers Capabilities.to_dict() plus these additive keys, states and reasons only, sent no-store:

  • reasons: field to no_source or source_failed, or for attribution the forwarded-identity gap (platform_unprovable, daemon_same_user, daemon_not_found, see Derivation). A source names a reason in CapabilityContribution.reasons; the weakest answer's reason is reported;
  • setup_paths: each shared-access setup path (access.SETUP_PATHS: tailscale, kiro_login) to {state, reason}. Tailscale reports what the gateway resolved at start (access.note_tailnet): available once Tailscale access is on and the tailnet name resolved, or once identity trust with an allowlist is on (tailscale serve set up by hand), degraded (tailnet_unreachable) when it is on without a name, else not_configured. The other paths report not_in_this_build;
  • keep_awake: state (available | unavailable), reason (no_backend, unsupported_platform, not_checked until the post-start probe has run), backend, laptop and laptop_reason (battery_present, no_battery, unknown), from host_power.note_host, which host_power.probe_after_start runs in a background task after the listener is up (see Who gets in, Keep awake).

In network mode the People page (PeopleCrew.tsx) reads, top to bottom:

  1. The share card, one bordered card. A green dot and "Shared on your tailnet" while tailnet_direct.state is active, else the Tailscale setup path's status badge; it reports the gateway's own listener and never claims the viewer can reach it. Its ⓘ says who can open the Crew (people Tailscale lets reach this machine) and that messages still go to the AI model service. On the right, the faces of the people connected now and "N here now", from presence; the viewer counts as here, since they are on this page. Below, the share link with a primary "Copy link" and, for the owner only (the invite read answered), a secondary "Invite...", then "Manage people in Tailscale" (https://login.tailscale.com/admin/users, a fixed URL, new tab, noopener noreferrer): removing a person is removing them in Tailscale.
  2. "People · N" with an ⓘ (everyone who connected; Tailscale names the device owner; names and photos are display only; remove people in Tailscale). Each row: picture, name (with You), the login and one activity (typing in a session from presence, else the running count, else here now or last seen), a green dot while connected (always on the viewer's own row), and ✎ when the row has a tailscale_user_id. A local operator row is the person who runs this Crew and carries this machine's own Tailscale user id (access_set.owner_user_id) once the daemon reported it, so everyone, the owner included, can rename themselves. Invites nobody accepted yet follow, dimmed, offering only Revoke.
  3. Remote Control with an ⓘ and its "Set up" button.

"Invite..." opens a dialog with the invite form (email or link, name, picture). Without a connected Tailscale API key the dialog asks for the key first, beside the by-hand share path. The People page has no Kiro login row and no Assigned users section; the capability code for those is unchanged.

✎ opens a name-and-picture dialog. Any admitted person may change any person's display name and picture, their own included (routes_people): equal rights among the callers the People read admits. Those are a person the direct listener admitted after checking the access set (routes_identity._tailnet_person), and the owner. A non-owner dashboard link session (a Telegram, Teams or Webex allowlist link) goes through require_owner_for_dashboard_caller and is refused, as it is for the read. The record is keyed by stable Tailscale user id in the invite store's display map, so it follows a renamed login and works for a person who was never invited (the user id comes from the daemon's whois, tailnet_live_allowlist). decorate_people attaches tailscale_user_id and lets a display record win over the alias an invite carried. It is display only: no access path reads display, the member record admission reads is untouched, and the verified login stays on the row. Each change is audited as a person_display action and pushed as a shared_crew.people frame. GET /api/shared-crew/people also carries live ({activity, session_key, session_title}, the person's strongest activity across sessions from PresenceRegistry.live_by_principal) for a person with a tab open.

The People surface (Settings > People) shows one setup empty state while no setup path is available and no one but the viewer has been seen: it names the three paths, each with the availability its capability reports and a link to existing docs only. It offers no button that does nothing.

Not in this build

Enterprise sign-in, per-person grants, revocation feeds, workload identity, Crew registration and inference budgets are not part of this build; their seams are described in the design doc. Every admitted person can use everything the Crew can: there is no per-task authorization layer.

9. Records and migration

Every record carries schema_version (codec.SCHEMA_VERSION). It is the Shared Crew record version, unrelated to the platform CONTRACT_VERSION. Rules:

  • An added optional field keeps the version. A changed meaning bumps it, and the reader handles every older version.
  • A reader preserves keys it does not own (codec.split_extra into extra, written back by merge_extra), so an older gateway's rewrite never drops a newer field. Session metadata also passes through history.carry_unowned_metadata.
  • An enum value a newer writer added reads as the field's explicit fallback (enum_or), not as a refusal of the whole record.
  • No migration rewrites history to add attribution. Legacy stays legacy.

The contracts are pinned by test/test_shared_crew_contracts.py. Changing a field or an enum value changes that test in the same change.

Operations

Prerequisites. One gateway on a host the operator controls. Collaborators reach it through tailscale serve (preferred) or the tailnet address directly (only when KIROCREW_BIND widens the bind), with dashboard.tailscale.trust_identity on and dashboard.tailscale.allowed_logins listing each person (section 2). Without that opt-in every remote caller is Unknown. Per-person containment needs Linux with cgroup v2, a systemd --user session and the cpu, memory and pids controllers delegated to the user slice; anything else runs with admission counts only and reports it.

Supported profiles.

Profile Admission Containment hard_limits
macOS, Windows, Linux without delegation counts and queues unavailable refuses all work, by design
Linux, cgroup v2, delegated user slice counts and queues best_effort (CPU, memory, pids) allowed
Unrestricted host root counts and queues best_effort not adversarial containment

Start, stop and configure. Start with kirocrew gateway (or the installed service) and stop with kirocrew stop. Limits live under dashboard.shared_crew (section 4) and are re-read within seconds, without a restart (every turn gate call refreshes the gateway's service, so enabling admission applies to the next turn):

kirocrew config set dashboard.shared_crew.admission_enabled true
kirocrew config set dashboard.shared_crew.principal_concurrency 2
kirocrew config set dashboard.shared_crew.hard_limits true   # only on a delegated Linux host

Check what holds with GET /api/shared-crew/capabilities (what is enforced) and GET /api/shared-crew/capacity (the effective limits, the containment report and the viewer's usage). A hard_limits host that lacks a prerequisite logs hard-limit mode is on and containment is unavailable (<reason>) at start and refuses every admission and runtime start until it is fixed.

Migration. Nothing is rewritten. Sessions created before Shared Crew read as legacy_missing (shown as the owner's, storage unchanged); their messages have no author. New sessions and messages carry attribution and author stamps. No creator is backfilled and no access is inferred from an author.

Rollback. Drain first: list GET /api/shared-crew/work, cancel what should not run (POST /api/shared-crew/work/{id}/cancel), and wait until capacity shows nothing active or queued. Then set admission_enabled false; new work passes through at once. Accepted-work records stay in the task store (tasks.db), and attribution stays in session metadata, which older readers carry as unowned keys. Never delete sessions to roll back.

Diagnosing Unknown attribution. GET /api/auth/me answers the caller's principal. kind: unknown with provenance none means the request did not come through a verified tailnet path: check trust_identity, the caller's login in allowed_logins, that tailscale serve (not Funnel or another proxy) fronts the port, and the gateway log for whois failures. A channel sender is always Unknown in this build.

Quota ownership. GET /api/shared-crew/capacity names the limiting scope (principal or crew) and the viewer's active and queued counts. GET /api/shared-crew/people shows each observed person's usage when admission is on. Work records carry budget_key, the opaque principal id charged.

Cancellation and recovery. Cancel a queued chat turn from its "Queued" line in the chat, or any queued or admitted item by the cancel route with its expected_revision; a stale revision answers 409 with the current record. A restart reconciles accepted work before admitting new work (section 4): nothing that may have run is replayed, and a chat turn queued across a restart ends cancelled with its user row in the transcript to resend.

Cleanup. The admission service purges terminal work records from the task store 24 hours after they ended (IDEMPOTENCY_TTL_SECONDS), while admission is on. Presence, observed people and shared decisions are in memory and reset on restart. Principal slices are runtime-only systemd units and disappear with the user session.

Known limits. Containment is best_effort: runtimes share the gateway's uid. IO is not limited, and disk is accounting of accepted request bytes, not a filesystem quota. A shared session's runtime stays in its first initiator's slice. Channel senders are Unknown. The internal one-shot helpers and the CLI's own processes in the table in section 1 bypass fair admission.