session: sessions are addressable only by opaque UUID, so a named session cannot be reused

[ankitranjan7]

Summary

Browser sessions are addressable only by opaque UUID. There is no alias, label, or tag — while profiles get exactly that via webcmd profile rename <contextId> <alias>. When an agent is told to work in a named session it cannot resolve the name, so it silently creates a new session instead, and the isolation the caller asked for is gone.

What agents actually do

Two independent tasks in an internal agent-behaviour eval, each supplied with a session name to use:

• Agent A was given a named session, "failed to resolve or reuse" it, and created a fresh one
• Agent B ignored the supplied name and created session_05c46486-a2f6-40a3-bedc-7b08060569e2 under a different profile than intended

Neither reported a problem. Both proceeded as though they had complied. Separately, a third agent left an exploratory session open after investigating — with session list returning nothing but UUIDs and timestamps, nothing distinguishes an abandoned session from a live one.

Why they did that

session create returns an opaque ID and requireSessionIdShape (src/cli.ts:864) rejects anything that is not one. So when an agent holds the string research-2026-08-17 and needs a session, its options are:

1. Pass it as --session → rejected on shape
2. Call session list and match it against the output → the output has id, profileId, kind, createdAt, updatedAt, lastUsedAt, runtimeState, handoff, and no field the name could match
3. Create a new session and carry on

Option 3 is the only one that completes the task, so that is what both agents chose. The failure is silent because from the agent's position nothing failed — it asked for a browser session and got one.

This also blocks the multi-agent workflow the skill documents. webcmd-browser/SKILL.md:35 says "Parallel agents use separate sessions" — but with no naming, a second agent cannot find the session a first agent established, and cannot verify it is not reusing one.

Root cause

• src/cli.ts:857 — session close takes <session-id>, described as "Existing opaque Session ID from webcmd session create"
• src/cli.ts:864 — requireSessionIdShape(sessionId) enforces the UUID form
• session list records carry no user-supplied field
• profile rename <contextId> <alias> exists and does exactly the needed thing, one noun over

Fix

Mirror the profile mechanism, which is already built and already shaped right:

1. webcmd session create --name <alias> — store the alias on the session record
2. Accept an alias wherever --session accepts an ID, resolving alias → ID before requireSessionIdShape
3. Surface name as a column in session list
4. webcmd session rename <session-id> <alias> for symmetry with profile rename

Aliases scope per profile, matching how profile aliases already work.

If naming is not wanted, the weaker fix is to make the failure loud: when --session receives a well-formed string that is not a known ID, error with SESSION_NOT_FOUND and list the candidates, rather than letting the agent fall through to creating a new one. That turns a silent isolation break into a visible one.

Check

A test asserting a session created with --name x is addressable as --session x, and one asserting an unknown alias errors rather than creating a session.