feat(setup-repo): repo-aware summaries + GH_TOKEN setup, DRY token storage

Improve the setup-repo shell flow's operator UX:

* Open with two bulleted lists — what we know about the repo (name +
  local-checkout vs GitHub-remote, classified from the repo's git URL) and
  what its setup entails (Claude credential always; GH_TOKEN for GitHub repos).
* Add a GH_TOKEN step (GitHub repos only): interactive `gh auth login`, then
  capture via `gh auth token` and write it into the env-file — mirroring the
  Claude-token step, with a graceful fallback when `gh` isn't on the host.
* DRY the env-file write: generalize `store_oauth_token` into
  `store_env_token <VAR> <token> <file>`, the one implementation both tokens
  share (comment out the active line, drop the placeholder stub, append).
* Turn the closing summary into a bullet-per-step list.
* Fold in PR #309's hint wording (detach reassurance + actionable drop).

To classify local vs GitHub the script needs the repo's git URL, so the
ShellRunner now exports PANOPTICON_REPO_NAME / PANOPTICON_REPO_GIT_URL (passed
through by the spawner from the repo record).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: Panopticon Agent

src/panopticon/sessionservice/shell_runner.py

@@ -69,6 +69,8 @@ def spawn(
         env_file: str | None = None,
         script: str = "",
         workdir: str | None = None,
+        repo_name: str | None = None,
+        git_url: str | None = None,
         progress: Callable[[LifecyclePhase], None] | None = None,
     ) -> str:
         """Run ``script`` for ``task_id`` in a fresh host tmux session; return the session name.
@@ -79,7 +81,9 @@ def spawn(
         workflow's own override. ``workdir`` falls back to the operator's home only when unset (direct
         use). The pane runs ``sh -c`` with ``PANOPTICON_SERVICE_URL`` and ``PANOPTICON_TASK_ID``
         exported — so the script can drive its own lifecycle over REST (e.g. advance to COMPLETE on
-        success) — and the repo's ``env_file`` secrets sourced first when given. ``env_file`` is a
+        success), ``PANOPTICON_REPO_NAME`` / ``PANOPTICON_REPO_GIT_URL`` exported when given (so a
+        shell workflow can tailor its flow to the repo — e.g. classify local vs GitHub) — and the
+        repo's ``env_file`` secrets sourced first when given. ``env_file`` is a
         **name relative to this runner's secrets dir** (ADR 0007), resolved host-locally (like
         ``LocalRunner``) so a remote runner uses its own host's secrets. The panopticon shell lib
         (``panopticon_advance``/``_drop``/…) is loaded into the shell so the script can drive its task
@@ -115,6 +119,13 @@ def _report(phase: LifecyclePhase) -> None:
             # Load the panopticon shell lib so the script can drive its task (panopticon_advance, …).
             _TASK_LIB,
         ]
+        # Expose what we know about the repo so a shell workflow can tailor its flow — e.g. setup-repo
+        # classifies local vs GitHub from the git URL to decide whether a GH_TOKEN is needed. Omitted
+        # when unset (direct use), so the script sees the vars unset.
+        if repo_name:
+            lines.append(f"export PANOPTICON_REPO_NAME={shlex.quote(repo_name)}")
+        if git_url:
+            lines.append(f"export PANOPTICON_REPO_GIT_URL={shlex.quote(git_url)}")
         # Resolve the env_file *name* to an absolute path under this host's secrets dir, expose the
         # path (so a script can tell the operator where to add their own credential), then source it
         # if it exists (a not-yet-created secrets file is fine — the script sees the vars unset).

src/panopticon/sessionservice/spawner.py

@@ -260,6 +260,10 @@ def _spawn_shell(self, task: JsonObj, repo: JsonObj) -> str:
             env_file=repo.get("env_file"),  # per-repo secrets, sourced into the shell (ADR 0007)
             script=spec["script"],
             workdir=workdir,
+            repo_name=repo.get(
+                "name"
+            ),  # so the script can name the repo + classify local vs GitHub
+            git_url=repo.get("git_url"),
             progress=lambda phase: self._report(task_id, phase),  # STARTING then AWAITING
         )
 

src/panopticon/workflows/setup_repo.sh

@@ -1,30 +1,80 @@
-# Collect a Claude auth token (`claude setup-token`) for the repo's env-file. Run by the session
-# service in a host tmux session (no container); ShellRunner sources the repo's env-file first, so an
-# already-configured credential shows up as an env var, and exports PANOPTICON_ENV_FILE (its path).
+# Guide the operator through a repo's host-side setup: mint a Claude auth token (`claude
+# setup-token`) and — for a GitHub repo — a `GH_TOKEN` (`gh auth login`), writing each into the
+# repo's env-file. Run by the session service in a host tmux session (no container); ShellRunner
+# sources the repo's env-file first (so an already-configured credential shows up as an env var) and
+# exports PANOPTICON_ENV_FILE (its path), plus PANOPTICON_REPO_NAME / PANOPTICON_REPO_GIT_URL.
 #
-# Whatever route the operator takes, the script converges on a summary + a prompt to press Enter,
-# which completes the task and returns them to the dashboard.
+# Whatever route the operator takes, the script converges on a bulleted summary + a prompt to press
+# Enter, which completes the task and returns them to the dashboard.
 
 env_file="${PANOPTICON_ENV_FILE:-the repo's env-file}"
+repo_name="${PANOPTICON_REPO_NAME:-this repo}"
+repo_url="${PANOPTICON_REPO_GIT_URL:-}"
+repo_label=$(repo_source_label "$repo_url")
 
 # How to get back to the dashboard: detach from this tmux session. Detect the prefix + detach key
 # from the running server (the operator may have rebound them), falling back to the tmux defaults.
 prefix=$(tmux show-options -gv prefix 2>/dev/null)
 [ -n "$prefix" ] || prefix="C-b"
 detach=$(tmux list-keys -T prefix 2>/dev/null | awk '$NF == "detach-client" { print $(NF - 1); exit }')
 [ -n "$detach" ] || detach="d"
-dashboard_hint="To return to the dashboard without finishing, detach: press $prefix then $detach (the task stays running)."
+dashboard_hint="To return to the dashboard without finishing, detach: press $prefix then $detach (you can resume this task any time from the dashboard)."
 
 # Show how to get back to the dashboard up front, before anything else.
 echo "$dashboard_hint"
 echo
 
+# Work out what's already configured and what setting this repo up entails. The Claude credential is
+# always needed (the agent runs `claude` regardless); a GH_TOKEN is only needed for a GitHub remote
+# (a local checkout has nothing to push).
+claude_configured=0
+if [ -n "${CLAUDE_CODE_OAUTH_TOKEN:-}" ] || [ -n "${ANTHROPIC_API_KEY:-}" ]; then
+    claude_configured=1
+fi
+gh_needed=0
+gh_configured=0
+if repo_is_github "$repo_url"; then
+    gh_needed=1
+    [ -n "${GH_TOKEN:-}" ] && gh_configured=1
+fi
+
+# What we know about the repo, and what its setup entails — two bulleted lists up front.
+echo "This repo:"
+echo "  • Name: $repo_name"
+echo "  • Source: $repo_label"
+echo
+echo "To set up:"
+if [ "$claude_configured" -eq 1 ]; then
+    echo "  • Claude credential — already configured"
+else
+    echo "  • Claude credential — needed"
+fi
+if [ "$gh_needed" -eq 1 ]; then
+    if [ "$gh_configured" -eq 1 ]; then
+        echo "  • GH_TOKEN — already configured"
+    else
+        echo "  • GH_TOKEN — needed (GitHub repo)"
+    fi
+else
+    echo "  • GH_TOKEN — not needed (not a GitHub repo)"
+fi
+echo
+
+# The closing summary is a bullet per step; each step appends its outcome here.
 summary=""
+add_summary() {
+    if [ -z "$summary" ]; then
+        summary="  • $1"
+    else
+        summary="$summary
+  • $1"
+    fi
+}
 
-# Mint a token and record the outcome in $summary. On success, capture the minted token and write it
-# straight into the repo's env-file (commenting out any previous one — see store_oauth_token); fall
+# Mint a Claude token and record the outcome. On success, capture the minted token and write it
+# straight into the repo's env-file (commenting out any previous one — see store_env_token); fall
 # back to on-screen copy instructions when it can't be captured or there's no env-file to write to.
-# extract_oauth_token / store_oauth_token come from setup_repo_lib.sh (prepended by shell_script()).
+# extract_oauth_token / store_env_token come from setup_repo_lib.sh (prepended by shell_script()).
 collect_token() {
     echo
     echo "Running 'claude setup-token' — follow the prompts to mint a token."
@@ -49,36 +99,73 @@ collect_token() {
     fi
 
     if [ "$_ct_ok" -eq 0 ]; then
-        summary="'claude setup-token' failed or was cancelled — no token was collected."
+        add_summary "Claude credential: 'claude setup-token' failed or was cancelled — nothing collected."
     elif [ -n "$_ct_token" ] && [ -n "${PANOPTICON_ENV_FILE:-}" ] \
-        && store_oauth_token "$_ct_token" "$PANOPTICON_ENV_FILE"; then
+        && store_env_token CLAUDE_CODE_OAUTH_TOKEN "$_ct_token" "$PANOPTICON_ENV_FILE"; then
         echo
         echo "Wrote the new token to $env_file as CLAUDE_CODE_OAUTH_TOKEN (any previous one was commented out)."
-        summary="Minted a new token and wrote it to $env_file (any previous token was commented out)."
+        add_summary "Claude credential: minted a new token and wrote it to $env_file (any previous one was commented out)."
     else
         # Minted, but we couldn't capture/extract it or there's no env-file configured — guide the copy.
         echo
         echo "Token minted. Copy the token shown above into $env_file as:"
         echo "    CLAUDE_CODE_OAUTH_TOKEN=<token>"
-        summary="Minted a new token — copy it into $env_file as CLAUDE_CODE_OAUTH_TOKEN."
+        add_summary "Claude credential: minted a new token — copy it into $env_file as CLAUDE_CODE_OAUTH_TOKEN."
     fi
 }
 
-if [ -n "${CLAUDE_CODE_OAUTH_TOKEN:-}" ] || [ -n "${ANTHROPIC_API_KEY:-}" ]; then
+# Authenticate to GitHub and record the outcome — mirrors collect_token. Run the interactive
+# `gh auth login`, then capture the resulting token with `gh auth token` and write it into the repo's
+# env-file via the shared store_env_token. Falls back to on-screen guidance when `gh` isn't installed
+# or the token can't be captured/written.
+collect_gh_token() {
+    if ! command -v gh >/dev/null 2>&1; then
+        echo
+        echo "The 'gh' CLI isn't installed on this host, so I can't run 'gh auth login'."
+        echo "Add a token to $env_file yourself instead:"
+        echo "    GH_TOKEN=<a GitHub token, e.g. from 'gh auth token' or a personal access token>"
+        add_summary "GH_TOKEN: 'gh' not installed — add GH_TOKEN to $env_file yourself."
+        return
+    fi
+    echo
+    echo "Running 'gh auth login' — follow the prompts to authenticate to GitHub."
+    echo
+    _gt_ok=1
+    gh auth login || _gt_ok=0
+    _gt_token=""
+    [ "$_gt_ok" -eq 1 ] && _gt_token=$(gh auth token 2>/dev/null)
+
+    if [ "$_gt_ok" -eq 0 ]; then
+        add_summary "GH_TOKEN: 'gh auth login' failed or was cancelled — nothing collected."
+    elif [ -n "$_gt_token" ] && [ -n "${PANOPTICON_ENV_FILE:-}" ] \
+        && store_env_token GH_TOKEN "$_gt_token" "$PANOPTICON_ENV_FILE"; then
+        echo
+        echo "Wrote the token to $env_file as GH_TOKEN (any previous one was commented out)."
+        add_summary "GH_TOKEN: authenticated with gh and wrote the token to $env_file (any previous one was commented out)."
+    else
+        # Authenticated, but we couldn't read the token or there's no env-file — guide the copy.
+        echo
+        echo "Authenticated, but couldn't capture the token. Add it to $env_file yourself:"
+        echo "    GH_TOKEN=<token from 'gh auth token'>"
+        add_summary "GH_TOKEN: authenticated — copy 'gh auth token' into $env_file as GH_TOKEN."
+    fi
+}
+
+# --- Claude credential -------------------------------------------------------------------------
+if [ "$claude_configured" -eq 1 ]; then
     echo "A Claude credential is already configured in $env_file."
-    echo "To keep using it, drop this task instead (press 'x' in the dashboard)."
     echo
     printf 'Collect a new token anyway? [y/N] '
     read answer
     case "$answer" in
         [Yy]*) collect_token ;;
-        *) summary="Kept the existing credential in $env_file — nothing collected." ;;
+        *) add_summary "Claude credential: kept the existing one in $env_file — nothing collected." ;;
     esac
 else
     echo "No Claude credential found in $env_file."
     echo "About to collect one with 'claude setup-token'."
     echo
-    echo "Prefer to use your own? Drop this task (press 'x' in the dashboard) and add one of"
+    echo "Prefer to use your own? Press $prefix then $detach to go to the dashboard, drop this task using 'x' and add one of"
     echo "these to $env_file yourself:"
     echo "    CLAUDE_CODE_OAUTH_TOKEN=<token from 'claude setup-token'>"
     echo "    ANTHROPIC_API_KEY=<your Anthropic API key>"
@@ -88,11 +175,44 @@ else
     collect_token
 fi
 
-# Every route converges here: summarize what happened, then complete the task on Enter (which ends
-# the session and returns the operator to the dashboard; detaching instead — see the hint above —
-# leaves it running).
+# --- GH_TOKEN (GitHub repos only) --------------------------------------------------------------
+if [ "$gh_needed" -eq 1 ]; then
+    echo
+    if [ "$gh_configured" -eq 1 ]; then
+        echo "A GH_TOKEN is already configured in $env_file."
+        echo
+        printf 'Re-authenticate to GitHub anyway? [y/N] '
+        read answer
+        case "$answer" in
+            [Yy]*) collect_gh_token ;;
+            *) add_summary "GH_TOKEN: kept the existing one in $env_file — nothing collected." ;;
+        esac
+    else
+        echo "No GH_TOKEN found in $env_file — a GitHub repo needs one to push and open PRs."
+        echo
+        echo "Prefer to use your own? Press $prefix then $detach to go to the dashboard, drop this task using 'x' and add"
+        echo "    GH_TOKEN=<a GitHub token>"
+        echo "to $env_file yourself."
+        echo
+        printf 'Authenticate to GitHub with gh now? [Y/n] '
+        read answer
+        case "$answer" in
+            [Nn]*) add_summary "GH_TOKEN: skipped — add GH_TOKEN to $env_file yourself." ;;
+            *) collect_gh_token ;;
+        esac
+    fi
+fi
+
+# Every route converges here: summarize what happened (a bullet per step), then complete the task on
+# Enter (which ends the session and returns the operator to the dashboard; detaching instead — see
+# the hint above — leaves it running).
 echo
-echo "Summary: $summary"
+echo "Summary:"
+if [ -n "$summary" ]; then
+    echo "$summary"
+else
+    echo "  • Nothing to do — everything was already configured."
+fi
 echo
 printf 'Press Enter to complete this task and return to the dashboard. '
 read _

src/panopticon/workflows/setup_repo_lib.sh

@@ -10,34 +10,65 @@ extract_oauth_token() {
     grep -oaE 'sk-ant-oat01-[A-Za-z0-9_-]+' "$1" 2>/dev/null | tail -n 1
 }
 
-# Store a freshly minted token $1 into env-file $2, preserving history:
-#   * comment out any existing *active* `CLAUDE_CODE_OAUTH_TOKEN=…` line (kept as a record, not lost),
-#   * drop any placeholder *comment* stub (`# CLAUDE_CODE_OAUTH_TOKEN =`, or a `<…>` placeholder),
+# Store a freshly minted value $2 for env var $1 into env-file $3, preserving history:
+#   * comment out any existing *active* `<VAR>=…` line (kept as a record, not lost),
+#   * drop any placeholder *comment* stub (`# <VAR> =`, or a `<…>` placeholder),
 #   * append the new active line.
-# Other lines (ANTHROPIC_API_KEY, GH_TOKEN, blanks, unrelated comments) are left untouched. Atomic
-# replace, private perms (the file holds a live credential). Returns nonzero if it can't be written.
-store_oauth_token() {
-    _sot_token=$1
-    _sot_file=$2
-    [ -n "$_sot_file" ] || return 1
+# Other lines (a different var, blanks, unrelated comments) are left untouched. Atomic replace,
+# private perms (the file holds a live credential). Returns nonzero if it can't be written. Shared
+# by every token the setup flow writes (CLAUDE_CODE_OAUTH_TOKEN, GH_TOKEN, …). $1 must be a plain
+# env var name (`[A-Za-z_][A-Za-z0-9_]*`) — it's interpolated verbatim into the sed/grep patterns,
+# where it carries no regex metacharacters.
+store_env_token() {
+    _set_var=$1
+    _set_token=$2
+    _set_file=$3
+    [ -n "$_set_file" ] || return 1
     umask 077
-    mkdir -p "$(dirname "$_sot_file")" || return 1
-    _sot_tmp=$(mktemp "$_sot_file.XXXXXX") || return 1
-    if [ -f "$_sot_file" ]; then
+    mkdir -p "$(dirname "$_set_file")" || return 1
+    _set_tmp=$(mktemp "$_set_file.XXXXXX") || return 1
+    if [ -f "$_set_file" ]; then
         # 1) comment out an active assignment — a leading '#' means the line no longer starts with
-        #    the bare var name, so an already-commented real token (with an sk-ant-… value) is left
-        #    as-is; then 2) drop placeholder comment stubs (an empty or `<…>` value).
-        sed -E 's/^([[:space:]]*)CLAUDE_CODE_OAUTH_TOKEN=/\1# CLAUDE_CODE_OAUTH_TOKEN=/' "$_sot_file" \
-            | grep -vE '^[[:space:]]*#[[:space:]]*CLAUDE_CODE_OAUTH_TOKEN[[:space:]]*=[[:space:]]*(<[^>]*>)?[[:space:]]*$' \
-            > "$_sot_tmp" || true # grep exits 1 when it filters every line — that's fine
+        #    the bare var name, so an already-commented real value is left as-is; then 2) drop
+        #    placeholder comment stubs (an empty or `<…>` value).
+        sed -E "s/^([[:space:]]*)${_set_var}=/\\1# ${_set_var}=/" "$_set_file" \
+            | grep -vE "^[[:space:]]*#[[:space:]]*${_set_var}[[:space:]]*=[[:space:]]*(<[^>]*>)?[[:space:]]*\$" \
+            > "$_set_tmp" || true # grep exits 1 when it filters every line — that's fine
     fi
-    printf 'CLAUDE_CODE_OAUTH_TOKEN=%s\n' "$_sot_token" >> "$_sot_tmp" || {
-        rm -f "$_sot_tmp"
+    printf '%s=%s\n' "$_set_var" "$_set_token" >> "$_set_tmp" || {
+        rm -f "$_set_tmp"
         return 1
     }
-    mv "$_sot_tmp" "$_sot_file" || {
-        rm -f "$_sot_tmp"
+    mv "$_set_tmp" "$_set_file" || {
+        rm -f "$_set_tmp"
         return 1
     }
-    chmod 600 "$_sot_file" 2>/dev/null || true
+    chmod 600 "$_set_file" 2>/dev/null || true
+}
+
+# Back-compat wrapper: store a Claude OAuth token. The shared implementation lives in
+# store_env_token; this keeps the Claude call site (and its tests) reading clearly.
+store_oauth_token() {
+    store_env_token CLAUDE_CODE_OAUTH_TOKEN "$1" "$2"
+}
+
+# Classify a repo from its git URL ($1), for the setup flow's "what do we know / what's needed"
+# summary. `repo_is_github` returns 0 for a github.com remote — the case that needs a GH_TOKEN (a
+# local checkout has nothing to push). `repo_source_label` prints a human label.
+repo_is_github() {
+    printf '%s' "$1" | grep -qiE 'github\.com'
+}
+
+repo_source_label() {
+    if [ -z "$1" ]; then
+        printf 'unknown'
+    elif repo_is_github "$1"; then
+        printf 'GitHub remote'
+    elif printf '%s' "$1" | grep -qE '^(/|\./|\.\./|~|file://)' \
+        || ! printf '%s' "$1" | grep -qE '://|@'; then
+        # A filesystem path / file:// URL, or a bare ref with neither a scheme nor an scp-style host.
+        printf 'local checkout'
+    else
+        printf 'remote'
+    fi
 }

tests/sessionservice/test_shell_runner.py

@@ -74,6 +74,29 @@ def test_spawn_exports_service_env_and_runs_the_script() -> None:
     assert command.rstrip().endswith("claude setup-token")  # the workflow script runs last
 
 
+def test_spawn_exports_repo_name_and_git_url_when_given() -> None:
+    # So a shell workflow can tailor its flow to the repo (setup-repo classifies local vs GitHub from
+    # the git URL to decide whether a GH_TOKEN is needed).
+    rec = _Recorder()
+    ShellRunner("http://svc:8000", run=rec).spawn(
+        "t1",
+        script="echo hi",
+        repo_name="acme/widget",
+        git_url="https://github.com/acme/widget.git",
+    )
+    command = rec.calls[-1][-1]
+    assert "export PANOPTICON_REPO_NAME=acme/widget" in command
+    assert "export PANOPTICON_REPO_GIT_URL=https://github.com/acme/widget.git" in command
+
+
+def test_spawn_omits_repo_vars_without_them() -> None:
+    rec = _Recorder()
+    ShellRunner("http://svc:8000", run=rec).spawn("t1", script="echo hi")
+    command = rec.calls[-1][-1]
+    assert "PANOPTICON_REPO_NAME" not in command
+    assert "PANOPTICON_REPO_GIT_URL" not in command
+
+
 def test_spawn_loads_the_panopticon_shell_lib_before_the_script() -> None:
     # The shell lib (task_lib.sh) is injected so the workflow script can drive its task over REST
     # (panopticon_advance/_drop/…) instead of hand-rolling curl.