ux(agent): minimize time-to-collaboration for a temporary Agent LAN #246

Status

COMPLETED — THE TEMPORARY AGENT-LAN JOURNEY IS NOW A PRODUCTION-VALIDATED BASELINE.

#208 proved browser-optional cross-machine collaboration, #223 fixed retained Runtime/Harness context delivery, and the later dogfood follow-ups that emerged from this issue are complete:

#258 Room participant/presence presentation        ✅
#276 safe named Harness environment inheritance    ✅
#280 longer multi-participant Room responsiveness  ✅
#281 artifact handoff + Harness setup hardening    ✅
#286 Room-native ACP Human approval                ✅
#296 production permission-route dispatch fix      ✅
#297 built-in Harness approval compatibility       ✅

The current production baseline is Agent Runtime v0.5.24.

Repeated production dogfood across independent machines/environments has exercised the intended journey:

install / verify
→ create or join one temporary Room
→ peers become discoverable
→ ordinary targeted conversation
→ structured request / response / result
→ bounded cross-machine artifact handoff
→ explicit Human approval when a Harness asks
→ leave / stop
→ no permanent Free4Chat workspace or Agent network remains

The result of this experiment is intentionally conservative:

• the existing Room id + peers + participant-id protocol is sufficiently small and legible for the current developer-native product;
• Human-facing names remain useful presentation/discovery metadata, but Free4Chat does not add implicit @Name routing or a second name-resolution authority merely to hide protocol ids;
• structured collaboration continues to use explicit current participantId values discovered from the Room roster;
• no account, organization, persistent Agent registry, central planner, credential service, or permanent network was required;
• further onboarding convenience should be evidence-driven from future real users, not kept as perpetual roadmap work inside this issue.

This is the accepted negative/stop condition that the issue explicitly allowed: the current path is simple enough that no additional architecture or speculative convenience layer is justified.

Final acceptance interpretation

• real clean/fresh-room dogfood exercised the current collaboration journey across independent environments;
• no account, organization, project or permanent workspace is required;
• one machine can create a Room and another can join from a short Room-id/invite handoff;
• free4chat-agent peers --room <room-id> exposes current participants without raw protocol inspection;
• Agents retain stable participant ids and truthful capability metadata;
• capability advertisement remains discovery only;
• targeted conversation and structured request/result are production-dogfooded;
• bounded artifacts cross machines without shared filesystem setup;
• leaving/stopping creates no persistent Free4Chat membership;
• browser-created and terminal-created Rooms remain the same Room domain;
• no central identity, registry, planner, task database or credential service was introduced;
• name-based implicit routing was deliberately not added: explicit ids remain the structured addressing boundary.

Historical experiment notes below are retained as the evidence trail that produced the shipped follow-ups.

Product goal — minimize time-to-collaboration

The primary optimization target is:

need to collaborate
→ install / bootstrap if needed
→ create or join one temporary Room
→ participants become visible
→ address the right participant
→ exchange context / work / artifacts
→ leave
→ Room disappears

Measure success by setup friction and cognitive load, not feature count.

The ideal Human mental model is:

install
→ join
→ peers appear
→ collaborate

No organization, project, workspace, account, Agent registry, or permanent network should be required.

Why this is different from #208

#208 answered:

Can developers create/join the same ordinary Room from the terminal and prove real cross-machine Agent collaboration?

Answer: yes.

This issue asks:

Is that proven path already as simple, legible, and low-friction as the product can make it?

So this is a UX/dogfood refinement layer over the existing Room/Runtime architecture.

Product principles to preserve

• Anonymous-first. Core collaboration must remain fully usable without registration.
• Zero-workspace. Joining a temporary collaboration must not require creating an organization, project, team, or durable workspace.
• Ephemeral by default. Participants and Room state disappear according to existing temporary Room semantics.
• Participant-owned capability. Models, tools, credentials, private memory, local files and durable state remain local.
• Open and inspectable. Do not hide trust-sensitive Runtime behavior behind a hosted-only control plane.
• Human + Agent symmetry. Browser Humans and terminal/native Agents remain participants in the same Room rather than separate products.
• Names for UX, opaque ids for protocol. Human/operator interaction should prefer understandable participant names/capabilities where safe, while stable participant ids remain available underneath.
• No implicit authority. Join, presence, name resolution and capability discovery never authorize local work.

Experiment A — measure the current clean-machine journey

Dogfood the real current published Agent release from at least two independent machines/environments and record every step required for:

Use fresh Runtime roots / Rooms where practical so the measurement reflects a clean collaboration journey rather than local historical setup. Treat the already-proven #223 context path as baseline infrastructure, not the subject of this experiment.

If #258 has landed, use the refreshed Room UI as the browser-side presentation baseline; do not delay terminal/native measurements solely on #258.

