Add configurable multi-user modes with user-bound session trees #1134

Summary

Add configurable multi-user operation while preserving the existing single-user behaviour by default.

The first multi-user profile, family-shared, runs one Piclaw process with a shared workspace, skills, add-ons and machine runtime. Effective application capabilities may differ per user. Each authenticated family member receives a stable identity, a predefined landing session, and ownership of their root session trees. Users may create roots where policy allows, fork their own sessions, rename their own session handles, archive and restore branches, and use the shared workspace.

The isolated-containers profile uses the same identity and authentication contract at a routing gateway, then sends each user to a dedicated Piclaw container. The deployment guide must state where isolation comes from and which resources can be shared deliberately.

TOTP and WebAuthn remain supported in every mode. The authenticated username and display name must be passed into session execution so models receive the correct user identity on interactive, restored, forked and background turns.

Mode semantics

single-user

• Default when configuration is absent on fresh/legacy single-user installs. Existing multi-user stores require explicit validated mode configuration; config loss or downgrade fails closed.
• Existing default user, web:default session, global TOTP secret and passkeys continue to work.
• No account selector or family administration is shown.
• Existing URLs, automation and stored data remain valid.

family-shared

• One process, database and workspace.
• Shared filesystem, skills, add-ons, provider setup and machine runtime; application capabilities may differ by account.
• Application-level separation for users, timelines and session trees.
• Intended for trusted household members. It is not a hostile-tenant filesystem boundary.
• Each user lands in a configured home root session after authentication.
• Forks inherit root ownership; friendly session/agent names can be changed by the owner.

isolated-containers

• A gateway authenticates users and routes them to configured backends.
• Each user receives a separate Piclaw process, database, session store, keychain and workspace unless an operator explicitly mounts shared resources.
• Shared skills should use versioned packages or a read-only mount; writable shared volumes reduce isolation and must be documented.

Acceptance criteria

• domains.access.mode is explicitly configurable as single-user, family-shared or isolated-containers. No config preserves single-user behaviour on fresh/legacy single-user stores; persistent activation state prevents silent downgrade of family/isolated data. Unimplemented modes fail validation until their gates pass.
• Existing installations start in single-user mode with no data rewrite or UI change required.
• Every authenticated request resolves a trusted actor principal with immutable user ID, current username/display name, role and destination. Authentication sessions, actors, target session owners and service executions are distinct; browser correlation headers never establish identity.
• TOTP and WebAuthn issue web sessions for the matched user instead of the hard-coded default user.
• Each family user has a predefined landing root session.
• Users can list, open, fork, rename, archive and restore sessions that they own.
• Forked sessions inherit the owner and root-tree policy atomically.
• Friendly renaming does not require changing the durable chat JID.
• Client-supplied chat, branch, message, media, task and recording identifiers are authorised against the principal before use.
• SSE clients receive events only for authorised chats.
• Model execution receives the authenticated username/display name and user-specific memory context on every supported execution path.
• Settings distinguishes personal, session-tree, family/shared, deployment and administrator scopes.
• family-shared is documented as logical conversation separation on a trusted shared machine.
• isolated-containers is documented and tested with explicit process/volume/network separation, no direct backend bypass and no tenant host-admin authority; Docker shares the host kernel. Optional shared volumes and host/operator access are stated limits.
• Migration, rollback, audit logging and end-to-end tests cover all three modes.

Non-goals for the first family release

• Filesystem confidentiality between family members.
• Per-file access-control lists inside the shared workspace.
• Enterprise SSO, SCIM or directory synchronisation.
• Cross-user shared chat trees or collaborative editing.
• Hostile-tenant isolation inside one Piclaw process.

Child issues

• Define modes, user schema and backward-compatible migration #1123 — Define modes, user schema and backward-compatible migration
• Resolve authenticated principals and expose /auth/me #1124 — Resolve authenticated principals and expose /auth/me
• Add per-user TOTP and WebAuthn account lifecycle #1125 — Add per-user TOTP and WebAuthn account lifecycle
• Add root session ownership and central chat authorisation #1126 — Add root session ownership and central chat authorisation
• Enforce principal scope across HTTP, SSE and referenced resources #1127 — Enforce principal scope across HTTP, SSE and referenced resources
• Support user-owned root sessions, forks and friendly renames #1128 — Support user-owned root sessions, forks and friendly renames
• Propagate authenticated user identity into model execution #1129 — Propagate user identity and personal memory into model execution
• Redesign Settings for account, session and family administration #1130 — Redesign Settings for account, session and family administration
• Define shared-family resources and capability controls #1131 — Define shared-family resources and capability controls
• Add isolated-container routing and deployment profile #1132 — Add the isolated-container gateway and deployment profile
• Add migration, security regression, operations and documentation gates #1133 — Add migration, security regression, operations and documentation gates
• Reach standard chat UX parity in family mode #1242 — Reach standard chat UX parity in family mode

