Workspace Lanes
Workspace lanes are an opt-in substrate for agents that may serve multiple people. They let one agent persona keep shared persona files in the configured agent workspace while giving each user a separate lane workspace for user-specific files and generated state. Current scope: this release adds the core resolver, config schema, first-use seeding, lane-aware bootstrap loading, hook/plugin context, reply-path adoption, reset/session-memory lane routing, lane-local remote media staging, and a real two-user route proof. Do not treat workspace lanes as complete hosted multi-tenant isolation yet.For Users
Most local users do not need workspace lanes. If you are the only person talking to your assistant, leaveworkspaceLanes unset and WednesdayAI keeps the existing single-workspace behavior.
Workspace lanes matter when the same persona may answer more than one person. Without a lane model,
files such as USER.md, MEMORY.md, generated notes, and downloaded artifacts can become shared
context. With lanes enabled and adopted by a runtime path, WednesdayAI can keep the persona stable
while separating user-specific context by lane.
The default lane model is hybrid:
workspaceLanes.create: "manual" never creates the lane directory on the reply path. Operators must
provision the resolved lane directory first; otherwise WednesdayAI denies the lane for that turn and
does not run the reply in the shared persona workspace.
workspaceLanes.skills defaults to "shared". "lane" switches skill discovery, skill snapshots,
and skill environment loading to the effective lane workspace. "both" is accepted as
configuration for forward compatibility, but currently behaves like "shared" until precedence and
conflict handling are specified and tested.
Session isolation is separate. If multiple people can DM the bot, also configure
session.dmScope: "per-channel-peer" or per-account-channel-peer. Session keys control
conversation history. Workspace lanes control workspace files and bootstrap context.
For Administrators
Enable lanes only on personas that are intended to serve more than one user:enabled: true is per agent. There is no global default lane setting in this slice.
Lane keys
laneKey controls which actor fields choose a lane:
Lane ids are deterministic digests, not raw sender ids. Missing actor fields deny the lane instead
of falling back to an anonymous shared lane.
Lane keys also decide which run paths can reach an agent at all:
- Agent-RPC runs (subagents,
sessions_send, announces, OpenAI-compatible HTTP, CLI, Discord voice) carry no channel sender of their own, so they are always denied onchannel-peerandaccount-channel-peerlane agents. account-channel-peerlane agents are unreachable from gateway clients: a gateway turn has no channel account.- On
canonical-identitylane agents, a channel user who is not insession.identityLinkscan no longer spawn orsessions_sendinto the agent — the run identity is validated against identityLinks keys, so an unlinked user’s delegations are denied instead of running in the shared persona workspace.
Linking gateway devices
Gateway turns (web client, Control UI) are sent by the verified device, so their sender id isdevice:<deviceId> — not the app id. Link each device to a person, and every turn from that
device resolves the person’s canonical lane. From ADR 0104 on, the person is
also the sender name: the model’s Sender block reads
"label": "Alice (device:…)", "name": "Alice", with the client’s display name
(for example MentraOS glasses) as a separate client provenance field. Link with
wednesdayai devices link <deviceId> --identity <key>, or pair with
wednesdayai qr --client <id> --identity <key> (or wednesdayai identity link <key> --qr) so the
first connect links the device; wednesdayai devices remove also unlinks. See
Identities.
Get device ids with wednesdayai devices list --json (the deviceId field of each entry under
paired). A device-less gateway turn is denied on every lane key; an unlinked device is denied on
canonical-identity and account-channel-peer (see channel-peer below). The reason is shown to
the requester:
- Device not linked:
This assistant keeps a private workspace for each person, and this device isn't linked to a person yet. Ask your administrator to link it: wednesdayai devices link <deviceId> --identity <your name> - No paired device:
This assistant keeps a private workspace for each person, and this connection has no paired device identity, so it can't be linked to a person. Connect from a paired device. account-channel-peeragent:This assistant keeps a workspace per channel account, so it can't be used from this app. Message it on its channel instead.- Otherwise (a linked turn the runtime still cannot serve):
This assistant's private workspace isn't available. Ask your administrator to check the gateway log.
gateway.controlUi.dangerouslyDisableDeviceAuth is treated as
device-less — any presented device block is ignored — so it is denied on lane agents. Under
channel-peer a device gets an isolated per-device lane (channel:webchat:peer:device:<deviceId>)
whether or not it is linked.
Upgrading from app-id lanes (before the device sender)
Builds before the device sender keyed gateway turns on the app id, producing lanes namedlane-<hash> with the preimage
agent:<agentId>:channel:<channel>:account:<accountId>:peer:openclaw-user-client. Those lanes are
shared by every web user of the agent and become orphaned once the device sender is live. Find each
one by hashing its preimage — laneId = "lane-" + sha256(preimage).hex.slice(0, 24) (Node:
crypto.createHash("sha256").update(preimage).digest("hex").slice(0, 24)) — then merge it into the
person’s canonical lane (agent:<agentId>:canonical:<identityLinks key>) by hand: one app-id
lane may hold several people’s data, so do not wholesale-rename without reviewing the files.
Root templates
rootTemplate accepts only {agentId} and {laneId} placeholders. {laneId} is required so two
users cannot collapse into the same workspace. Templates with traversal segments, blank values,
unsupported placeholders, or malformed braces are denied.
Keep lane roots under controlled WednesdayAI state unless you have an operator-managed storage
plan. Avoid broad roots such as the home directory. When a resolved lane path already exists, it
must be a directory; regular files, symlinks, and other non-directory entries are denied.
Creation and seed files
create: "on-first-message" creates the effective lane workspace when first resolved, unless a
non-directory entry already exists at that path. create: "manual" requires the lane directory to
exist before the turn starts; a missing path or non-directory entry denies the lane. Default seed
files are:
USER.mdBOOTSTRAP.md
BOOTSTRAP.md after completing onboarding does not get it
back on later turns. Symlink and hardlink aliases that escape the persona workspace are
skipped, and dangling symlinks in the lane are treated as existing rather than followed.
Creation is atomic: the lane directory is seeded in a hidden temporary sibling
of the lane path, named .<lane directory name>.creating-<uuid> (under the
default root template: .workspace.creating-<uuid> inside lanes/<laneId>/),
and renamed into place only after every seed file has been written. A failed
seed write removes the temporary directory and fails that turn; the next turn
retries creation, so a published lane always has its seed files. A leftover
.<lane directory name>.creating-<uuid> directory can only come from a crash
mid-creation and is safe to delete.
Each lane completes onboarding independently: the lane’s agent deletes its own BOOTSTRAP.md copy
when the ritual is done, and the shared persona workspace keeps its BOOTSTRAP.md as the seed
template for new lanes.
Supported strategies
The config schema accepts reserved strategy names for forward compatibility, but runtime support in this slice ishybrid only. Other values are denied by policy until a later task implements them.
Sandbox lane fencing
When sandboxing is enabled, setfenceToLane: true in the agent’s sandbox
config to bind the sandbox tool filesystem to the user’s effective lane workspace instead of the
shared persona root. Without this flag, a sandboxed multi-lane agent can still traverse up to the
persona root and reach sibling lane directories via the workspace mount.
workspaceAccess: "rw" is required for complete lane isolation. With "none" or "ro", the
sandbox uses a scope-keyed workspace directory seeded from the lane directory — two sessions that
share the same scope key across lanes can read each other’s seeded files. WednesdayAI logs a
warning at session setup when fenceToLane: true and workspaceAccess is not "rw".
The fence only restricts tool filesystem access. Bootstrap resolution still happens before sandbox
entry, but it is not persona-only: lane-aware bootstrap loading can still select lane-local files
such as AGENTS.md, with persona fallback where applicable. The fence takes effect only when
workspace lanes are enabled, the lane is resolved, and the policy decision is "allowed" — it has
no effect in single-user (mode: "single") or denied configurations.
Migration notes
Existing per-agent workspaces keep working whenworkspaceLanes is unset. To migrate an existing
persona, keep the current workspace path as the persona workspace, enable lanes on that agent, and
let first-use seeding copy USER.md and BOOTSTRAP.md into each lane. Review any existing
MEMORY.md, memory/, downloads, and generated files before enabling lanes; move user-specific
content into the correct lane rather than leaving it in the shared persona root.
Feishu-style dynamic agents remain on the legacy-compatible per-agent workspace path unless their
resolved agent config enables workspaceLanes. Do not use lanes to replace dynamic-agent selection;
use lanes only to separate user-specific files inside a persona that may be shared by multiple users.
For Developers
Workspace lane data is additive. Existing hooks and plugins continue to run without lane fields.Gateway senders and lane denials
Gateway turns (chat.send, sessions.steer, talk) carry SenderId: "device:<deviceId>" when the
connect frame has a verified device block, and the app id (for example openclaw-user-client) only
when it does not. A Control UI running with gateway.controlUi.dangerouslyDisableDeviceAuth counts
as device-less: any presented device block is ignored. A device:<id> sender resolves to the
person recorded as the device’s owner on its pairing record (devices link, or a setup code with
--identity), never to a device: value in session.identityLinks; nothing re-derives identity
from the session key or the delivery route. For a linked device the sender name (ADR 0104) is the
identityLinks key; the raw device:<id> stays the sender id and the client display name is the
Sender-block client field.
A lane-enabled agent resolves the lane from the validated run identity on every path. A run that
cannot be attributed to a linked identity fails closed with WorkspaceLaneDeniedError
(message is user-facing, agentId names the agent):
- Gateway turns: the denial message is broadcast to the requesting client as the turn’s error, and
no assistant message is appended to
chat.history.sessions.steerchecks lane admission before it touches the active run, so a denied requester cannot abort another person’s turn and receives the reason as an RPC error. agentRPC (sessions_send, subagents, announces, Discord voice) and the CLI: the gatewayagenterror frame carriesdetails.reason: "workspace_lane_denied",agent.waitends withstatus: "error"and the message, and the CLI prints the denial and exits 1 instead of falling back to an embedded run.- OpenAI-compatible HTTP:
/v1/chat/completionsanswers403with{ "error": { "message": …, "type": "permission_error" } },/v1/responseswith{ "error": { "code": "permission_error", "message": … } }; streams carryError: <message>content /response.failedrespectively.
canonical-identity agents the agent-RPC denial reads: Agent "<agentId>" keeps a private workspace for each person, and this run is not attributed to a linked identity in session.identityLinks. For channel-peer and account-channel-peer agents every agent-RPC run is
denied, because those runs have no channel sender: Agent "<agentId>" keeps a workspace per channel sender, so runs without a channel sender (subagents, sessions_send, HTTP, CLI) can't use it.
Trust boundary: lane isolation holds against narrow-scope clients (the user client). operator.write
callers of the agent RPC are trusted to assert inheritedCanonicalIdentity, which is only checked
against identityLinks keys.
Denials on channel turns (Telegram, Discord, …) stay silent — an unlinked stranger gets no reply —
and this is unchanged.
Lane admission and resolution API
src/agents/workspace-lanes.ts is the resolver seam:
checkWorkspaceLaneAdmission({ cfg, agentId, personaWorkspaceDir, actor })is the side-effect-free admission check: the policy decision plus the on-disk gates (create: "manual"and non-directory paths). Pre-checks must call it instead ofresolveWorkspaceLaneso a pre-check admits exactly what the turn admits.sessions.steeruses it before touching the active run.resolveWorkspaceLaneForTurn(...)runs the same admission and then creates and seeds the lane whencreateis"on-first-message". The reply path calls it with the actor built bybuildWorkspaceLaneActor(src/auto-reply/reply/workspace-lane-actor.ts): a gateway turn keys the lane on thedevice:sender only, and channel turns keep their channel actor fields.WorkspaceLaneResolutioncarriesmode,agentId,laneId,laneKeySource,actor,personaWorkspaceDir,effectiveWorkspaceDir,created, andpolicy: { decision, reason? }.workspaceLaneCorrelationIdexposeslaneIdonly for an allowed multi-lane run.
Agent-RPC lane resolution and skills
resolveAgentCommandWorkspace (src/commands/agent/workspace-lane.ts) is the seam every
agent-RPC run path shares: the gateway agent method, sessions_send, subagent spawns and
announces, Discord voice, and the CLI agent command.
- A non-lane agent keeps the persona workspace for the run and for skills; nothing changes.
- A lane-enabled agent resolves the run identity with
resolveRunSenderIdentity— the same inputs the run itself uses, so the lane identity equals the run identity — and keys the lane on that identity alone. The request’schannel,to, andaccountIdare delivery targets, andinheritedSenderIdis an unvalidated wire value; neither keys a lane. - An unattributed run throws
WorkspaceLaneDeniedErrorbefore any model call. An allowed run getsensureAgentWorkspaceon the lane directory (bootstrap files are not seeded) and aworkspaceLaneresolution to forward to the embedded or CLI runner. skillWorkspaceDiris the lane directory when the agent setsworkspaceLanes.skills: "lane", otherwise the persona directory. The reply path derives it the same way. Skill snapshots record their source directory (skillWorkspaceDiron the snapshot) and are rebuilt when the current run has a different one, so one lane never reuses another lane’s skills. A snapshot without the field predates this change and counts as persona-built: only a run whose skill source is a lane directory rebuilds it, so non-lane agents never rebuild on the legacy shape.
The lane denial marker
Every lane denial carriesdetails.reason: "workspace_lane_denied" on the gateway error frame
(WORKSPACE_LANE_DENIED_REASON, a dependency-free constant in
src/agents/workspace-lane-denied-reason.ts). Read it back from a rejected gateway client request
with gatewayErrorReason(err) (src/gateway/client.ts) instead of matching the message text.
Core behavior keys on the marker: the CLI agent command skips its embedded fallback,
sessions_send reports status: "error" with the denial instead of waiting out a timeout, and a
denied subagent announce settles without retry (see Sub-agents).
Bootstrap hooks
agent:bootstrap hook context can include:
workspaceDir is the effective workspace for the current bootstrap pass and
workspaceLane.personaWorkspaceDir points at the shared persona workspace. Denied lane resolutions
are not exposed to bootstrap hooks.
Plugin runtime context
Plugin agent-hook and tool context can include:workspaceLane is
undefined.
The message_received plugin hook still runs before workspace-lane resolution, so it does not
receive workspaceLane in this slice. Message-hook types keep the optional fields for future
lane-aware message surfaces and compatibility, but plugins must not rely on them for
message_received.
Reading workspace files
Lane-aware bootstrap loading reads shared files frompersonaWorkspaceDir and lane-local files from
effectiveWorkspaceDir. This applies to embedded runs and CLI-provider runs that receive an
allowed workspaceLane. Custom project context paths use POSIX-style / separators for source-plan
matching; backslashes are treated as literal filename characters. Root-level variants such as
./AGENTS.md are matched by basename, while nested paths such as notes/AGENTS.md stay lane-local
unless that full path or a parent directory is explicitly listed in sharedFiles.
Sandbox context and lane fencing
resolveSandboxContext accepts an optional workspaceLane parameter. When a sandbox config has
fenceToLane: true, passing the resolved WorkspaceLaneResolution causes the sandbox workspace to
be bound to workspaceLane.effectiveWorkspaceDir instead of the agent workspace root. Embedded
compact sessions (compactEmbeddedPiSessionDirect) thread the lane through to sandbox setup
automatically when workspaceLane is included in the compact params.
Plugin and hook authors do not need to wire this themselves — the runtime handles it. It is
documented here for authors building custom compact flows or sandbox integrations that call
resolveSandboxContext directly.
Correlating by lane
providerConversationId is the opaque provider/cache session identity derived from
agentId + (sessionKey || sessionId). It is NOT lane-specific: in a multi-user group agent with
workspace lanes, several lane users can share one providerConversationId. To partition correctly
per lane, consumers (e.g. brain/background/cache systems) should dedupe on the composite key:
laneId is the opaque lane-<hash> digest, present only for an allowed multi-lane turn and
undefined for single-user and denied resolutions. Never correlate on raw identityLinks or a
lane hash preimage — they are intentionally stripped from runtime metadata.
Do not overclaim isolation
Workspace lanes provide product-context isolation for mostly trusted users. They are not hostile multi-tenant sandboxing, an auth system, organization model, billing boundary, quota system, or cloud-storage mapper. Hosted frameworks should carry lane metadata into their own storage, authorization, audit, and runtime policies.Per-lane usage accounting
Themodel_call_ended hook’s context (ctx) carries a laneId field (available since the
lane-correlation SDK surface, Slice 1) with the opaque lane-<hash> identifier for every turn
in an allowed multi-lane session. Operators can use this field to partition token counts by lane
for billing, auditing, or per-user cost attribution:
laneId is undefined for single-user agents or denied resolutions — these fall through to
existing non-lane accounting. providerConversationId is NOT per-lane (it is provider/cache
session identity shared by all lanes of a session); use laneId for per-lane attribution.