@freibergergarcia/phone-a-friend 2.0.1 → 2.1.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "phone-a-friend",
   "description": "CLI relay that lets AI coding agents collaborate by sending prompts and repository context to backend agents.",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "author": {
     "name": "Bruno Freiberger"
   }

package/commands/phone-a-friend.md

@@ -86,8 +86,9 @@ I'm working on this task and got the above response. Please review it and return
    **Binary mode** (`RELAY_MODE = binary`):
    ```bash
    phone-a-friend --to codex --repo "$PWD" --prompt "<relay-prompt>" --context-text "<context-payload>" [--fast] [--session <id>]
-   # For gemini, always include --model (see "Gemini Model Priority" below):
-   phone-a-friend --to gemini --repo "$PWD" --prompt "<relay-prompt>" --context-text "<context-payload>" --model <model> [--fast] [--session <id>]
+   # For gemini, always include --model (see "Gemini Model Priority" below).
+   # Do NOT pass --session to gemini — it will error (see "Session continuity" below):
+   phone-a-friend --to gemini --repo "$PWD" --prompt "<relay-prompt>" --context-text "<context-payload>" --model <model> [--fast]
    ```
 
    See "Speed optimization" and "Session continuity" below for when to
@@ -144,7 +145,7 @@ wants the same backend to apply fixes or dig deeper), reuse the session:
 3. On **subsequent** relays to the **same backend** in the same
    conversation, reuse the same session ID. The backend remembers previous
    turns.
-4. If switching backends (e.g., first call to codex, second to gemini),
+4. If switching backends (e.g., first call to codex, second to ollama),
    generate a new session ID for the new backend. Sessions are
    backend-specific.
 
@@ -152,13 +153,20 @@ Benefits: the backend keeps full conversation history, so follow-up prompts
 can be shorter (no need to re-send context from previous turns).
 
 **Backend-specific behavior:**
-- **Claude, Codex**: native session resume. Follow-up prompts can send
-  deltas only.
-- **Ollama**: replays full history each call. Sessions work but prompt size
-  grows with each turn. Keep follow-ups concise.
-- **Gemini**: session resume is best-effort (may start fresh). Always
-  include enough context for Gemini to answer independently, even in
-  follow-up calls.
+- **Codex, Claude, OpenCode**: native session resume. Follow-up prompts
+  can send deltas only.
+- **Ollama**: replays full history each call. Sessions work but prompt
+  size grows with each turn. Keep follow-ups concise.
+- **Gemini**: `--session` is **not supported**. PaF rejects it with a
+  RelayError (`--session is not supported by the gemini backend ...`).
+  Each Gemini relay call must be self-contained. Do not pass `--session`
+  with `--to gemini`.
+
+On the FIRST relay under a new session label, PaF prints an informational
+stderr line: `[phone-a-friend] Session label "..." not found in store.
+Starting a fresh session under this label.` This is expected. The hint
+about `--backend-session` in that line is for advanced use (see below)
+and not relevant to the typical `/phone-a-friend` flow.
 
 **Omit `--session`** for one-off relays where no follow-up is expected.
 This is the common case. Only add `--session` when the user explicitly
@@ -166,6 +174,25 @@ asks for a follow-up or continuation of a previous relay.
 
 Session continuity is only available in binary mode (`RELAY_MODE = binary`).
 
+### Advanced: `--backend-session` (raw thread ID adoption)
+
+If the user explicitly provides a Codex/Claude/OpenCode backend thread ID
+that PaF did not create (e.g., from another tool or a previous CLI run),
+attach to it with `--backend-session <id>` instead of `--session <id>`.
+Combine with `--session <label>` to also start tracking under a label.
+
+```bash
+# Resume a raw backend thread once (no PaF persistence):
+phone-a-friend --to codex --repo "$PWD" --backend-session <thread-id> --prompt "<...>"
+
+# Adopt: resume AND start tracking under a PaF label going forward:
+phone-a-friend --to codex --repo "$PWD" --session <label> --backend-session <thread-id> --prompt "<...>"
+```
+
+This is rarely the right move from inside a Claude Code conversation — the
+common case is `--session <label>` with a fresh label. Only use
+`--backend-session` when the user supplied a specific backend thread ID.
+
 ## Gemini Model Priority
 
 When using `--to gemini`, **always** pass `--model` using the first model from