Cross-cutting acceptance

• Explicit single-user → family activation inventories every legacy root/resource and preserves all messages/session files. Rollback/config-loss cannot expose multi-user histories or remove ownership.
• API requests with foreign/unknown targets are denied without implicit rerouting; only omitted targets default home. Fresh login opens the preconfigured root; users freely fork/rename owned descendants. Handles are unique per owner across their active roots, with no global resolver fallback.
• Identity reaches interactive and background models/tools through validated scoped execution context; persist actor/owner attribution in messages, jobs, usage and audits. Background jobs do not depend on a live browser cookie.
• Settings includes the mode configuration entry, personal/shared/admin scope, safe factor/recovery lifecycle, home/fork management and effective capability warnings. Account switches clear prior-user browser/stream state and correctly rebind push devices.
• Family mode deliberately shares a filesystem and machine runtime, with per-user application capability policy. Application role checks do not confine users with arbitrary code/file access or guarantee child-safe/privacy isolation; auth/gateway secrets must still be excluded from generic tool injection.
• Keep personal memory/Dream source scope separate from explicit family memory. Shared workspace/skills do not imply shared conversations, personal preference attribution or automatic all-chat consolidation.
• Apply per-user fairness and global resource bounds on the small shared machine. Preserve single-user provider/identity/settings behaviour when mode is absent.
• Attach Define modes, user schema and backward-compatible migration #1123–Add migration, security regression, operations and documentation gates #1133 through native GitHub parent/sub-issue links and record exact dependency edges; maintain real-number links and staged acceptance prerequisites.

Implementation notes

Current code already stores user_id on web_sessions, WebAuthn credentials and WebAuthn enrolments. Login still hard-codes DEFAULT_WEB_USER_ID, and request guards only prove that a cookie is valid. Many handlers then trust a client-supplied chat_jid. The implementation needs one principal and authorisation seam before enabling a second account.

Representative paths:

• runtime/src/db/web-sessions.ts
• runtime/src/db/webauthn.ts
• runtime/src/channels/web/auth/
• runtime/src/channels/web/http/request-guards.ts
• runtime/src/channels/web/sse/sse.ts
• runtime/src/channels/web/agent/agent-control-plane-service.ts
• runtime/src/agent-pool/branch-manager.ts
• runtime/src/db/chat-branches.ts
• runtime/web/src/components/settings/

Definition of done

• Family milestone: Define modes, user schema and backward-compatible migration #1123–Define shared-family resources and capability controls #1131 plus the family acceptance/documentation stage in Add migration, security regression, operations and documentation gates #1133 are verified before enabling additional users.
• Existing single-user installations pass migration and behaviour tests.
• Family-shared threat model and isolation limits are visible in Settings and docs.
• Later isolated-container milestone: Add isolated-container routing and deployment profile #1132 plus isolated acceptance in Add migration, security regression, operations and documentation gates #1133 passes. The complete epic closes only after both milestones, but the family release does not wait for Docker implementation.
• Hosted CI and production-shaped end-to-end tests pass.

Release sequence

1. Define modes, user schema and backward-compatible migration #1123 configuration/schema/migration contracts; Resolve authenticated principals and expose /auth/me #1124 trusted principals.
2. Add per-user TOTP and WebAuthn account lifecycle #1125 account authentication and Add root session ownership and central chat authorisation #1126 ownership proceed in parallel. Enforce principal scope across HTTP, SSE and referenced resources #1127 route enforcement and Propagate authenticated user identity into model execution #1129 execution identity follow ownership.
3. Support user-owned root sessions, forks and friendly renames #1128 owned branch UX and Define shared-family resources and capability controls #1131 memory/capability/resource policy; Redesign Settings for account, session and family administration #1130 integrates Settings and account switching.
4. Add migration, security regression, operations and documentation gates #1133 verifies the family gate throughout these phases; only then enable family-shared.
5. Add isolated-container routing and deployment profile #1132 supplies the later gateway/container implementation, conditional Settings and the isolated gate in Add migration, security regression, operations and documentation gates #1133. Both deployments are documented; unavailable functionality is labelled.

Existing #446 certificate/device onboarding is related, not a prerequisite for users already served over valid HTTPS. No enterprise SSO, general shared-chat ACL system or container provisioning UI is required for the first family release.

Tracking

• Related onboarding issue: Web onboarding flow for mkcert + passkey setup #446
• Deployment mode default: single-user