unsloth start: add --persist to keep and reopen agent sessions (#7014)

* unsloth start: add --resume to persist and reopen agent sessions

`unsloth start <agent>` launches a coding agent whose home is a throwaway
temp dir wiped on exit, so codex/openclaw/hermes/pi (which relocate their
whole home there) cannot resume a conversation after you quit. opencode and
claude keep their session data in a fixed user dir, so they already resume.

Add an opt-in --resume/--no-resume flag: it routes the launch to the stable
Unsloth agents dir (the same one --no-launch already uses) so the session
survives the exit, never touching the user's own ~/.<agent>. A bare --resume
also reopens the last conversation via the agent's native flag (codex
`resume --last`, opencode/claude/pi `--continue`). The default is unchanged:
a plain launch still uses a temp dir and persists nothing.

Add a dispatch-only `resume` job to the Local Agent Guides CI that drives the
real launch path and asserts the split: codex/pi are wiped without --resume
and persist with it, while opencode/claude persist either way.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* unsloth start: rename --resume to --persist

The session flag collided with agents' own resume flags. `unsloth start
claude --resume <id>` used to forward `--resume <id>` straight to Claude
(which keeps its history in ~/.claude regardless), so a boolean --resume on
unsloth start would have swallowed the session id and turned it into a stray
prompt. Name the persistence flag --persist instead, so every agent's native
resume flag (claude --resume <id>, codex resume, opencode --continue, ...)
still passes through untouched. Behavior is otherwise identical: --persist
keeps a launched agent's session under the Unsloth agents dir, and a bare
--persist reopens the last conversation.

Add a regression test that `--resume <id>` passes through verbatim, and in the
CI resume experiment skip the redundant second pass for opencode/claude (they
persist either way, and a second CPU turn only risks a timeout).

* unsloth start: correct --persist help and drop the buggy auto-resume

Reword the --persist help to be accurate: claude and opencode keep sessions in
the user's own stores and resume regardless, so --persist only stabilizes the
otherwise-ephemeral relocated home of codex/openclaw/hermes/pi. Drop the
bare-launch auto-append of native resume tokens: it errored on a first launch
with no prior session, and was inconsistent between launch and no-launch.
--persist now only keeps the session dir; resume via the agent's own command
(e.g. `unsloth start codex --persist resume`), which now finds it.

In the CI resume experiment, fail the pass when the launched turn exits
non-zero, so a write-then-error is not misread as PERSISTED.

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

.github/scripts/agent-guides-drive.sh

@@ -527,6 +527,154 @@ case "$MODE" in
     echo "[claude] attribution A/B OK (suppressed HIT, header=1 MISS)"
     ;;
 
+  # ── resume: does a launched agent's session survive exit and resume? ────
+  # Unlike the other modes, this drives the real LAUNCH path (`unsloth start
+  # <agent> ...`, the interactive default), not the --no-launch recipe. That
+  # path relocates each agent's home to a throwaway temp dir wiped on exit, so
+  # a session cannot be resumed -- unless --persist routes it to the stable
+  # Unsloth agents dir instead. We run one headless turn per pass and check
+  # whether the turn left a session in a persistent store (deterministic, no
+  # reliance on the model recalling anything), for a baseline pass and a
+  # --persist pass, and assert the expected split for this agent.
+  resume)
+    CODEWORD="PLATYPUS7"
+    T1="Remember this codeword for later: ${CODEWORD}. Reply with just the word OK."
+    T2="What codeword did I ask you to remember? Reply with just that word."
+    WORK="$WORKDIR_BASE/${AGENT}-resume"
+
+    # STABLE_HOME: the stable dir that --no-launch (and --persist) relocate to.
+    # Read it from a --no-launch probe (which also writes the agent's config
+    # there). codex/pi relocate their whole home/HOME here; opencode/claude keep
+    # their session data in a fixed user dir, so STABLE_HOME stays empty for them.
+    parse_connect
+    case "$AGENT" in
+      codex)    STABLE_HOME="$(raw_env CODEX_HOME)" ;;
+      pi)       STABLE_HOME="$(raw_env HOME)" ;;
+      *)        STABLE_HOME="" ;;
+    esac
+
+    # The persistent stores a session would land in if it were NOT wiped. We
+    # count files here before/after each turn; a positive delta means the
+    # session persisted (is resumable), zero means it went to a wiped temp dir.
+    resume_tracked_dirs() {
+      case "$AGENT" in
+        codex)    printf '%s\n' "$HOME/.codex" ;;
+        opencode) printf '%s\n' "$HOME/.local/share/opencode" "$HOME/.config/opencode" ;;
+        claude)   printf '%s\n' "$HOME/.claude" ;;
+        pi)       printf '%s\n' "$HOME/.pi" ;;
+        *)        : ;;
+      esac
+      [ -n "$STABLE_HOME" ] && printf '%s\n' "$STABLE_HOME"
+    }
+    count_session_files() {
+      local total=0 d n
+      while IFS= read -r d; do
+        [ -n "$d" ] && [ -d "$d" ] || continue
+        n="$(find "$d" -type f 2>/dev/null | wc -l)"; total=$((total + n))
+      done < <(resume_tracked_dirs)
+      echo "$total"
+    }
+
+    # The headless first-turn subcommand per agent (mirrors file-edit's map),
+    # forwarded verbatim through the launch path as passthrough args.
+    set_t1_cmd() {
+      case "$AGENT" in
+        claude)   T1_CMD=("${CLAUDE_CONNECT_FLAGS[@]}" -p "$T1") ;;
+        codex)    T1_CMD=(exec "$T1") ;;
+        opencode) T1_CMD=(run "$T1") ;;
+        pi)       T1_CMD=(-p "$T1") ;;
+        *)        guide_fail "resume mode does not cover agent '$AGENT'" ;;
+      esac
+    }
+
+    # Run one headless turn through the launch path. $1=outfile, $2="" or
+    # "--persist", rest = the agent subcommand. --yolo auto-approves so no tool
+    # prompt can hang; --api-key attaches to the already-served CI model.
+    launch_turn() {
+      local out="$1" rflag="$2"; shift 2
+      local flag=(); [ -n "$rflag" ] && flag=("$rflag")
+      run_timed "$out" unsloth start "$AGENT" "${flag[@]}" --yolo \
+        --api-key "$UNSLOTH_API_KEY" "$@"
+      local rc=$?
+      redact "$out"
+      return "$rc"
+    }
+
+    # One pass: fresh work dir, one planting turn, set RESULT to PERSISTED/WIPED
+    # from the session-store delta. Runs in the main shell (not a command
+    # substitution) so a hang's guide_fail actually fails the job and the
+    # progress lines reach the CI log. $1 = "" (baseline) or "--persist".
+    RESULT=""
+    run_pass() {
+      local rflag="$1" label="baseline"
+      [ -n "$rflag" ] && label="resume"
+      rm -rf "$WORK"; mkdir -p "$WORK"
+      set_t1_cmd
+      local out="$LOGS_DIR/${AGENT}-resume-${label}.txt"
+      local before after rc
+      before="$(count_session_files)"
+      pushd "$WORK" >/dev/null || guide_fail "could not enter work dir $WORK"
+      launch_turn "$out" "$rflag" "${T1_CMD[@]}"; rc=$?
+      popd >/dev/null || true
+      after="$(count_session_files)"
+      echo "[$AGENT] ${label}: session files ${before} -> ${after} (rc=${rc})"
+      # The turn must succeed for the delta to mean anything: an agent that writes a
+      # session file then errors would otherwise be misread as PERSISTED. Mirror the
+      # file-edit mode and fail the pass on a non-zero launch (the flagship codex recall
+      # below stays WARN-only, driven by its own launch_turn calls).
+      [ "$rc" -eq 0 ] || { echo "[$AGENT] ${label} transcript (tail):"; tail -30 "$out" 2>/dev/null || true; \
+        guide_fail "resume ${label} turn for ${AGENT} exited non-zero (rc=${rc})"; }
+      if [ "$after" -gt "$before" ]; then RESULT="PERSISTED"; else RESULT="WIPED"; fi
+    }
+
+    run_pass ""; BASELINE="$RESULT"
+    # Only the temp-dir agents (codex/pi) need the --persist pass to prove the fix.
+    # opencode/claude persist either way, so the baseline already proves it and a
+    # second full CPU turn only risks a timeout; skip it for them.
+    case "$AGENT" in
+      codex|pi) run_pass "--persist"; RESUME="$RESULT" ;;
+      *)        RESUME="n/a (persists either way)" ;;
+    esac
+
+    # Expected: codex/pi relocate their whole home to the temp dir, so a plain
+    # launch is WIPED and only --persist PERSISTS. opencode/claude keep their
+    # session data in a fixed user dir, so the baseline already PERSISTS.
+    case "$AGENT" in
+      codex|pi)        EXPECT_BASELINE="WIPED" ;;
+      opencode|claude) EXPECT_BASELINE="PERSISTED" ;;
+    esac
+
+    echo "──────────────────────────────────────────────"
+    echo "[$AGENT] RESUME EXPERIMENT"
+    echo "  baseline (unsloth start ${AGENT}):                 ${BASELINE}  (expected ${EXPECT_BASELINE})"
+    echo "  with --persist (unsloth start ${AGENT} --persist): ${RESUME}"
+    echo "──────────────────────────────────────────────"
+
+    [ "$BASELINE" = "$EXPECT_BASELINE" ] \
+      || guide_fail "baseline resume behavior for ${AGENT} was ${BASELINE}, expected ${EXPECT_BASELINE}"
+    case "$AGENT" in
+      codex|pi)
+        [ "$RESUME" = "PERSISTED" ] \
+          || guide_fail "--persist did not persist ${AGENT}'s session (got ${RESUME}); the session dir is still not stable" ;;
+    esac
+
+    # Flagship behavioral proof (codex only, WARN-only): after a --persist plant,
+    # resume the session and check the model actually recalls the codeword. A
+    # miss is not a failure (the CI model is small); the mechanism gate above is
+    # the real assertion.
+    if [ "$AGENT" = "codex" ]; then
+      rm -rf "$WORK"; mkdir -p "$WORK"
+      ( cd "$WORK" && launch_turn "$LOGS_DIR/codex-resume-plant.txt" "--persist" exec "$T1" ) || true
+      ( cd "$WORK" && launch_turn "$LOGS_DIR/codex-resume-recall.txt" "--persist" exec resume --last "$T2" ) || true
+      if grep -q "$CODEWORD" "$LOGS_DIR/codex-resume-recall.txt" 2>/dev/null; then
+        echo "[codex] behavioral recall HIT: resumed session remembered ${CODEWORD}"
+      else
+        echo "::warning::[codex] behavioral recall MISS (small CI model); mechanism gate still passed"
+      fi
+    fi
+    echo "[$AGENT] resume OK"
+    ;;
+
   *)
     echo "agent-guides-drive.sh: unknown mode '$MODE'" >&2
     exit 2

