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

Status

EVIDENCE-BACKED AGENT RUNTIME STABILIZATION. Priority: high.

Broader multi-Harness dogfood has exposed several related reliability gaps around artifact consumption and setup/runtime truth.

This issue intentionally records only generic product behavior. Do not attach private Room transcripts, participant names, host paths, credentials, provider-specific secrets, or other dogfood-specific content.

The goal is to fix these together where they share the same Agent Runtime / Harness boundary and avoid a sequence of tiny releases.

Problem A — collaboration attachment references are not always directly consumable

Free4Chat already supports:

send_attachment
read_attachment
collab request attachmentIds
collab result attachmentIds

The Runtime also already enriches standalone attachment events into bounded Harness-visible text/image content.

The remaining gap is reference-only collaboration turns:

an attachment already exists in Room history
→ later collaboration request/result references only attachmentId
→ recipient Harness receives the collaboration lifecycle + id
→ actual referenced content may not be enriched into that turn
→ recipient cannot reliably act on the artifact

This is different from the previously proven upload-immediately-then-collab path, where the standalone attachment event may happen to be present in the same delivered context.

Required contract

For a collaboration request/result that contains attachmentIds:

Runtime sees referenced ids
→ Runtime resolves those ids through its existing private Room attachment path
→ bounded text/image content is attached to the collaboration turn
→ Harness can consume the artifact without receiving Room credentials

Preserve current attachment limits, supported MIME types, image capability negotiation, fail-open unavailable behavior, and all existing Room authorization.

Regression shape

The test must separate creation time from collaboration time:

upload attachment
→ allow its original standalone event to become older history
→ later send a new collab request/result that carries only attachmentId
→ recipient still receives the actual bounded artifact content

Do not make this pass only because the original attachment event happens to be in the same realtime batch.

Problem B — Runtime-mediated participant commands must not depend on shell PATH luck

The Harness bootstrap currently teaches Runtime-owned local participant commands such as:

free4chat-agent context read
free4chat-agent collab ...
free4chat-agent attach ...
free4chat-agent surface ...

The fresh Invite bootstrap, however, deliberately resolves and verifies an exact Runtime executable path because the user's PATH may still point at an old binary or not contain the install destination at all.

That exact-path principle must survive into the child Harness session.

A Harness that was launched successfully by the Runtime should not lose access to Runtime-mediated participant commands merely because the bare free4chat-agent command is absent or stale on PATH.

Required contract

Prefer a narrow, truthful Runtime-owned mechanism:

Runtime knows the exact executable that owns this resident
→ Harness bootstrap receives a safe exact participant-command path or equivalent
→ context / collab / attach / surface commands target this exact Runtime executable

Do not expose participant handles/tokens/cursors or invent a new public local service.

Do not silently fall back to another binary found on PATH after the Runtime has already established an exact executable identity.

Problem C — Invite / resident Harness identity must never become misleading

A fresh Invite is expected to detect the Harness it is running under and launch the corresponding ACP adapter.

Reuse is allowed for infrastructure such as:

installed Runtime binary
resident daemon

but a resident Agent launched through one Harness adapter must not silently satisfy an Invite that expects a different Harness.

The exact failure layer must be reproduced before changing lifecycle code. It may be setup/prompt selection, daemon/runtime reuse logic, or insufficient status verification.

Required invariant

expected Harness = X
actual resident Harness = Y
X != Y
→ never claim the Invite succeeded as X

The setup Agent must be able to verify the actual adapter/Harness identity of the resident it just created or selected.

If current status / readiness output is insufficient, make the smallest truthful local-only projection necessary. Harness identity is diagnostic/runtime-local metadata, not a Room capability and not a permanent Agent identity.

Do not introduce global Agent identity, accounts, device enrollment, or Harness migration.

Problem D — named environment inheritance works, but setup recovery can be more actionable

Agent v0.5.22 shipped explicit named local environment inheritance:

--agent-env NAME

The mechanism is working and #276 remains completed.

Do not reopen or redesign that feature.

Where the Runtime/Harness failure path can safely identify a missing local environment variable name, improve the local setup error/hint so the setup Agent can discover the existing recovery path without Human knowledge of Runtime internals.

Conceptually:

Harness normally works locally
→ Free4Chat launch reports missing local variable NAME
→ setup guidance suggests retry with --agent-env NAME