1. first install / bootstrap;
2. doctor / readiness if needed;
3. Room create;
4. Room join;
5. seeing who is present;
6. selecting/addressing a peer;
7. one ordinary targeted conversation;
8. one structured collaboration request/result;
9. one artifact handoff;
10. leave / shutdown.

Record:

• commands that must be copied manually;
• opaque identifiers Humans must reason about;
• moments where the user must understand internal architecture;
• repeated setup that could be safely inferred locally;
• failure states whose next action is unclear;
• steps that exist only because of implementation history rather than a real trust boundary.

Acceptance: one short friction log with concrete evidence. Do not implement speculative convenience before this exists.

Broader multi-participant dogfood — public-safe findings

A later round of broader dogfood exercised the same temporary-Room product with a mixture of Humans and independently running Agents for longer sessions and exposed two stabilization classes that short clean-machine tests did not make visible.

Only the generic product findings are recorded here. Do not attach private Room transcripts, participant names, host paths, credentials, provider-specific configuration, or other dogfood-specific content to this public issue.

Browser responsiveness under a longer active Room

As participant count and the active timeline grow, browser interaction can become sluggish: typing and unrelated Room controls may both feel delayed.

The current Durable Object already keeps the ordinary Room message log bounded to a 100-message ring, so this is not evidence for a persistent chat archive or an immediate server-pagination project. A connected browser may still accumulate more live entries during a long session, and the React render path should be profiled before changing protocol/storage.

Tracked stabilization:

• perf(room): keep multi-participant Rooms responsive with longer timelines #280 — keep multi-participant Rooms responsive with longer timelines.

The product target is intentionally modest: ordinary low-double-digit Rooms and a few hundred mixed client-side timeline entries should remain comfortable. If the current bounded initial state is smooth after render isolation/indexing fixes, keep the simple one-shot initial Room state.

Agent Runtime artifact/setup reliability

Broader Harness combinations also exposed a few related Runtime-boundary gaps:

• a collaboration lifecycle can reference an already-existing attachment by id without the recipient Harness receiving the referenced content directly;
• Runtime-mediated participant commands must remain usable from the child Harness even when the bare free4chat-agent executable is absent or stale on PATH;
• an Invite must verify the actual Harness adapter backing the resulting resident rather than allowing infrastructure reuse to create a misleading Harness identity;
• ux(agent): let setup Agents safely inherit selected local Harness environment #276's --agent-env NAME mechanism works in production, but local failure UX can make the existing recovery path more discoverable when the missing variable name is safely known.

Tracked stabilization:

• stabilization(agent): harden artifact handoff and Harness setup after broader dogfood #281 — harden artifact handoff and Harness setup after broader dogfood.

Treat these as Runtime/setup reliability work, not reasons to add a central artifact store, global Agent identity, credential vault, or post-#223 architecture rewrite.

Headless Harness permission policy can block real work after join

The same broader dogfood exposed a distinct authorization/setup gap:

Harness joins successfully
→ collaboration begins
→ useful local tool action requires the Harness's normal Human approval
→ resident ACP has no interactive approval window
→ permission request cannot be completed
→ the turn is cancelled / useful work stops

This is not Room work authorization and not the #276 environment problem. The current Runtime intentionally fails closed on ACP permission requests, while built-in Harnesses have different native policy models. A participant can therefore look healthy at join time yet be unable to perform the work it was invited for.

Tracked security/UX follow-up:

• ux/security(agent): Room-native ACP approval for resident Harnesses #286 — preflight a Human-approved non-interactive Harness policy before Room join.

The intended product direction is setup-time preflight, not Room-time implicit approval:

Invite copied to setup Agent
→ inspect selected Harness's unattended policy behavior
→ explain available local/session policy choices
→ Human explicitly chooses/confirms
→ apply the narrowest truthful Harness-native policy
→ verify unattended readiness
→ join

Do not silently enable unrestricted access, do not treat Room messages/collaboration acceptance as local tool approval, and prefer per-resident/session policy over global Harness mutation where the Harness supports it.

Observed friction — local Harness configuration does not always survive Free4Chat launch

Clean-machine / real-agent dogfood exposed a general launcher configuration problem:

Agent/Harness already works locally
→ Free4Chat launches the built-in ACP bridge
→ Runtime applies the safe Harness environment filter
→ one locally required custom environment variable is not inherited
→ Agent joins the Room but cannot use its normal local model/provider configuration

This is not specific to one provider or one variable name. The tested credential was only one concrete example of a broader class:

A locally working Harness may depend on additional operator-defined environment variables that Free4Chat does not currently know about.

The current workaround is a trusted local ACP wrapper that obtains the required configuration locally and then execs the official ACP bridge. That is a valid escape hatch, but it is too much setup for the normal temporary-collaboration path: the operator must understand ACP wrappers, environment filtering, and --agent-command merely to reuse an already-working local Agent configuration.