.github/workflows/local-agent-guides-ci.yml

@@ -471,6 +471,176 @@ jobs:
             redacted-configs/
           retention-days: 7
 
+  # ═════════════════════════════════════════════════════════════════════
+  # Job: resume
+  #   Does a conversation started with `unsloth start <agent>` survive exit
+  #   and resume? This drives the REAL launch path (not the --no-launch
+  #   recipe the other jobs use). A plain launch relocates the agent home to
+  #   a temp dir wiped on exit, so codex/pi cannot resume; --persist routes the
+  #   session to the stable Unsloth agents dir so it persists. opencode/claude
+  #   keep their session data in a fixed user dir, so they persist either way.
+  #   Dispatch-only: it is an end-to-end experiment, not a PR gate.
+  # ═════════════════════════════════════════════════════════════════════
+  resume:
+    name: resume (${{ matrix.agent }})
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    strategy:
+      fail-fast: false
+      matrix:
+        # codex/pi relocate their whole home (resume broken without --persist);
+        # opencode/claude keep session data in a fixed dir (resume already works).
+        # One agent from each class proves the split end to end; openclaw/hermes
+        # share codex's relocation mechanism and are covered by the unit tests.
+        agent: [codex, opencode, claude, pi]
+    env:
+      GGUF_REPO: unsloth/gemma-4-E4B-it-GGUF
+      GGUF_FILE: gemma-4-E4B-it-UD-Q4_K_XL.gguf
+      STUDIO_PORT: '18904'
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Linux deps for llama.cpp prebuilt
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends \
+            libcurl4-openssl-dev libssl-dev jq
+
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e  # v6.4.0
+        with:
+          node-version: '22'
+
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
+        with:
+          python-version: '3.12'
+          cache: 'pip'
+
+      - name: Restore GGUF model file
+        id: cache-gguf
+        uses: actions/cache/restore@27d5ce7f107fe9357f9df03efb73ab90386fccae  # v5.0.5
+        continue-on-error: true
+        with:
+          path: gguf-cache
+          key: ${{ runner.os }}-gguf-${{ env.GGUF_REPO }}-${{ env.GGUF_FILE }}-v1
+
+      - name: Download GGUF if cache miss
+        id: download-gguf
+        if: steps.cache-gguf.outputs.cache-hit != 'true' || steps.cache-gguf.outcome != 'success'
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+        run: |
+          python -m pip install --upgrade huggingface_hub
+          mkdir -p gguf-cache
+          bash .github/scripts/hf-download-with-retry.sh "$GGUF_REPO" "$GGUF_FILE" gguf-cache
+
+      - name: Save GGUF model file
+        if: always() && steps.download-gguf.outcome == 'success'
+        uses: actions/cache/save@27d5ce7f107fe9357f9df03efb73ab90386fccae  # v5.0.5
+        with:
+          path: gguf-cache
+          key: ${{ runner.os }}-gguf-${{ env.GGUF_REPO }}-${{ env.GGUF_FILE }}-v1
+
+      - name: Install Studio (--local, --no-torch)
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+        run: |
+          mkdir -p logs
+          set -o pipefail
+          bash install.sh --local --no-torch 2>&1 | tee logs/install.log
+
+      - name: Serve unsloth run --disable-tools (gemma-4-E4B)
+        run: |
+          unsloth studio reset-password
+          bash .github/scripts/serve-unsloth-run.sh \
+            --gguf-file "$GITHUB_WORKSPACE/gguf-cache/${GGUF_FILE}" \
+            --port "$STUDIO_PORT" --log-dir logs \
+            --extra "--seed $UNSLOTH_SEED --temp 0" \
+            --health-timeout 900
+
+      - name: Preflight the agent's API dialect (class-a isolation)
+        env:
+          AGENT: ${{ matrix.agent }}
+        run: |
+          set -uo pipefail
+          B="$UNSLOTH_BASE_URL"; K="$UNSLOTH_API_KEY"
+          preflight_fail() {
+            echo "::error::[server/API regression] agent=$AGENT: $* (preflight failed BEFORE install/connect). Endpoint contract lives in studio/backend/routes/**.";
+            exit 1
+          }
+          code=$(curl -s -o /tmp/pf.json -w '%{http_code}' "$B/v1/models" \
+            -H "Authorization: Bearer $K") || true
+          [ "$code" = "200" ] || preflight_fail "/v1/models returned HTTP $code"
+          case "$AGENT" in
+            claude)
+              code=$(curl -s -o /tmp/pf.json -w '%{http_code}' "$B/v1/messages" \
+                -H "Authorization: Bearer $K" -H 'content-type: application/json' \
+                --max-time 120 \
+                -d "{\"model\":\"$UNSLOTH_MODEL_ID\",\"max_tokens\":16,\"messages\":[{\"role\":\"user\",\"content\":\"Hi\"}]}") || true
+              [ "$code" = "200" ] || preflight_fail "/v1/messages returned HTTP $code"
+              ;;
+            codex)
+              code=$(curl -s -o /tmp/pf.json -w '%{http_code}' "$B/v1/responses" \
+                -H "Authorization: Bearer $K" -H 'content-type: application/json' \
+                --max-time 120 \
+                -d "{\"model\":\"$UNSLOTH_MODEL_ID\",\"input\":\"Hi\",\"max_output_tokens\":16,\"stream\":true}") || true
+              [ "$code" = "200" ] || preflight_fail "/v1/responses returned HTTP $code"
+              ;;
+            *)
+              code=$(curl -s -o /tmp/pf.json -w '%{http_code}' "$B/v1/chat/completions" \
+                -H "Authorization: Bearer $K" -H 'content-type: application/json' \
+                --max-time 120 \
+                -d "{\"model\":\"$UNSLOTH_MODEL_ID\",\"max_tokens\":16,\"messages\":[{\"role\":\"user\",\"content\":\"Hi\"}]}") || true
+              [ "$code" = "200" ] || preflight_fail "/v1/chat/completions returned HTTP $code"
+              ;;
+          esac
+          echo "preflight OK for $AGENT"
+
+      - name: Install agent CLI (class-b isolation)
+        env:
+          AGENT: ${{ matrix.agent }}
+        run: bash .github/scripts/agent-guides-install.sh "$AGENT"
+
+      - name: Resume experiment (launch path)
+        env:
+          AGENT: ${{ matrix.agent }}
+        run: bash .github/scripts/agent-guides-drive.sh resume "$AGENT"
+
+      - name: Collect server logs (debug)
+        if: always()
+        run: |
+          mkdir -p logs/studio-logs
+          cp -r "$HOME/.unsloth/studio/logs/." logs/studio-logs/ 2>/dev/null || true
+          if [ -n "${UNSLOTH_API_KEY:-}" ]; then
+            grep -rlF "$UNSLOTH_API_KEY" logs redacted-configs agent-workdir 2>/dev/null | while IFS= read -r f; do
+              sed -i "s#${UNSLOTH_API_KEY}#<REDACTED>#g" "$f" 2>/dev/null || true
+            done
+          fi
+
+      - name: Stop Studio
+        if: always()
+        run: |
+          if [ -n "${UNSLOTH_SERVER_PID:-}" ] && [ "${UNSLOTH_SERVER_PID}" != "0" ]; then
+            kill "${UNSLOTH_SERVER_PID}" 2>/dev/null || true
+          fi
+          sleep 2
+          ss -tln 2>/dev/null | grep ":${STUDIO_PORT}" || true
+
+      - name: Upload logs
+        if: always()
+        continue-on-error: true
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
+        with:
+          name: resume-${{ matrix.agent }}-log
+          path: |
+            logs/
+            agent-workdir/
+            redacted-configs/
+          retention-days: 7
+
   # ═════════════════════════════════════════════════════════════════════
   # Job 3: prompt-cache
   #   (a) curl 2-turn /v1/chat/completions: assert turn-2 cached_tokens > 0

