Make one Headless host reliable for concurrent subagents

[SarthakWade]

Problem

Several subagents can connect to the same Headless host, but Headless currently coordinates individual commands rather than their complete browser tasks. Named isolated sessions protect cookies and storage, yet a session name does not identify its owner. A second same-user client can navigate or close that session, stop its recording, or replace its active flow. Commands for all sessions use one execution queue, so a long wait or tour can delay unrelated agents until their clients time out. The timed-out command may still run later.

Evidence also shares one artifact store: artifacts list is host-wide, report create includes that list, and artifact names can be used across sessions. stop and profile clear affect every session. The current skill recommends task-specific names but does not require isolated sessions for parallel work.

Relevant code: Transport.swift (single request queue), HostCore.swift (session lookup, flows, recordings, report), Artifacts.swift (shared store), and MCP/main.swift (one shared argv tool).

Goal

Two cooperating subagents should be able to run independent browser tasks on one host without accidentally changing each other's page, evidence, recording, or lifecycle. A stalled or disconnected client must produce an explicit, recoverable outcome. This is a correctness contract for cooperating agents. It must not claim to protect against a hostile process running as the same OS user; separate OS users remain the boundary for that case.

Design work

• Define how a client claims a session, how ownership is checked on every session command, and how leases expire or are released after a client exits. Decide how this works for CLI and multiple stdio MCP processes without putting a reusable secret in logs, flows, reports, or page output.
• Specify the behavior of the implicit default session in multi-agent use. Preserve a simple single-agent path while preventing accidental sharing.
• Define fair scheduling and timeout behavior across sessions. A queued request must not execute silently after its caller has timed out; where cancellation cannot be guaranteed, return an explicit unknown-outcome state and a way to reconcile it.
• Scope artifact listing, report references, uploads, visual comparisons, flows, and recordings to the owning task or session, with an explicit path for intentional sharing.
• Decide who may run host-wide operations such as stop and profile clear while other sessions are active. One subagent's cleanup must not end another's work.
• Document what happens when a session is closed, a client disconnects, the host restarts, or a subagent crashes.

Acceptance criteria

• Add an architecture decision before changing the agent-facing protocol or ownership model.
• Two independent CLI clients and two MCP clients can create isolated sessions and complete interleaved visit, inspect, action, capture, and cleanup flows without cross-session effects.
• Tests cover same-session contention, name collisions, crashed clients, long waits and tours, queued timeouts, host-wide commands, and recording and flow ownership.
• A report and artifact listing for one subagent do not silently include another subagent's evidence. Intentional sharing is explicit and tested.
• Existing session isolation, credential challenge binding, private socket, no TCP listener, bounded responses, and no arbitrary JavaScript contracts remain intact.
• Update CLI help, capabilities and SDK schema where the contract changes, plus command docs, skill guidance, and macOS and Linux E2E coverage.

@yashranaway Could you review this scope, especially session ownership, queued-request outcomes, and artifact sharing? Please flag any behavior that should be split into a separate issue before implementation.

[yashranaway]

Try to see if we can make a lightweight version of headless which can be synced between multiple sessions or not depending on the task and it should be used for subagents

[SarthakWade]

I think we can keep this lightweight by using the existing host and session model:

1. Give each subagent its own named session. The parent chooses --isolated for separate cookies/logins, or a normal session when the task needs the existing shared profile.
2. Keep each session's live page, actions, recordings, and evidence separate. My reading of "sync" is shared login/profile state when requested, not two agents controlling the same tab.
3. Add a session owner or lease so one subagent cannot accidentally use or close another's session. Only the parent should run host-wide cleanup while child sessions are active.
4. Make queued commands and timeouts predictable, then test two CLI and MCP clients working at once on macOS and Linux.

I would ship those two clear modes first. If a real task needs selective state transfer between isolated sessions, we can design that separately rather than silently copying cookies. @yashranaway , is shared profile state what you meant by sync?

[yashranaway]

Those points LGTM, sync as in the orchestrator agent should have access to other subagents using Headless. Basically something like an orchestrator and a Headless approach where the agent spawning multiple subagents has access to, or has a flow of where they are going. I wanted something like that, something of that sort in Headless, where the main agent, which is spawning subagents and letting them access Headless, should know what Headless is doing.

[SarthakWade]

@yashranaway Thanks, I understand "sync" now. You mean the orchestrator should be able to follow what its subagents are doing in Headless. My earlier comment interpreted it as syncing browser profile state.

Here is the revised lightweight approach:

1. The orchestrator creates a named Headless session for each subagent and registers those sessions under one parent task. Each child still gets its own page; the parent chooses shared-profile or isolated cookies separately.
2. Headless keeps a small, bounded activity trail for each child: current URL/title, command type and time, success or error, and links to screenshots, recordings, or reports. It never records filled text, passwords, cookie values, or raw page content in this trail.
3. Add a read-only CLI/MCP command for the orchestrator to list its child sessions and check their latest activity. Polling is enough for a first version; Headless does not need to spawn the subagents or add a second browser host.
4. Bind child commands and cleanup to the right session, protect host-wide operations, and test two CLI and MCP subagents running at once, including a stalled or crashed child.

That gives the parent a clear view of where each subagent went and what happened, without making their live tabs interfere. Does this match what you had in mind?

[yashranaway]

Go ahead