Treat this as Experiment A evidence.

Completed implementation follow-up: #276 — safe named local environment inheritance for setup Agents, shipped in Agent v0.5.22.

Security constraint

Do not solve this by automatically inheriting the entire daemon / shell environment into every Harness subprocess.

Ambient environments can contain unrelated credentials and sensitive local configuration. A Harness is a powerful local process and may execute tools or shell commands; broad inheritance would unnecessarily enlarge the secret surface available to model-driven work.

Also avoid passing secret values through command-line arguments, Room messages, ACP prompts, or other user-visible/protocol surfaces.

Candidate direction — explicit named environment inheritance

If further dogfood confirms this class of friction, evaluate a narrow mechanism that lets the operator explicitly authorize environment variable names for one Agent launch, while the Runtime reads the values locally.

Conceptually:

operator authorizes env name(s)
→ local CLI/Runtime resolves only those names from local configuration
→ if the resident daemon needs the value, transfer it only over the restricted local IPC boundary and keep it in memory
→ only those values are added to the Harness subprocess environment
→ values never appear in Room state, ACP prompt, CLI output, logs, status, workspace files, or argv

Illustrative syntax only:

--agent-env <NAME>
--agent-env <NAME>

The exact UX should come from evidence. Do not commit to this flag name yet.

Preserve:

• the existing default safe allow-list for common launcher configuration;
• explicit opt-in for additional names;
• no wildcard / prefix-based inheritance by default;
• no secret values in argv;
• no Room/protocol exposure;
• no automatic inheritance of unrelated credentials;
• no persistence of inherited secret values in Runtime workspaces or config generated by Free4Chat;
• no logging or status projection of inherited values.

The exact value source needs evidence-driven design. A resident daemon may have an older process environment than the shell that invokes join, so a future implementation should not assume that daemon-start-time environment is always authoritative. It is acceptable for the local CLI to resolve an explicitly authorized variable from its current environment and pass the value through the existing restrictive local IPC boundary, provided the value is ephemeral/in-memory only and never enters Room or ACP-visible data.

If this remains a one-off edge case, a narrow launcher-specific allow-list update may be sufficient. If multiple real Harness/provider configurations hit the same problem, prefer a general explicit named-inheritance mechanism rather than continuously hard-coding individual provider keys.

Setup-agent discoverability and self-repair

The capability alone is insufficient. The fresh Invite / setup guidance should make this failure mode understandable to the Agent performing setup.

A setup Agent should be able to reason about this class of failure without being told provider-specific internals:

local Harness works outside Free4Chat
→ invited Harness fails to authenticate/configure
→ inspect whether required local environment configuration was filtered
→ identify the missing environment variable name locally
→ ask the operator to explicitly authorize that name, or reuse an already-authorized named inheritance mechanism
→ retry the join

The setup guidance should explicitly teach the safety boundary:

• never ask the Human to paste the secret value into Room chat or the ACP prompt;
• never put a secret value into --agent-arg, command-line KEY=value, logs, or status;
• it is acceptable to identify and discuss the variable name;
• use the supported local named-environment inheritance mechanism when available;
• if that mechanism is unavailable, explain the limitation and use the trusted local --agent-command wrapper only as an escape hatch.

This allows a Human to keep talking to the setup Agent after a failed invite. The Agent can diagnose the local configuration problem and produce a safe retry command rather than requiring the Human to understand Runtime environment filtering.

When a general named-environment mechanism is implemented, update the canonical fresh Invite bootstrap guidance (the live /agent.md contract and generated matching documentation) so setup Agents can discover and use it naturally.

Do not hard-code one provider or one secret name into the canonical prompt. Teach the generic reasoning pattern and security boundary instead.

A useful acceptance scenario is:

Human copies Invite prompt to setup Agent
→ Agent installs/verifies Runtime
→ Agent attempts join
→ Harness reports missing local configuration
→ setup Agent diagnoses a filtered environment variable
→ setup Agent safely authorizes only that variable name
→ retries join
→ participant becomes healthy

The Human should not have to write an ACP wrapper manually for the normal supported path.

Experiment B — peer visibility and addressing UX

Evaluate whether the post-join experience can become immediately legible.

Conceptually:

Room abc123

PEERS
Dawei              human
Hermes-MacMini      browser.authenticated, memory
Codex-MacBook       code.edit
Ops-VPS             production.logs

The exact UI/CLI shape should come from the current implementation.

#258 may improve browser-side participant presentation, but Experiment B remains specifically about discoverability and addressing semantics across Human/operator CLI and Agent use. Do not treat prettier participant cards as evidence that opaque-id friction or ambiguous name resolution is solved.

Questions:

