Portal

Portal

Portal moves a local coding session to a paired computer while keeping the relay as the control plane and the paired computer as the execution residence. The Code Agents chat list supports moving one local chat or all eligible local and worktree chats in one handoff.

Workflow

1. Select Portal for the coding session and keep the source folder as a Git repository with an origin remote.
2. Snapshot the current working tree, including dirty tracked and untracked code, into a unique portal/<timestamp>-<id> branch. Do not switch, reset, stash, or overwrite the source checkout.
3. Queue the run for a paired active host. The run metadata must identify the host, handoff id, branch, commit, and envPolicy: "load-local".
4. On the paired host, fetch the exact commit into a detached Portal worktree under its local Agent-Native store. Preserve an existing dirty worktree and create a new one instead of overwriting it.
5. Load the paired host's current local environment files immediately before starting the runner. Never put environment values, tokens, or secrets in relay metadata, prompts, transcripts, or status messages.

Existing chat transfer

Use Move to Portal for one chat or Move local chats to Portal for the bulk handoff. The transfer stops a local runner before snapshotting, pushes the current worktree without changing the source checkout, and imports the full text transcript into the same run id on the paired computer. The target gets a continuation turn rather than replaying the original prompt. Chats waiting for local approval are skipped because approval state is computer-local and cannot be reconstructed safely.

Binary attachment bodies are not relayed. Their names, text, and an explicit omission marker remain in the transcript context. Oversized or otherwise unsafe context fails visibly so the source chat can be retried instead of being silently truncated.

Execution residence

Treat metadata.executionResidence as authoritative for where the run is executing. It should report kind: "portal", host id and label, handoff id, source commit, remote workspace path once prepared, and environment file names without values. Follow-ups and stops must target the same host and remote run.

Verification

Before saying Portal is ready, verify the relay has a paired host, the host is heartbeating, the exact handoff commit was fetched, the detached worktree is clean, and the run metadata reports the remote workspace. For an existing chat, also verify the target transcript contains the imported event count and the continuation turn. A queued command is not proof that the remote runner started; inspect the remote result or event readback.

Operator recovery

When a host is present but a handoff stalls:

1. Confirm the connector's relayUrl is the same deployment origin used for pairing. A device paired against another origin can return 401 with a fresh-looking token because the row is in a different database.
2. After repairing a pairing, restart the connector. It reads remote-device.json once at startup and will not adopt a new token or relay URL in an existing process.
3. Confirm the host is heartbeating and connected, then retry one bounded run. Read the remote result and transcript; enqueue success alone is not proof.
4. Keep tokens and environment values out of logs, prompts, metadata, and transcripts. Report source, published-runtime, and live-relay evidence separately.

Don't

• Do not copy .env contents or credentials to the source branch or relay.
• Do not treat the primary laptop's cwd or environment as the remote cwd.
• Do not report Portal complete from a local push alone; confirm remote execution residence and runner state.

Related skills

• external-agents - relay and external-agent boundaries.
• a2a-protocol - idempotent cross-agent task lifecycle.
• concurrent-agents - preserve shared checkouts and peer work.
• reliable-mutations - verify durable handoff state.