unsloth_cli/commands/start.py

@@ -133,6 +133,21 @@ _YOLO_OPTION = typer.Option(
         "flag/config. Any of the three spellings works for any agent."
     ),
 )
+_PERSIST_OPTION = typer.Option(
+    False,
+    "--persist/--no-persist",
+    help = (
+        "Keep this agent's Unsloth-managed session dir so you can resume it later. "
+        "codex/openclaw/hermes/pi have their whole home relocated into an Unsloth dir "
+        "that is a throwaway temp dir (wiped on exit) by default; with --persist it "
+        "lives under the Unsloth agents dir and survives, so their own resume can reopen "
+        "it. claude and opencode keep sessions in your own stores (~/.claude, "
+        "~/.local/share/opencode), so they already resume regardless. To reopen a "
+        "session, pass the agent's own resume command through, e.g. "
+        "`unsloth start codex --persist resume` or `claude --resume <id>`; those flow to "
+        "the agent unchanged."
+    ),
+)
 
 # Per-agent CLI flag for "run tools without prompting". opencode and openclaw have no
 # such flag (config only) and are handled in their config writers, so they are absent.
@@ -1133,15 +1148,20 @@ def _agents_config_root() -> Path:
 
 
 @contextlib.contextmanager
-def _session_config(agent: str, launch: bool):
+def _session_config(
+    agent: str,
+    launch: bool,
+    persist: bool = False,
+):
     """Yield a private directory for an agent's session config (never the user's own).
 
-    launch: an ephemeral temp dir removed after the agent process exits, so nothing
-    persists. no-launch: a stable Unsloth-owned dir (the printed recipe is run later
-    on this machine), reused across runs. Either way the user's real ~/.<agent>
-    config is left untouched.
+    launch (default): an ephemeral temp dir removed after the agent process exits, so
+    nothing persists. no-launch: a stable Unsloth-owned dir (the printed recipe is run
+    later on this machine), reused across runs. persist (from --persist): use that same
+    stable dir even for a launch, so the agent's session survives the exit and can be
+    resumed next time. Either way the user's real ~/.<agent> config is left untouched.
     """