1. Can a Human/operator see useful peers immediately after join?
2. Can Agents discover the same truthful roster/capability information?
3. Can Human-facing commands avoid requiring copied participantId values for ordinary interaction?
4. Can name-to-participant resolution be deterministic enough inside one temporary Room?
5. How are duplicate names handled without inventing permanent identity?
6. Can ambiguity fail clearly rather than guessing?

Protocol-level ids remain authoritative underneath. Do not weaken structured addressing or security boundaries merely to create prettier names.

Experiment C — invite / join handoff

Evaluate the smallest safe invitation flow for another Human or independently running Agent.

Preserve:

Room id = invitation coordinate
Room id != owner/admin credential
join != work authorization

Possible improvements may include clearer copy/paste output, one obvious Agent join command, or Human-facing Room URL + Agent-facing command shown together.

Do not add account-based contacts, persistent device enrollment, global Agent discovery, or public directories.

Experiment D — status after join

The local Runtime already behaves like a collaboration node. Evaluate whether status / join output should make that model more obvious without creating a permanent network abstraction.

Useful information may include:

• current Runtime Host;
• active temporary Rooms;
• resident participant names;
• Room-safe advertised capabilities;
• participation health / age already available from stabilization work.

Do not expose credentials, provider claims, private Harness state, or unrelated local processes.

Runtime architecture gate

A post-#223 Runtime refactor is not a prerequisite for this issue.

If Experiment A–D can be solved with presentation, CLI output, local name resolution, or other narrow UX changes, keep the proven Runtime/Harness delivery machinery untouched.

If measured friction genuinely requires changing retained delivery, ACP session/context semantics, transport receipt state, or other #223-sensitive Runtime behavior, stop before implementation and perform a focused post-#223 architecture review for that concrete change.

Do not create a generic HarnessDeliveryState / Runtime refactor merely because the current implementation is internally complex.

Acceptance

• clean-machine dogfood records the real current time/steps to first collaboration;
• no account, organization, project or permanent workspace is required;
• one machine can create a Room and another can join with a short Human-comprehensible handoff;
• post-join output makes current peers discoverable without inspecting raw protocol payloads;
• ordinary Human/operator interaction does not require manually reasoning about opaque participant ids when an unambiguous Room-local name is available;
• ambiguous/duplicate names fail explicitly rather than targeting the wrong participant;
• Agents still receive stable participant ids and truthful capability metadata for machine use;
• capability advertisement remains discovery only;
• one targeted conversational handoff and one structured request/result remain easy to execute;
• one bounded artifact can cross machines without shared filesystem setup;
• leaving produces no persistent Free4Chat workspace/network membership;
• browser-created and terminal-created Rooms remain the same product/domain;
• no new central identity, registry, planner, task database or credential service is introduced.

Non-goals

• persistent personal Agent network / "tailnet";
• account requirement;
• organization/team/workspace management;
• global Agent/device registry;
• Agent marketplace/social graph;
• remote shell, arbitrary TCP connectivity or VPN;
• remote desktop/control plane;
• daemon/device auto-enrollment;
• central credential vault;
• central planner/orchestrator;
• replacing A2A/MCP/ACP/networking standards;
• hiding protocol ids from machine-facing APIs;
• adding convenience syntax without measured friction.

Scheduling

#208 browser-optional cross-machine productization ✅
→ #223 retained context correctness ✅
→ #258 / #276 / #280 / #281 stabilization ✅
→ #286 / #296 / #297 Room approval + compatibility ✅
→ Agent v0.5.24 production baseline ✅
→ stop: no further speculative Agent-LAN UX layer justified

Future friction may open a new narrow issue with fresh evidence. Do not reopen this umbrella merely to accumulate unrelated onboarding ideas.

Related

• Core direction — temporary capability access and collaboration fabric #51 — canonical temporary collaboration fabric / Agent LAN north star.
• ux(cli): make temporary Rooms browser-optional for developer-native Human/Agent collaboration #208 — completed browser-optional developer-native Room entry.
• runtime(context): push realtime deltas to retained ACP sessions and let Harnesses pull bounded Room history #223 — completed retained ACP context delivery correctness; Agent v0.5.24 is the current production baseline.
• ui(room): refresh participant presence with retro sci-fi temporary-room language #258 — completed Room participant/presence presentation refresh.
• ux(agent): let setup Agents safely inherit selected local Harness environment #276 — completed setup-Agent named local environment inheritance, shipped in Agent v0.5.22.
• perf(room): keep multi-participant Rooms responsive with longer timelines #280 — completed browser responsiveness work from broader multi-participant / longer-timeline dogfood.
• stabilization(agent): harden artifact handoff and Harness setup after broader dogfood #281 — completed Agent Runtime artifact handoff + Harness setup stabilization from broader dogfood.
• experiment: A2A interoperability for Free4Chat Agent participants #160 — optional A2A interoperability experiment; task interoperability is separate from Room onboarding UX.