# Beam work to Outpost

> /beam hands unfinished local work to a new one-shot Outpost session. /beam back brings the completed branch and return brief into the current local session. /handoff is an exact alias.

`/beam` hands unfinished local work to a new one-shot Outpost session.
`/beam back` brings the completed branch and return brief into the current local
session. `/handoff` is an exact alias.

<!-- SOURCE: src/kin/harness/session/roundtrip.py, src/kin/harness/beam.py, src/kin/harness/defaults/commands/beam.md, src/kin/harness/tools/outpost.py, src/kin/tui/commands/beam.py, src/kin/tui/modals/beam.py, src/kin/tui/beam_card.py, container/dashboard/inbox.py, container/dashboard/v1_profiles.py -->

## Outcome

Move one bounded task from the local TUI to Outpost, see exactly which branch,
workspace, profile/model, and effort will be used, then verify the returned work
locally.

## Fast path

1. Work on a feature branch; Beam never targets `main` or `master`.
2. Run `/beam` with an optional focus hint.
3. Review the detected workspace, branch, local changes, and editable handoff
   brief.
4. Confirm the Outpost execution profile/model and effort.
5. Continue to the consequential-action confirmation and approve the commit,
   branch push, and Outpost submission.
6. Follow the durable Beam card until it is ready or needs you.
7. Run `/beam back` to pull the branch, read the return brief, and verify its
   claims against the local diff and history.

[![Kin Beam handoff review showing a feature branch, Outpost workspace, execution profile, bounded brief, and confirmation actions.](/docs-assets/kin/assets/screenshots/beam_handoff.svg)](/docs-assets/kin/assets/screenshots/beam_handoff.svg)

*Beam makes the remote boundary explicit before it commits, pushes, or creates
the Outpost job.*

```text
local session → commit + push → new Outpost job → same branch checkpoints
      ↑                                            |
      └──── /beam back ← return brief + pull ─────┘
```

This is sequential handoff, not remote attachment: one surface owns the work at
a time. The remote session receives a self-contained brief rather than the
local journal.

## What the review protects

The native screen fills asynchronously as Git and Outpost checks settle. If the
current model matches an execution profile, Kin selects it and says whether the
endpoint matched exactly. Otherwise the server-default fallback is visible;
the handoff never silently claims it will use the local model. Remote profile,
model, and effort labels render as literal text while their exact server values
remain the submitted selection.

Cancel is focused at the final confirmation. The reviewed operation becomes
one immutable plan, including its Outpost request and idempotency identity. If
commit, push, or submission fails, Kin retains that plan in the live session.
Reopen bare `/beam`, review the prepared retry, and Kin reuses the same request,
identity, and prepared commit; intervening local changes stop the retry instead
of silently widening it. Supplying a new focus starts a new plan. A successful
submission leaves a durable card with queued, working, needs-you, ready, failed,
unreachable, unknown, or returned state.

## Answering remote gates

A needs-you Beam card can answer an Outpost question or a typed approval
without leaving Kin. Remote authorizations offer **Approve**, **Deny**, **Deny
with note**, or **Cancel**—never a session-wide Always grant.

Approval for the exact root `git-push` carries one short-lived, single-use
authorization into the continuation. Changed arguments, a repeated call, or a
subagent push asks again. Other answers resume the model with context but do
not pre-authorize a tool.

An answer is usable only while that exact halt still owns the job. Cancelling
the Beam, starting a newer run, or reaching a later halt permanently retires
older Inbox actions and any unspent approval they carried. They remain visible
as history, but both the dashboard and machine answer doors reject them. An
item containing several approval questions is deliberately unanswerable:
Beam never treats one generic **Approve** as permission for a bundle.

## Returning work

Without an id, `/beam back` uses the newest local Beam record for the current
folder; Outpost remains the lifecycle authority. A successful report is
treated as unverified input. The prompt path calls the typed return controller
through the always-ask `outpost-send return` action. That controller requires
the locally recorded job and feature branch to match Outpost, requires a clean
checkout already on that branch, fetches the report, and uses a fast-forward-only
pull. Only after it can count the new commits does it persist and emit
`beam_returned`; Kin then summarizes the report and checks its claims against
the local log and diff.

On a halted job, Beam pulls a partial checkpoint only when you explicitly ask;
the return action carries `partial=true` and labels the durable result partial.
Answering the remote gate and returning partial work remain separate actions.

## Alternative methods

#### Prompt fallback


Set `beam_native = false` or `KIN_BEAM_NATIVE=0` to retain the
prompt-command flow. Headless clients use it automatically. The separate
commit/push and Outpost-submit approvals remain visible.

#### Specific return


Run `/beam back <job-id>` when several handoffs exist for the same project.

#### Inspect in Outpost


Open the Beam card's job detail to read Activity, run evidence, and any
needs-you item before returning the branch.

## One-time setup

Beam needs an Outpost project cloned from GitHub plus a service identity with
operator read access and mutation constrained to the intended workspace. Set
global `outpost_url` and `outpost_token` (or their `KIN_*` environment
variables). Execution profiles and secrets remain on Outpost; Beam submits
only a profile/model reference.

Issuer URLs, oauth2-proxy redirects, service creation, workspace ACLs, the
durable live-gate identity, and credential rotation are operator work. Follow
[Outpost operations](/docs/kin/internals/outpost-operations/) rather than copying
deployment values into a user session.

## Troubleshooting

- **No matching workspace:** clone the repository in Outpost and confirm its
  project slug.
- **No profile matches:** choose the visible server default or fix the remote
  provider catalogue; Beam will not pretend the endpoints match.
- **Branch pushed but the response was lost:** reopen bare `/beam` in the same
  live session. The prepared retry keeps the original idempotency identity, so
  a job accepted before the response was lost resolves to that same job rather
  than duplicating it.
- **Beam return refuses the checkout:** switch to the locally recorded feature
  branch and settle local changes. Return is fast-forward-only and never merges
  through a dirty or different branch.
- **A card needs you:** open it and answer the exact remote question or
  authorization. Do not grant a broader local session permission.
- **The return brief overstates the work:** trust the pulled branch and local
  verification, not the prose.

## Reference

- [Outpost overview](/docs/kin/guide/outpost/)
- [Automations](/docs/kin/guide/scheduled-jobs/)
- [Modes & approvals](/docs/kin/guide/modes-and-permissions/)
- [Outpost operations](/docs/kin/internals/outpost-operations/)
- [Protocol](/docs/kin/protocol/)