-    if launch:
+    if launch and not persist:
         path = Path(tempfile.mkdtemp(prefix = f"unsloth-{agent}-"))
         try:
             yield path
@@ -1453,6 +1473,7 @@ def claude(
     tensor_parallel: bool = _TENSOR_PARALLEL_OPTION,
     serve: bool = _SERVE_OPTION,
     yolo: bool = _YOLO_OPTION,
+    persist: bool = _PERSIST_OPTION,
 ):
     """Point Claude Code at the running Studio server and start it."""
     base, key, entry = _connect(
@@ -1497,6 +1518,9 @@ def claude(
     # --yolo (or its aliases) maps to Claude's own --dangerously-skip-permissions.
     # IS_SANDBOX is left unset on purpose: Claude refuses bypass mode as root unless a
     # sandbox is detected, and we don't want to falsely claim one on the user's host.
+    # claude keeps its history in ~/.claude/projects, which --settings/env never
+    # relocate, so a session already survives exit; resume it with `claude --continue`
+    # or `--resume <id>` passed through.
     command = [
         "claude",
         "--model",
@@ -1533,6 +1557,7 @@ def codex(
     tensor_parallel: bool = _TENSOR_PARALLEL_OPTION,
     serve: bool = _SERVE_OPTION,
     yolo: bool = _YOLO_OPTION,
+    persist: bool = _PERSIST_OPTION,
 ):
     """Point OpenAI Codex at the running Studio server and start it."""
     base, key, entry = _connect(
@@ -1558,7 +1583,7 @@ def codex(
         *_yolo_command_flags("codex", yolo),
         *ctx.args,
     ]
-    with _session_config("codex", launch) as home:
+    with _session_config("codex", launch, persist = persist) as home:
         write_codex_config(base, entry, home)
         env = {_CODEX_ENV_KEY: key, "CODEX_HOME": str(home)}
         _run(base, entry, env, command, launch = launch, install_hint = "npm install -g @openai/codex")
@@ -1576,6 +1601,7 @@ def openclaw(
     tensor_parallel: bool = _TENSOR_PARALLEL_OPTION,
     serve: bool = _SERVE_OPTION,
     yolo: bool = _YOLO_OPTION,
+    persist: bool = _PERSIST_OPTION,
 ):
     """Point OpenClaw at the running Studio server and start it."""
     base, key, entry = _connect(
@@ -1601,7 +1627,7 @@ def openclaw(
         if os.name == "nt"
         else "curl -fsSL https://openclaw.ai/install.sh | bash"
     )
-    with _session_config("openclaw", launch) as cfg:
+    with _session_config("openclaw", launch, persist = persist) as cfg:
         config_path = cfg / "openclaw.json"
         # key lives in the config, not the env; --yolo writes the exec policy here too.
         write_openclaw_config(base, key, entry, config_path, yolo = yolo)
@@ -1622,6 +1648,7 @@ def opencode(
     tensor_parallel: bool = _TENSOR_PARALLEL_OPTION,
     serve: bool = _SERVE_OPTION,
     yolo: bool = _YOLO_OPTION,
+    persist: bool = _PERSIST_OPTION,
 ):
     """Point OpenCode at the running Studio server and start it."""
     base, key, entry = _connect(
@@ -1645,7 +1672,9 @@ def opencode(
         command = ["opencode", "--model", opencode_model]
     else:
         command = ["opencode"]
-    with _session_config("opencode", launch) as cfg:
+    # opencode keeps sessions in ~/.local/share/opencode (never relocated), so resume
+    # already survives exit; reopen the last one by passing `opencode --continue` through.
+    with _session_config("opencode", launch, persist = persist) as cfg:
         config_path = cfg / "opencode.json"
         # OPENCODE_CONFIG is an overlay (loaded between the user's global and project
         # configs), so this adds the Unsloth provider/model for the session without
@@ -1697,6 +1726,7 @@ def hermes(
     tensor_parallel: bool = _TENSOR_PARALLEL_OPTION,
     serve: bool = _SERVE_OPTION,
     yolo: bool = _YOLO_OPTION,
+    persist: bool = _PERSIST_OPTION,
 ):
     """Point Hermes (Nous Research) at the running Studio server and start it."""
     base, key, entry = _connect(
@@ -1708,7 +1738,7 @@ def hermes(
     )
     command = ["hermes", *_yolo_command_flags("hermes", yolo), *ctx.args]
     install_hint = _hermes_install_hint()
-    with _session_config("hermes", launch) as home:
+    with _session_config("hermes", launch, persist = persist) as home:
         # HERMES_HOME relocates hermes' whole home dir (config.yaml, sessions, state)
         # like CODEX_HOME, so the user's ~/.hermes is left untouched for the session.
         write_hermes_config(base, entry, home / "config.yaml")
@@ -1728,6 +1758,7 @@ def pi(
     tensor_parallel: bool = _TENSOR_PARALLEL_OPTION,
     serve: bool = _SERVE_OPTION,
     yolo: bool = _YOLO_OPTION,
+    persist: bool = _PERSIST_OPTION,
 ):
     """Point Pi (coding agent) at the running Studio server and start it."""
     base, key, entry = _connect(
@@ -1752,7 +1783,7 @@ def pi(
     # --ignore-scripts matches Pi's documented install recipe (its README notes Pi needs
     # no install scripts), so accepting the prompt skips dependency lifecycle scripts.
     install_hint = "npm install -g --ignore-scripts @earendil-works/pi-coding-agent"
-    with _session_config("pi", launch) as home:
+    with _session_config("pi", launch, persist = persist) as home:
         # Pi resolves its config dir from PI_CODING_AGENT_DIR first (getAgentDir() prefers
         # it over $HOME/.pi/agent), so pin it at the session dir: an inherited
         # PI_CODING_AGENT_DIR in the user's shell would otherwise send Pi to their real

unsloth_cli/tests/test_start.py

@@ -2548,3 +2548,145 @@ def test_session_config_no_launch_preserves_existing_state(fake_studio, tmp_path
     with start._session_config("codex", launch = False) as home2:
         assert home2 == home
         assert (home2 / "sessions" / "live.sqlite").read_text() == "state"
+
+
+# ── --persist: persist the agent session so it can be resumed ────────────────
+def test_session_config_persist_uses_stable_dir_and_survives(monkeypatch, tmp_path):
+    # --persist routes a launch to the stable Unsloth agents dir (the one --no-launch
+    # already uses) instead of a throwaway temp dir, and never wipes it on exit.
+    monkeypatch.setattr(start, "_agents_config_root", lambda: tmp_path / "agents")
+    with start._session_config("codex", launch = True, persist = True) as home:
+        assert home == tmp_path / "agents" / "codex"
+        (home / "marker").write_text("kept")
+    assert home.exists()
+    assert (home / "marker").read_text() == "kept"
+
+
+def test_session_config_default_launch_is_ephemeral():
+    # Default launch (no --persist) still uses a throwaway temp dir wiped on exit.
+    with start._session_config("codex", launch = True) as home:
+        assert home.exists()
+        assert "unsloth-codex-" in home.name
+    assert not home.exists()
+
+
+# The temp-dir agents: --persist points each one's home/state env at the stable dir;
+# without it, at an ephemeral temp path. opencode is handled separately (only its
+# config overlay is relocated; its session data was never in the temp dir).
+_RESUME_ENV_VAR = {
+    "codex": "CODEX_HOME",
+    "openclaw": "OPENCLAW_STATE_DIR",
+    "hermes": "HERMES_HOME",
+    "pi": "HOME",
+}
+
+
+def _capture_launch(monkeypatch, argv):
+    captured = {}
+
+    def run(
+        command,
+        env = None,
+        **kwargs,
+    ):
+        captured["command"] = command
+        captured["env"] = env
+        return SimpleNamespace(returncode = 0)
+
+    monkeypatch.setattr(start.subprocess, "run", run)
+    result = CliRunner().invoke(start.start_app, argv)
+    assert result.exit_code == 0, result.output
+    return captured
+
+
+@pytest.mark.parametrize("agent", sorted(_RESUME_ENV_VAR))
+def test_resume_persists_agent_home_to_stable_dir(agent, fake_studio, tmp_path, monkeypatch):
+    monkeypatch.setattr(start.shutil, "which", lambda _: f"/usr/local/bin/{agent}")
+    captured = _capture_launch(monkeypatch, [agent, "--persist"])
+    stable = tmp_path / "agents" / agent
+    assert captured["env"][_RESUME_ENV_VAR[agent]] == str(stable)
+    # The stable dir survives the agent exit, so the session can be resumed.
+    assert stable.exists()
+
+
+@pytest.mark.parametrize("agent", sorted(_RESUME_ENV_VAR))
+def test_default_launch_home_is_ephemeral(agent, fake_studio, tmp_path, monkeypatch):
+    monkeypatch.setattr(start.shutil, "which", lambda _: f"/usr/local/bin/{agent}")
+    captured = _capture_launch(monkeypatch, [agent])
+    home = captured["env"][_RESUME_ENV_VAR[agent]]
+    assert f"unsloth-{agent}-" in home
+    assert str(tmp_path / "agents") not in home
+
+
+def test_resume_opencode_config_in_stable_dir(fake_studio, tmp_path, monkeypatch):
+    # opencode's session data lives in ~/.local/share/opencode (never relocated), so
+    # resume already survives exit; --persist also stabilizes its config overlay dir.
+    monkeypatch.setattr(start.shutil, "which", lambda _: "/usr/local/bin/opencode")
+    captured = _capture_launch(monkeypatch, ["opencode", "--persist"])
+    stable = tmp_path / "agents" / "opencode"
+    assert captured["env"]["OPENCODE_CONFIG"] == str(stable / "opencode.json")
+    assert stable.exists()
+
+
+def test_persist_bare_codex_launch_has_no_resume_token(fake_studio, monkeypatch):
+    # A bare `--persist` only persists the session dir; it must NOT auto-append a native
+    # resume token, or the very first launch (no session yet) would send codex down its
+    # no-session error path. The user resumes explicitly: `unsloth start codex --persist resume`.
+    monkeypatch.setattr(start.shutil, "which", lambda _: "/usr/local/bin/codex")
+    captured = _capture_launch(monkeypatch, ["codex", "--persist"])
+    assert "resume" not in captured["command"]
+    # command[0] is the resolved executable path; assert the argv after it.
+    assert captured["command"][1:] == ["--oss", "--profile", start._CODEX_PROFILE]
+
+
+def test_persist_bare_opencode_launch_has_no_resume_token(fake_studio, monkeypatch):
+    monkeypatch.setattr(start.shutil, "which", lambda _: "/usr/local/bin/opencode")
+    captured = _capture_launch(monkeypatch, ["opencode", "--persist"])
+    assert "--continue" not in captured["command"]
+    assert captured["command"][1:] == ["--model", f"{start._OPENCODE_PROVIDER}/{MODEL['id']}"]
+
+
+def test_persist_bare_claude_launch_has_no_resume_token(fake_studio, monkeypatch):
+    monkeypatch.setattr(start.shutil, "which", lambda _: "/usr/local/bin/claude")
+    monkeypatch.setattr(start, "_claude_flags", lambda: [])
+    captured = _capture_launch(monkeypatch, ["claude", "--persist"])
+    assert "--continue" not in captured["command"]
+    assert captured["command"][1:] == ["--model", MODEL["id"]]
+
+
+def test_resume_with_passthrough_does_not_auto_append(fake_studio, monkeypatch):
+    # When the caller drives their own subcommand, --persist only persists the dir; it
+    # must not inject a resume token that would collide with the user's command.
+    monkeypatch.setattr(start.shutil, "which", lambda _: "/usr/local/bin/codex")
+    captured = _capture_launch(monkeypatch, ["codex", "--persist", "exec", "hello"])
+    assert "resume" not in captured["command"]
+    assert captured["command"][-2:] == ["exec", "hello"]
+
+
+def test_default_launch_has_no_resume_token(fake_studio, monkeypatch):
+    monkeypatch.setattr(start.shutil, "which", lambda _: "/usr/local/bin/codex")
+    captured = _capture_launch(monkeypatch, ["codex"])
+    assert "resume" not in captured["command"]
+
+
+def test_resume_persist_only_agents_have_no_resume_token(fake_studio, monkeypatch):
+    # openclaw/hermes persist their session dir but have no non-interactive resume
+    # selector, so --persist must not append a token; their own picker resumes.
+    for agent in ("openclaw", "hermes"):
+        monkeypatch.setattr(start.shutil, "which", lambda _, a = agent: f"/usr/local/bin/{a}")
+        captured = _capture_launch(monkeypatch, [agent, "--persist"])
+        assert "resume" not in captured["command"]
+        assert "--continue" not in captured["command"]
+
+
+def test_native_resume_flag_passes_through_unchanged(fake_studio, monkeypatch):
+    # The persistence flag is --persist, NOT --resume, so an agent's own
+    # `--resume <id>` (e.g. `unsloth start claude --resume <guid>`) still flows
+    # through to the agent verbatim and is not swallowed as a Studio option.
+    monkeypatch.setattr(start.shutil, "which", lambda _: "/usr/local/bin/claude")
+    monkeypatch.setattr(start, "_claude_flags", lambda: [])
+    captured = _capture_launch(monkeypatch, ["claude", "--resume", "some-session-guid"])
+    assert captured["command"][-2:] == ["--resume", "some-session-guid"]
+    # Studio never auto-appends its own resume token when the user drives resume.
+    assert captured["command"].count("--resume") == 1
+    assert "--continue" not in captured["command"]