| name | sot-fe-session-start |
| description | Bootstrap a frontend-side Codex session for Ship of Tools. Use in a local FE terminal/Codex session to set the win-fe handle, send through the local SSH tunnel to the backend Unix socket, read the frontend-local fe-inbox, and coordinate with backend sessions without relying on old remote TCP. |
sot-fe-session-start
Run this on the frontend machine. The FE machine usually has its own filesystem
and registry, so do not expect a local comm-join.sh to create a backend-host
registry row.
Handle
Match the native frontend handle:
PowerShell:
$hostName = if ($env:HOSTNAME) { $env:HOSTNAME } elseif ($env:COMPUTERNAME) { $env:COMPUTERNAME } else { "unknown" }
$env:SOT_COMM_NAME = "win-fe-$($hostName.ToLowerInvariant())"
Bash:
export SOT_COMM_NAME="win-fe-$( (hostname -s 2>/dev/null || hostname || printf unknown) | tr '[:upper:]' '[:lower:]' )"
If ~/.sot-comm/bin is installed locally, join with that name so outbound relay
messages have the right from::
~/.sot-comm/bin/comm-join.sh --name "$SOT_COMM_NAME"
Endpoint
The backend is socket-only by default. The frontend sends through a local TCP
tunnel that forwards to the remote Unix socket:
PowerShell:
$port = if ($env:SOT_PORT) { $env:SOT_PORT } else { "18743" }
$env:SOT_RELAY_ENDPOINT = "tcp:127.0.0.1:$port"
Bash:
export SOT_RELAY_ENDPOINT="tcp:127.0.0.1:${SOT_PORT:-18743}"
Do not probe remote 127.0.0.1:18743. Query the remote socket with
sotd session-socket-path sot and forward local 18743 to that socket.
Inbox
The native frontend appends daemon agent.message events to:
- Windows:
%LOCALAPPDATA%\sot\fe-inbox.jsonl
- Linux/macOS FE:
${XDG_STATE_HOME:-$HOME/.local/state}/sot/fe-inbox.jsonl
Codex FE sessions do not automatically get a tmux codex-watch.sh wake unless
they are running inside tmux. At turn start, or when told there is FE backlog,
read the local FE inbox and answer via comm-relay.sh.
The daemon broadcasts every agent.message to ALL connected FEs; the to
field is an advisory label, not enforced routing. Treat as addressed to you:
to:<your handle> or the bare to:win-fe family label ("any FE"). Lines aimed
at another handle (a sibling win-fe-<otherhost>, backend-dev) and true
broadcasts (to:"") are FYIs — anything broadcast that matters is also on the
durable git-bus (/bus-sync).
PowerShell backlog check:
$inbox = Join-Path $env:LOCALAPPDATA "sot\fe-inbox.jsonl"
if (Test-Path $inbox) { Get-Content $inbox -Tail 40 }
Bash backlog check:
state="${XDG_STATE_HOME:-$HOME/.local/state}/sot"
[ -n "${LOCALAPPDATA:-}" ] && state="$LOCALAPPDATA/sot"
[ -f "$state/fe-inbox.jsonl" ] && tail -40 "$state/fe-inbox.jsonl"
Ping BE
If the backend handle is known:
~/.sot-comm/bin/comm-relay.sh send @<be-handle> "[$SOT_COMM_NAME] FE relay path armed; please ack."
If no direct route exists yet, use the human-provided temporary dropbox only for
that live incident; never commit private machine paths or secrets to the repo.