package/commands/phone-a-team.md

@@ -233,8 +233,13 @@ command:
 - `SESSION_IDS` = map of backend name to session ID (binary mode only).
   Generated as `paf-team-<backend>-<task-slug>-<4-char-random>` (e.g.,
   `paf-team-codex-review-auth-b7e1`). The random suffix prevents
-  collisions across runs and repos. One session ID per backend. Used in
-  all relay calls so the backend remembers previous rounds.
+  collisions across runs and repos. One session ID per session-capable
+  backend. Used in relay calls so the backend remembers previous rounds.
+
+  **Generate session IDs only for `codex` and `ollama`.** Do NOT generate
+  one for `gemini` — the Gemini backend declares `resumeStrategy:
+  unsupported`, and PaF will reject `--session` for Gemini with a
+  RelayError. For `--backend both`, generate a session ID for codex only.
 
 ### Algorithm
 
@@ -274,7 +279,16 @@ command:
 
    phone-a-friend --to <backend> --repo "$PWD" --prompt "<prompt>" \
      [--context-text "<context>"] [--include-diff] [--sandbox <mode>] \
-     [--model <model>] --fast --session <SESSION_ID>
+     [--model <model>] --fast [--session <SESSION_ID>]
+
+   Include `--session <SESSION_ID>` ONLY when <backend> is `codex` or
+   `ollama`. For `gemini`, omit `--session` entirely (PaF rejects it for
+   Gemini with a RelayError).
+
+   On the FIRST relay under a new session label, PaF prints an
+   informational stderr line: `[phone-a-friend] Session label "..." not
+   found in store. Starting a fresh session under this label.` This is
+   expected and not a failure.
 
    After the relay completes, send the FULL unedited output to the team
    lead via SendMessage. Include:
@@ -389,13 +403,19 @@ Delegate the task to the backend via the relay. The lead's job is to
 
   **Binary mode** (`RELAY_MODE = binary`):
   ```bash
-  phone-a-friend --to <backend> --repo "$PWD" --prompt "<prompt>" [--context-text "<context>"] [--include-diff] [--sandbox <mode>] [--model <model>] --fast --session <SESSION_ID>
+  phone-a-friend --to <backend> --repo "$PWD" --prompt "<prompt>" [--context-text "<context>"] [--include-diff] [--sandbox <mode>] [--model <model>] --fast [--session <SESSION_ID>]
   ```
 