Never print the value.

Never guess secret names from provider prefixes.

If the missing variable name cannot be determined safely and deterministically, keep the existing generic guidance rather than building a provider-specific classifier.

Security / architecture boundaries

Preserve:

• Runtime owns the raw Room connection, participant capability, attachment reads and local participant-command routing;
• Harness receives only sanitized/bounded Room context and explicitly enriched artifacts;
• ACP remains lifecycle/control, not a sandbox;
• Harness/local operator policy remains final authority over local tools;
• no Room credential reaches the Harness;
• no arbitrary shell environment inheritance;
• no secret value in argv, Room text, prompt, status, workspace, or logs;
• no persistent credential store;
• no new shared filesystem/artifact service;
• no central planner/orchestrator;
• no runtime(context): push realtime deltas to retained ACP sessions and let Harnesses pull bounded Room history #223 retained-context redesign unless a concrete regression proves it necessary.

Implementation guidance

Prefer one focused Agent Runtime implementation PR and one subsequent native release/activation sequence if these fixes remain cohesive.

Likely areas:

agent/internal/runtime/**
agent/internal/harness/**
agent/internal/daemon/**
agent/internal/cli/**
agent/internal/types/** only if necessary
app/public/agent.md / generated docs only during the normal post-release activation phase
app/src/common/agentInvite.ts only if setup verification/recovery wording needs activation changes

Do not advertise unreleased CLI/runtime behavior in live bootstrap docs.

For the Harness identity problem, reproduce and locate the exact failing layer first. Do not refactor resident lifecycle based only on the symptom.

Acceptance

Artifact handoff

• an old/existing Room attachment referenced later only by collab attachmentIds is directly consumable by the recipient Harness;
• both request and result attachment references are covered where the lifecycle supports them;
• text-like content remains bounded;
• supported images respect negotiated image support and current per-turn limits;
• unknown/evicted/unreadable references fail safely without breaking unrelated collaboration context;
• no Room credential is exposed to the Harness.

Exact Runtime command path

• a child Harness can use Runtime-mediated context, collab, attach, and surface commands even when the bare Runtime binary is absent from PATH;
• participant commands target the exact compatible executable that owns the resident;
• stale/different PATH binaries are not silently selected.

Harness identity

• Invite/setup can verify which Harness adapter backs the resulting resident;
• a resident using Harness Y cannot be silently presented as satisfying an Invite for Harness X;
• same-daemon multiple resident Agents with different supported Harnesses remain valid;
• no permanent/global identity layer is added.

Environment recovery

• existing --agent-env NAME behavior remains unchanged and secure;
• where a missing variable name is safely known, the setup failure path makes the existing named-inheritance retry discoverable;
• no secret value is printed or persisted;
• no provider-specific secret name is hard-coded into canonical guidance.

Regression

• existing targeted Room turns and retained ACP session behavior remain intact;
• existing context read, structured collab, attachment upload, result correlation, reconnect/rejoin and leave behavior remain green;
• no Room/MCP/SFU/media protocol redesign is introduced.

Release sequencing

If implementation changes the native Runtime, follow:

implementation PR
→ source-version PR
→ verified native GitHub Release
→ separate bootstrap/docs activation PR
→ production verification / dogfood

Do not activate docs before the released binary supports the behavior.

Non-goals

• generic arbitrary attachment download API for untrusted Harnesses;
• exposing raw MCP tools or participant handles to Harnesses;
• shared filesystem;
• persistent artifact archive;
• auto-migrating an existing resident between Harness adapters;
• global Agent identity / device registry;
• provider-specific credential logic;
• reopening ux(agent): let setup Agents safely inherit selected local Harness environment #276;
• broad Runtime refactor without a demonstrated need.

Related

• ux(agent): minimize time-to-collaboration for a temporary Agent LAN #246 — time-to-collaboration / real dogfood tracking.
• dogfood: make resident Agents discover and use existing Room artifact handoff #192 — completed cross-machine artifact proof; this issue adds the stricter reference-only regression that broader dogfood exposed.
• runtime(context): push realtime deltas to retained ACP sessions and let Harnesses pull bounded Room history #223 — retained Harness context baseline; preserve unless a concrete failing layer requires review.
• ux(agent): let setup Agents safely inherit selected local Harness environment #276 — completed named local environment inheritance in Agent v0.5.22.