-  Always include `--fast` (relay prompts are self-contained) and
-  `--session` using the backend-specific ID from `SESSION_IDS`. The session
-  lets the backend remember previous rounds, so follow-up prompts can focus
-  on feedback deltas rather than re-sending full context.
+  Always include `--fast` (relay prompts are self-contained). Include
+  `--session` ONLY when `<backend>` is `codex` or `ollama` — pass the
+  backend-specific ID from `SESSION_IDS`. For `gemini`, omit `--session`
+  entirely; PaF rejects `--session` against Gemini (resume strategy
+  declared `unsupported`).
+
+  When `--session` is used, the session lets the backend remember
+  previous rounds, so follow-up prompts can focus on feedback deltas
+  rather than re-sending full context. For Gemini (no session), each
+  round is stateless — see "Per-round relay rules" below.
 
   **Direct mode** (`RELAY_MODE = direct`):
   ```bash
@@ -511,18 +531,21 @@ codebase. Read at most 2-3 files for preflight context. The backend has
 not to become an expert on the codebase before delegating.
 
 **Per-round relay rules (binary mode with `--session`)**:
-When `--session` is active, session-capable backends (Claude, Codex)
-remember previous rounds natively. Each relay call only needs to send:
+When `--session` is active, session-capable backends (Codex) remember
+previous rounds natively. Each relay call only needs to send:
   - The specific feedback or revision request for this round
   - Any new context (e.g., updated diff after changes)
 Do NOT re-send the full task description, prior outputs, or summaries.
 The backend already has them in its session history.
 
-**Exception: Gemini and Ollama with `--session`**: Gemini may not resume
-natively (best-effort). Ollama replays full history each call (prompt size
-grows per turn). For these backends, always include enough context for the
-backend to answer independently, even in follow-up rounds. Include a brief
-task recap + the latest output alongside the feedback.
+**Exception: Ollama with `--session`**: Ollama replays full history each
+call (prompt size grows per turn). Sessions work but follow-up prompts
+must stay concise to avoid hitting size limits.
+
+**Exception: Gemini (no `--session`)**: Gemini runs stateless every round.
+Each Gemini relay call must include enough context for the backend to
+answer independently — include a brief task recap and the latest output
+alongside the feedback in every round.
 
 **Per-round relay rules (direct mode, no session)**:
 - Each relay call sends ONLY:

package/dist/index.js

@@ -5720,7 +5720,21 @@ var init_jobs = __esm({
 });
 
 // src/sessions.ts
-import { readFileSync as readFileSync4, writeFileSync as writeFileSync4, existsSync as existsSync4, mkdirSync as mkdirSync3 } from "fs";
+var sessions_exports = {};
+__export(sessions_exports, {
+  SessionStore: () => SessionStore
+});
+import {
+  readFileSync as readFileSync4,
+  writeFileSync as writeFileSync4,
+  existsSync as existsSync4,
+  mkdirSync as mkdirSync3,
+  openSync,
+  closeSync,
+  fsyncSync,
+  renameSync,
+  unlinkSync
+} from "fs";
 import { dirname as dirname3, join as join4 } from "path";
 import { homedir as homedir3 } from "os";
 var MAX_SESSIONS, SessionStore;
@@ -5739,15 +5753,65 @@ var init_sessions = __esm({
       }
       load() {
         if (!existsSync4(this.filePath)) return [];
+        let raw;
         try {
-          return JSON.parse(readFileSync4(this.filePath, "utf-8"));
-        } catch {
+          raw = readFileSync4(this.filePath, "utf-8");
+        } catch (err) {
+          console.error(`[phone-a-friend] Failed to read session store ${this.filePath}: ${err.message}`);
+          return [];
+        }
+        try {
+          const parsed = JSON.parse(raw);
+          if (!Array.isArray(parsed)) {
+            throw new Error("session store is not a JSON array");
+          }
+          return parsed;
+        } catch (err) {
+          const ts = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+          const rotated = `${this.filePath}.corrupt-${ts}`;
+          try {
+            renameSync(this.filePath, rotated);
+            console.error(
+              `[phone-a-friend] Session store at ${this.filePath} could not be parsed (${err.message}). Rotated to ${rotated}. Starting with an empty store.`
+            );
+          } catch (rotateErr) {
+            console.error(
+              `[phone-a-friend] Session store at ${this.filePath} could not be parsed (${err.message}) and could not be rotated (${rotateErr.message}). Starting with an empty store; the file will be overwritten on next write.`
+            );
+          }
           return [];
         }
       }
       save(sessions) {
-        mkdirSync3(dirname3(this.filePath), { recursive: true });
-        writeFileSync4(this.filePath, JSON.stringify(sessions, null, 2), "utf-8");
+        const dir = dirname3(this.filePath);
+        mkdirSync3(dir, { recursive: true });
+        const tmpPath = `${this.filePath}.tmp.${process.pid}.${Date.now()}`;
+        const payload = JSON.stringify(sessions, null, 2);
+        const tmpFd = openSync(tmpPath, "w");
+        try {
+          try {
+            writeFileSync4(tmpFd, payload, "utf-8");
+            fsyncSync(tmpFd);
+          } finally {
+            closeSync(tmpFd);
+          }
+          renameSync(tmpPath, this.filePath);
+        } catch (err) {
+          try {
+            unlinkSync(tmpPath);
+          } catch {
+          }
+          throw err;
+        }
+        try {
+          const dirFd = openSync(dir, "r");
+          try {
+            fsyncSync(dirFd);
+          } finally {
+            closeSync(dirFd);
+          }
+        } catch {
+        }
       }
       get(id) {
         return this.load().find((session) => session.id === id) ?? null;
@@ -5755,7 +5819,35 @@ var init_sessions = __esm({
       list() {
         return this.load();
       }
+      /** Remove a single session by label. Returns true if a row was removed. */
+      delete(id) {
+        const sessions = this.load();
+        const filtered = sessions.filter((session) => session.id !== id);
+        if (filtered.length === sessions.length) return false;
+        this.save(filtered);
+        return true;
+      }
+      /** Drop sessions whose `lastUsedAt` is older than `cutoff`. Returns the IDs removed. */
+      pruneOlderThan(cutoff) {
+        const sessions = this.load();
+        const cutoffIso = cutoff.toISOString();
+        const removed = sessions.filter((s) => s.lastUsedAt < cutoffIso).map((s) => s.id);
+        if (removed.length === 0) return [];
+        const kept = sessions.filter((s) => s.lastUsedAt >= cutoffIso);
+        this.save(kept);
+        return removed;
+      }
+      /** Drop every session. Returns the count removed. */
+      clear() {
+        const sessions = this.load();
+        if (sessions.length === 0) return 0;
+        this.save([]);
+        return sessions.length;
+      }
       upsert(opts) {
+        if (opts.historyAppend !== void 0 && opts.replaceHistory !== void 0) {
+          throw new Error("upsert: historyAppend and replaceHistory are mutually exclusive");
+        }
         const sessions = this.load();
         const now = (/* @__PURE__ */ new Date()).toISOString();
         const existing = sessions.find((session2) => session2.id === opts.id);
@@ -5765,19 +5857,22 @@ var init_sessions = __esm({
           if (opts.backendSessionId) {
             existing.backendSessionId = opts.backendSessionId;
           }
-          if (opts.historyAppend?.length) {
+          if (opts.replaceHistory !== void 0) {
+            existing.history = [...opts.replaceHistory];
+          } else if (opts.historyAppend?.length) {
             existing.history.push(...opts.historyAppend);
           }
           existing.lastUsedAt = now;
           this.save(sessions);
           return existing;
         }
+        const initialHistory = opts.replaceHistory !== void 0 ? [...opts.replaceHistory] : [...opts.historyAppend ?? []];
         const session = {
           id: opts.id,
           backend: opts.backend,
           backendSessionId: opts.backendSessionId,
           repoPath: opts.repoPath,
-          history: [...opts.historyAppend ?? []],
+          history: initialHistory,
           createdAt: now,
           lastUsedAt: now
         };
@@ -5954,6 +6049,7 @@ function prepareRelay(opts) {
     sandbox = DEFAULT_SANDBOX,
     schema = null,
     session = null,
+    backendSession = null,
     fast = false
   } = opts;
   if (!prompt.trim()) {
@@ -5978,6 +6074,16 @@ function prepareRelay(opts) {
     const allowed = [...selectedBackend.allowedSandboxes].sort().join(", ");
     throw new RelayError(`Invalid sandbox mode: ${sandbox}. Allowed values: ${allowed}`);
   }
+  if (backendSession && selectedBackend.capabilities.resumeStrategy !== "native-session") {
+    throw new RelayError(
+      `--backend-session is not supported by the ${selectedBackend.name} backend (resume strategy: ${selectedBackend.capabilities.resumeStrategy}).`
+    );
+  }
+  if (session && selectedBackend.capabilities.resumeStrategy === "unsupported") {
+    throw new RelayError(
+      `--session is not supported by the ${selectedBackend.name} backend (resume strategy: unsupported). The backend cannot resume a prior conversation, so PaF refuses to persist a label that would silently fresh-spawn each call.`
+    );
+  }
   const resolvedContext = resolveContextText(contextFile, contextText);
   const diffText = includeDiff ? gitDiff(resolvedRepo) : "";
   const fullPrompt = buildPrompt({
@@ -5999,6 +6105,7 @@ function prepareRelay(opts) {
     model,
     schema,
     session,
+    backendSession,
     fast,
     sessionStore: opts.sessionStore
   };
@@ -6014,10 +6121,62 @@ async function relay(opts) {
     model,
     schema,
     session,
+    backendSession,
     fast,
     sessionStore
   } = prepareRelay(opts);
   try {
+    if (backendSession) {
+      const store2 = session ? sessionStore ?? new SessionStore() : null;
+      const existing = session && store2 ? store2.get(session) : null;
+      if (existing) {
+        const conflicts = [];
+        if (existing.backend !== selectedBackend.name) {
+          conflicts.push(`backend "${existing.backend}" (expected "${selectedBackend.name}")`);
+        }
+        if (existing.backendSessionId && existing.backendSessionId !== backendSession) {
+          conflicts.push(`backend session "${existing.backendSessionId}" (expected "${backendSession}")`);
+        }
+        if (existing.repoPath !== resolvedRepo) {
+          conflicts.push(`repo "${existing.repoPath}" (expected "${resolvedRepo}")`);
+        }
+        if (conflicts.length > 0) {
+          throw new RelayError(
+            `Session label "${session}" already exists with conflicting metadata: ${conflicts.join("; ")}. Use a different label or remove the existing entry.`
+          );
+        }
+      }
+      let createdSessionId2 = backendSession;
+      const result2 = await selectedBackend.run({
+        prompt: fullPrompt,
+        repoPath: resolvedRepo,
+        timeoutSeconds,
+        sandbox,
+        model,
+        env: env3,
+        schema,
+        sessionId: backendSession,
+        persistSession: Boolean(session),
+        resumeSession: true,
+        fast,
+        sessionHistory: existing?.history ?? [],
+        onSessionCreated: (newSessionId) => {
+          createdSessionId2 = newSessionId;
+        }
+      });
+      if (session && store2) {
+        persistRelaySession(
+          store2,
+          session,
+          selectedBackend,
+          resolvedRepo,
+          fullPrompt,
+          result2,
+          createdSessionId2
+        );
+      }
+      return result2;
+    }
     const store = session ? sessionStore ?? new SessionStore() : null;
     const storedSession = session ? store?.get(session) ?? null : null;
     if (storedSession && storedSession.backend !== selectedBackend.name) {
@@ -6030,6 +6189,11 @@ async function relay(opts) {
         `Session ${session} belongs to a different repository: ${storedSession.repoPath}`
       );
     }
+    if (session && !storedSession) {
+      console.error(
+        `[phone-a-friend] Session label "${session}" not found in store. Starting a fresh session under this label. If you meant to attach to an existing backend thread, use --backend-session <id>.`
+      );
+    }
     let backendSessionId = storedSession?.backendSessionId ?? null;
     if (session && !storedSession && selectedBackend.capabilities.requiresClientSessionId) {
       backendSessionId = randomUUID2();
@@ -6077,15 +6241,26 @@ async function relay(opts) {
   }
 }
 function persistRelaySession(store, id, backend, repoPath, prompt, output, backendSessionId) {
+  const replaysHistory = backend.capabilities.resumeStrategy === "transcript-replay";
+  if (replaysHistory) {
+    store.upsert({
+      id,
+      backend: backend.name,
+      repoPath,
+      backendSessionId: backendSessionId ?? void 0,
+      historyAppend: [
+        { role: "user", content: prompt },
+        { role: "assistant", content: output }
+      ]
+    });
+    return;
+  }
   store.upsert({
     id,
     backend: backend.name,
     repoPath,
     backendSessionId: backendSessionId ?? void 0,
-    historyAppend: [
-      { role: "user", content: prompt },
-      { role: "assistant", content: output }
-    ]
+    replaceHistory: []
   });
 }
 async function* relayStream(opts) {
@@ -6099,11 +6274,12 @@ async function* relayStream(opts) {
     model,
     schema,
     session,
+    backendSession,
     fast,
     sessionStore
   } = prepareRelay(opts);
-  const store = session ? sessionStore ?? new SessionStore() : null;
-  const storedSession = session ? store?.get(session) ?? null : null;
+  const store = session && !backendSession ? sessionStore ?? new SessionStore() : null;
+  const storedSession = session && !backendSession ? store?.get(session) ?? null : null;
   const runOpts = {
     prompt: fullPrompt,
     repoPath: resolvedRepo,
@@ -6113,9 +6289,9 @@ async function* relayStream(opts) {
     env: env3,
     schema,
     fast,
-    sessionId: storedSession?.backendSessionId ?? null,
+    sessionId: backendSession ?? storedSession?.backendSessionId ?? null,
     persistSession: Boolean(session),
-    resumeSession: Boolean(session && storedSession),
+    resumeSession: Boolean(backendSession || session && storedSession),
     sessionHistory: storedSession?.history ?? []
   };
   try {
@@ -6287,7 +6463,7 @@ import {
   rmSync as rmSync2,
   symlinkSync,
   cpSync,
-  unlinkSync
+  unlinkSync as unlinkSync2
 } from "fs";
 import { resolve as resolve3, join as join5, dirname as dirname5 } from "path";
 import { homedir as homedir4 } from "os";
@@ -6303,7 +6479,7 @@ function removePath(filePath) {
     throw err;
   }
   if (stat.isSymbolicLink() || stat.isFile()) {
-    unlinkSync(filePath);
+    unlinkSync2(filePath);
   } else if (stat.isDirectory()) {
     rmSync2(filePath, { recursive: true, force: true });
   }
@@ -17884,7 +18060,7 @@ var init_parse_editor_command = __esm({
 
 // node_modules/@inquirer/external-editor/dist/index.js
 import { spawn as spawn3, spawnSync } from "child_process";
-import { readFileSync as readFileSync8, unlinkSync as unlinkSync2, writeFileSync as writeFileSync5 } from "fs";
+import { readFileSync as readFileSync8, unlinkSync as unlinkSync3, writeFileSync as writeFileSync5 } from "fs";
 import path2 from "path";
 import os2 from "os";
 import { randomUUID as randomUUID3 } from "crypto";
@@ -17959,7 +18135,7 @@ var init_dist8 = __esm({
         if (!this.tempFile)
           return;
         try {
-          unlinkSync2(this.tempFile);
+          unlinkSync3(this.tempFile);
           this.tempFile = "";
         } catch (removeFileError) {
           throw new RemoveFileError(removeFileError);
@@ -76642,8 +76818,14 @@ var GeminiBackend = class {
     "workspace-write",
     "danger-full-access"
   ]);
+  // Session resume is declared 'unsupported' rather than 'transcript-replay':
+  // run() never reads opts.sessionHistory, and the --resume code path below
+  // depends on a session ID that the upstream extractor cannot reliably
+  // produce (see extractGeminiSessionId). Until the Gemini CLI's session
+  // surface is verified, --session against this backend is rejected at the
+  // relay layer instead of silently no-opping.
   capabilities = {
-    resumeStrategy: "transcript-replay",
+    resumeStrategy: "unsupported",
     requiresClientSessionId: false
   };
   async run(opts) {
@@ -80349,7 +80531,7 @@ init_version();
 function repoRootDefault() {
   return getPackageRoot();
 }
-var KNOWN_SUBCOMMANDS = ["relay", "install", "update", "uninstall", "setup", "doctor", "config", "plugin", "agentic", "job"];
+var KNOWN_SUBCOMMANDS = ["relay", "install", "update", "uninstall", "setup", "doctor", "config", "plugin", "agentic", "job", "session"];
 var TOP_LEVEL_FLAGS = /* @__PURE__ */ new Set(["-v", "-V", "--version", "-h", "--help"]);
 function normalizeArgv(argv) {
   if (argv.length === 0) return argv;
@@ -80545,7 +80727,7 @@ ${banner("AI coding agent relay")}
     writeOut: (str) => console.log(str.trimEnd()),
     writeErr: (str) => console.error(str.trimEnd())
   }).exitOverride();
-  program2.command("relay").description("Relay prompt/context to a coding backend (default)").option("--prompt <text>", "Prompt to relay (required unless --review or --base is used)").option("--to <backend>", "Target backend: codex, gemini, ollama, claude, opencode").option("--repo <path>", "Repository path", process.cwd()).option("--context-file <path>", "File with additional context").option("--context-text <text>", "Inline context text").option("--include-diff", "Append git diff to prompt").option("--timeout <seconds>", "Max runtime in seconds").option("--model <name>", "Model override").option("--sandbox <mode>", "Sandbox: read-only, workspace-write, danger-full-access").option("--schema <json>", "Request structured JSON output matching this schema").option("--session <id>", "Resume or create a persisted relay session").option("--fast", "Use fast mode when supported (maps to --bare for Claude)").option("--stream", "Stream tokens as they arrive (default)").option("--no-stream", "Disable streaming output (get full response at once)").option("--review", "Use review mode (scoped to diff against base branch)").option("--base <branch>", "Base branch for review diff (default: auto-detect main/master)").option("--quiet", "Run silently, save result to job store").action(async (opts, command) => {
+  program2.command("relay").description("Relay prompt/context to a coding backend (default)").option("--prompt <text>", "Prompt to relay (required unless --review or --base is used)").option("--to <backend>", "Target backend: codex, gemini, ollama, claude, opencode").option("--repo <path>", "Repository path", process.cwd()).option("--context-file <path>", "File with additional context").option("--context-text <text>", "Inline context text").option("--include-diff", "Append git diff to prompt").option("--timeout <seconds>", "Max runtime in seconds").option("--model <name>", "Model override").option("--sandbox <mode>", "Sandbox: read-only, workspace-write, danger-full-access").option("--schema <json>", "Request structured JSON output matching this schema").option("--session <id>", "Resume or create a persisted relay session (PaF label)").option("--backend-session <id>", "Attach to a raw backend session/thread ID (bypasses PaF label store; combine with --session to adopt it)").option("--fast", "Use fast mode when supported (maps to --bare for Claude)").option("--stream", "Stream tokens as they arrive (default)").option("--no-stream", "Disable streaming output (get full response at once)").option("--review", "Use review mode (scoped to diff against base branch)").option("--base <branch>", "Base branch for review diff (default: auto-detect main/master)").option("--quiet", "Run silently, save result to job store").action(async (opts, command) => {
     const isReview = opts.review || opts.base !== void 0;
     if (!opts.prompt && !isReview) {
       console.error(`  ${theme.crossmark} ${theme.error("--prompt is required (unless using --review or --base)")}`);
@@ -80603,9 +80785,10 @@ ${banner("AI coding agent relay")}
       sandbox: resolved.sandbox,
       schema: opts.schema ?? null,
       session: opts.session ?? null,
+      backendSession: opts.backendSession ?? null,
       fast: Boolean(opts.fast)
     };
-    const shouldStream = resolved.stream && !opts.schema && !opts.session;
+    const shouldStream = resolved.stream && !opts.schema && !opts.session && !opts.backendSession;
     if (opts.quiet) {
       const { relayBackground: relayBackground2 } = await Promise.resolve().then(() => (init_relay(), relay_exports));
       const { JobManager: JobManager2 } = await Promise.resolve().then(() => (init_jobs(), jobs_exports));
@@ -80968,6 +81151,71 @@ ${banner("AI coding agent relay")}
     manager.update(id, { status: "cancelled" });
     console.log(`  ${theme.success("\u2713")} Cancelled job ${theme.bold(id)}`);
   });
+  const sessionCmd = program2.command("session").description("Manage persisted relay sessions");
+  sessionCmd.command("list").description("List persisted relay sessions").option("--json", "Output as JSON", false).action(async (opts) => {
+    const { SessionStore: SessionStore2 } = await Promise.resolve().then(() => (init_sessions(), sessions_exports));
+    const store = new SessionStore2();
+    const sessions = store.list();
+    if (opts.json) {
+      console.log(JSON.stringify(sessions, null, 2));
+      return;
+    }
+    if (sessions.length === 0) {
+      console.log(`
+  ${theme.hint("No persisted sessions.")}
+`);
+      return;
+    }
+    console.log(`
+  ${theme.heading("Persisted Sessions")} ${theme.hint(`(${sessions.length})`)}
+`);
+    const sorted = [...sessions].sort((a, b) => b.lastUsedAt.localeCompare(a.lastUsedAt));
+    for (const session of sorted) {
+      const age = timeSince(session.lastUsedAt);
+      const backendSid = session.backendSessionId ?? theme.hint("(none)");
+      console.log(`  ${theme.bold(session.id)}  ${theme.info(session.backend)}  ${theme.hint(age)}`);
+      console.log(`    ${theme.hint("backend session:")} ${backendSid}`);
+      console.log(`    ${theme.hint("repo:")} ${session.repoPath}`);
+      console.log(`    ${theme.hint("history:")} ${session.history.length} entries`);
+    }
+    console.log("");
+  });
+  sessionCmd.command("delete <label>").description("Remove a persisted session by label").action(async (label) => {
+    const { SessionStore: SessionStore2 } = await Promise.resolve().then(() => (init_sessions(), sessions_exports));
+    const store = new SessionStore2();
+    const removed = store.delete(label);
+    if (!removed) {
+      console.error(`  ${theme.crossmark} Session ${theme.bold(label)} not found`);
+      exitCode = 1;
+      return;
+    }
+    console.log(`  ${theme.success("\u2713")} Deleted session ${theme.bold(label)}`);
+  });
+  sessionCmd.command("prune").description("Remove old sessions (default: older than 30 days)").option("--older-than <days>", "Drop sessions whose lastUsedAt is older than N days", "30").option("--all", "Drop every session", false).action(async (opts) => {
+    const { SessionStore: SessionStore2 } = await Promise.resolve().then(() => (init_sessions(), sessions_exports));
+    const store = new SessionStore2();
+    if (opts.all) {
+      const count = store.clear();
+      console.log(`  ${theme.success("\u2713")} Removed ${theme.bold(String(count))} session${count === 1 ? "" : "s"}`);
+      return;
+    }
+    const days = Number(opts.olderThan);
+    if (!Number.isFinite(days) || days <= 0) {
+      console.error(`  ${theme.crossmark} --older-than must be a positive number of days, got "${opts.olderThan}"`);
+      exitCode = 1;
+      return;
+    }
+    const cutoff = new Date(Date.now() - days * 24 * 60 * 60 * 1e3);
+    const removed = store.pruneOlderThan(cutoff);
+    if (removed.length === 0) {
+      console.log(`  ${theme.hint(`No sessions older than ${days} day${days === 1 ? "" : "s"}.`)}`);
+      return;
+    }
+    console.log(`  ${theme.success("\u2713")} Pruned ${theme.bold(String(removed.length))} session${removed.length === 1 ? "" : "s"} older than ${days} day${days === 1 ? "" : "s"}`);
+    for (const id of removed) {
+      console.log(`    ${theme.hint("-")} ${id}`);
+    }
+  });
   addInstallOptions(
     program2.command("install").description("Install Claude plugin (alias for: plugin install)")
   ).action((opts) => installAction(opts));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@freibergergarcia/phone-a-friend",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "CLI relay that lets AI coding agents collaborate",
   "keywords": [
     "ai-agent",