From 3996eaa41f3743af617cb85e9abdc2b8d8b15ab6 Mon Sep 17 00:00:00 2001
From: omartelo <meopedevts@proton.me>
Date: Fri, 21 Aug 2026 19:33:19 -0300
Subject: [PATCH] feat: rename a session from the command line and from an
 agent's tools
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Renaming a card was the one session operation only the window could do.
spawn.Rename is the same rename from outside it: it resolves a session by
either of the names it answers to (the resolver close already had), writes
through store.RenameSession — so the row's label_auto is cleared and the
provider's auto-title never overwrites the name again — and emits the event
the auto-title already emits, which is the whole reason the card relabels
live with no new frontend handler.

`lich rename "the login bug"` renames the session the command runs in;
`lich rename auth-fix "the login bug"` renames another one. The one-argument
form is what an agent has: `sessions` shows it every session but its own, so
it knows what it is doing long before it knows what its card is called. The
`rename_session` tool is the same call.

A name another session in that project already holds is refused rather than
written: two sessions under one label is the one thing `lich send` cannot
resolve, and the guard is what makes a forgotten second argument an error
instead of a silent self-rename. The window keeps no such rule — the user is
pointing at the card they mean.

findSession is now a plain resolver: whether the caller's own session is a
legal answer belongs to the caller, so the refusal to close it moved into
Close, which is also where it finally got a test.
---
 CHANGELOG.md                               |  12 ++
 docs/ceilings.md                           |   7 ++
 docs/cli.md                                |  28 ++++-
 frontend/src/lib/session/session-events.ts |   7 +-
 frontend/src/providers/projects.tsx        |   4 +-
 internal/cli/cli.go                        |  41 +++++++
 internal/cli/cli_test.go                   |   5 +
 internal/cli/help.go                       |   7 ++
 internal/cli/mcp.go                        |  25 ++++
 internal/cli/mcp_test.go                   |  47 ++++++++
 internal/cli/wire_test.go                  |  44 +++++++
 internal/spawn/close.go                    |  18 +--
 internal/spawn/close_test.go               |  13 ++
 internal/spawn/rename.go                   | 105 +++++++++++++++++
 internal/spawn/rename_test.go              | 131 +++++++++++++++++++++
 internal/spawn/spawn.go                    |  12 +-
 internal/spawn/spawn_test.go               |  15 +++
 17 files changed, 504 insertions(+), 17 deletions(-)
 create mode 100644 internal/spawn/rename.go
 create mode 100644 internal/spawn/rename_test.go

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 84bbb56a..68ab276d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **Sessions can be renamed from the command line and from an agent's own
+  tools.** Renaming a card was a thing only the window could do; `lich rename
+  "the login bug"` now renames the session the command runs in, `lich rename
+  auth-fix "the login bug"` renames another one, and the `rename_session` tool is
+  the same for an agent — which is what lets a worker's card say what the work in
+  it is rather than the number it was born with. The name becomes the user's
+  either way: the provider's auto-title never overwrites it again. A name another
+  session in that project already holds is refused, because two sessions under
+  one label is the one thing `lich send` cannot resolve.
+
 ### Changed
 
 - **Building lich from source now needs Go 1.27.0.** The pin stays exact so that
diff --git a/docs/ceilings.md b/docs/ceilings.md
index c77ae3c6..172dda20 100644
--- a/docs/ceilings.md
+++ b/docs/ceilings.md
@@ -103,6 +103,13 @@ work when nobody knows it and that the call site never shows. The mechanism and
   which is why the install asks its version first. Crush's block and omp's `mcp.json` register lich's MCP server by
   the absolute path of the binary that installed it, and omp's is a JSON document lich rewrites rather than appends
   to: every key survives, the user's formatting does not.
+- **A new MCP tool reaches opencode a release later than everyone else** (`internal/cli/mcp.go`, `mcpTools`; the
+  registration table in `docs/cli.md`): every other harness is handed lich's own server, so a tool added here is in
+  that session's list on the next spawn. opencode cannot register an MCP server from a plugin, so its plugin
+  defines each tool itself in the companion repo (`omartelo/lich-plugin`, `opencode/lich.js`) — which means a tool
+  arrives there only once that repo cuts a release and the user reinstalls the plugin, and until they do it is
+  missing from that session's list while it is in every other. `lich rename` works there like anywhere else; it is
+  discovery that lags, which is the whole reason the tools exist.
 - **Only two of the four harnesses that report a tool spell an MCP one splittably** (`frontend/src/lib/session/tool-label.ts`,
   table in `docs/hooks/session-state.md`): Claude Code and Codex send `mcp__<server>__<tool>`, which the card draws
   as `<server> · <tool>`. omp's `mcp__<server>_<tool>` has one underscore doing two jobs — `mcp__lich_list_sessions`
diff --git a/docs/cli.md b/docs/cli.md
index e14fa8b5..f48a81c2 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -351,6 +351,29 @@ conversation back up.
 - Unlike `sessions`, this reaches a card whose terminal was never opened: it is
   still a session, and closing it is the one thing you can do with it.
 
+### `lich rename [--project <name>] [--json] [<session>] <label>`
+
+Renames a session — the name on its card, which is also the name it is addressed
+by. The window's rename, from outside the window.
+
+```
+$ lich rename auth-fix "the login bug"
+Renamed "auth-fix" to "the login bug".
+```
+
+- **One argument is the new name for the session the command runs in**; two are
+  the target and the new name. The one-argument form is what an agent has to
+  work with: `sessions` shows it every session but its own, so it knows what it
+  is doing long before it knows what its card is called.
+- **The name becomes the user's.** As in the window, renaming clears the row's
+  `label_auto`, so the provider's own auto-title never overwrites it again.
+- **A name another session in that project already holds is refused.** Two
+  sessions under one label is the one thing `send` cannot resolve. The window
+  has no such rule — the user is pointing at the card they mean, and can see
+  the other one.
+- The provider's own idea of the session's name is untouched: nothing here runs
+  `/rename` inside the terminal, exactly as the window's rename does not.
+
 ### `lich worktrees [--project <name>] [--json]`
 
 Lists a project's git worktrees — what each is called, whether it holds
@@ -385,6 +408,7 @@ at lich.
 | `reply_to_session` | `ticket`, `answer` — what a relayed message asks for. |
 | `open_session` | optional `project`, `kind`, `worktree`, `base`, `model` — `lich open` — plus optional `prompt` — `lich open --prompt`, the same hand-off in the same call. |
 | `close_session` | `session`, optional `project`, `worktree` (`keep`/`remove`), `force`. |
+| `rename_session` | `label`, optional `session` (omitted renames the caller's own) and `project` — `lich rename`. |
 | `list_worktrees` | optional `project` — the checkouts, as JSON. |
 
 A tool that fails answers with `isError` and the reason as text, not a JSON-RPC
@@ -482,7 +506,7 @@ own command line (`providers.AcceptsMCPServer`):
 | Claude Code | `--mcp-config` with a JSON string, no file on disk | at spawn |
 | Codex | `-c mcp_servers.lich.command=…` and `…args=["mcp"]` | at spawn |
 | Crush | an `mcp add` line in the block the plugin install writes into `crushrc` | with the plugin |
-| opencode | its plugin defines the same seven as tools of its own — a plugin there cannot register an MCP server | with the plugin |
+| opencode | its plugin defines the same eight as tools of its own — a plugin there cannot register an MCP server | with the plugin |
 | oh-my-pi | a `lich` entry merged into `mcp.json` beside the extension the plugin install writes | with the plugin |
 
 Only the first two can be told on their own command line, which is what makes
@@ -682,7 +706,7 @@ whoever asked.
   every tool it has. This does not widen lich's trust boundary (`LICH_TOKEN` is
   already in every PTY, and any process in one can already write to any
   session), but it is the first feature that uses it, and there is no switch.
-- **The tools cost context in every session, used or not.** Seven tool
+- **The tools cost context in every session, used or not.** Eight tool
   definitions are in the prompt of every Claude Code and Codex session lich
   spawns, whether or not that session ever talks to another one. The command
   line costs nothing until it is called; the tools are what buy discovery, and
diff --git a/frontend/src/lib/session/session-events.ts b/frontend/src/lib/session/session-events.ts
index e917e9a1..ef5e6556 100644
--- a/frontend/src/lib/session/session-events.ts
+++ b/frontend/src/lib/session/session-events.ts
@@ -20,8 +20,11 @@ export type SessionEventSource = (handler: (data: unknown) => void) => () => voi
 // id can only reach a subscriber that exists when it is emitted.
 export const STATUS_EVENT = "session-status"
 
-// Global event the backend emits when it auto-applies a session's ai-title as
-// its label (see terminal.titleEventName). Payload: { id, label }.
+// Global event the backend emits when a session's label changed outside the
+// window: an auto-applied ai-title (see terminal.titleEventName), or a rename
+// from the command line or an agent's tools (spawn.RenamedEventName, which is
+// this same name — the window's answer to both is to relabel that card).
+// Payload: { id, label }.
 export const TITLE_EVENT = "session-title"
 
 // Global event the backend emits when a session likely changed files on disk
diff --git a/frontend/src/providers/projects.tsx b/frontend/src/providers/projects.tsx
index 8eaf4c67..eba2469b 100644
--- a/frontend/src/providers/projects.tsx
+++ b/frontend/src/providers/projects.tsx
@@ -168,8 +168,8 @@ export function ProjectsProvider({ children }: { children: ReactNode }) {
     })()
   }, [applyLoaded])
 
-  // The backend auto-applies the Claude ai-title as a session's label (only
-  // while the user has not renamed it) and emits this event with the change.
+  // A label changed outside the window: the auto-applied Claude ai-title (only
+  // while the user has not renamed it), or `lich rename` and its MCP tool.
   // Mirror it into local state so the card updates live; the store already
   // persisted it, so this never writes back.
   useEffect(() => {
diff --git a/internal/cli/cli.go b/internal/cli/cli.go
index 3c19b582..7aca6542 100644
--- a/internal/cli/cli.go
+++ b/internal/cli/cli.go
@@ -112,6 +112,8 @@ func dispatch(args []string, c *client) int {
 		return c.run(c.open, args[1:])
 	case "close":
 		return c.run(c.close, args[1:])
+	case "rename":
+		return c.run(c.rename, args[1:])
 	case "worktrees":
 		return c.run(c.worktrees, args[1:])
 	case "mcp":
@@ -559,6 +561,45 @@ func closedText(closed spawn.Closed) string {
 	}
 }
 
+// rename takes one argument or two: the new name alone renames the session the
+// command is running in, which is the common one an agent has (it knows what it
+// is doing, not what its card is called); a target before it renames that one.
+func (c *client) rename(args []string) error {
+	flags := newFlagSet("rename")
+	project := flags.String("project", "", "narrow the target to one project when the label is ambiguous")
+	asJSON := flags.Bool("json", false, "print the result as JSON")
+	if err := c.parse(flags, args); err != nil {
+		return err
+	}
+	var target, label string
+	switch flags.NArg() {
+	case 1:
+		label = flags.Arg(0)
+	case 2:
+		target, label = flags.Arg(0), flags.Arg(1)
+	default:
+		return usageError("rename")
+	}
+
+	var renamed spawn.Renamed
+	call := []any{c.sessionID(), target, *project, label}
+	if err := c.call("spawn.Rename", call, shortCall, &renamed); err != nil {
+		return err
+	}
+	if *asJSON {
+		return c.emit(renamed)
+	}
+	fmt.Fprint(c.stdout, renamedText(renamed))
+	return nil
+}
+
+// renamedText names both ends of the change: the name that is gone is the half
+// the caller cannot look up afterwards, and the half whoever was addressing that
+// session by it needs to hear.
+func renamedText(renamed spawn.Renamed) string {
+	return fmt.Sprintf("Renamed %q to %q.\n", renamed.Previous, renamed.Label)
+}
+
 func (c *client) worktrees(args []string) error {
 	flags := newFlagSet("worktrees")
 	project := flags.String("project", "", "project to list; defaults to the caller's own")
diff --git a/internal/cli/cli_test.go b/internal/cli/cli_test.go
index 2ef7148f..99d21b98 100644
--- a/internal/cli/cli_test.go
+++ b/internal/cli/cli_test.go
@@ -431,6 +431,11 @@ func TestWrongArgumentCountsFailWithUsage(t *testing.T) {
 		{"sessions", "docs"},
 		{"open", "feature-x"},
 		{"worktrees", "lich"},
+		// rename reads one argument or two, so three is a name with a space in
+		// it that was never quoted — and the last word would silently become
+		// the whole name.
+		{"rename"},
+		{"rename", "docs", "the login", "bug"},
 	}
 	for _, args := range tests {
 		t.Run(strings.Join(args, " "), func(t *testing.T) {
diff --git a/internal/cli/help.go b/internal/cli/help.go
index 30f85342..8d436e91 100644
--- a/internal/cli/help.go
+++ b/internal/cli/help.go
@@ -64,6 +64,13 @@ var commands = []command{
 		about: "Close a session. Closing the last one in a worktree needs --worktree to\n" +
 			"say whether the checkout stays; removing a dirty one needs --force.",
 	},
+	{
+		name: "rename",
+		args: "[--project <name>] [--json] [<session>] <label>",
+		about: "Rename a session's card. With <session> it renames that one, with only a\n" +
+			"name it renames the session the command runs in. The name becomes the\n" +
+			"user's: the provider's auto-title never overwrites it again.",
+	},
 	{
 		name: "worktrees",
 		args: "[--project <name>] [--json]",
diff --git a/internal/cli/mcp.go b/internal/cli/mcp.go
index 2b88e207..7410ae5d 100644
--- a/internal/cli/mcp.go
+++ b/internal/cli/mcp.go
@@ -454,6 +454,31 @@ var mcpTools = []mcpTool{
 			return closedText(closed), nil
 		},
 	},
+	{
+		Name: "rename_session",
+		Description: "Rename a lich session: the name on its card, which is also the name it is " +
+			"addressed by. Omit the session to rename your own — the way a card comes to say " +
+			"what the work in it is, rather than the number it was born with. A name another " +
+			"session in that project already holds is refused, because two sessions under one " +
+			"name is the one thing send_to_session cannot resolve. The name becomes the user's: " +
+			"the provider's own auto-title never overwrites it again.",
+		Schema: schema(map[string]any{
+			"label": property("string", "The new name for the card."),
+			"session": property("string",
+				"Session to rename, by the label on its card or the name it answers to. "+
+					"Omit to rename the session you are running in."),
+			"project": property("string",
+				"Project to narrow to, when the same label exists in more than one."),
+		}, "label"),
+		Run: func(c *client, args mcpArgs) (string, error) {
+			var renamed spawn.Renamed
+			call := []any{c.sessionID(), args.text("session"), args.text("project"), args.text("label")}
+			if err := c.call("spawn.Rename", call, shortCall, &renamed); err != nil {
+				return "", err
+			}
+			return renamedText(renamed), nil
+		},
+	},
 	{
 		Name: "list_worktrees",
 		Description: "The git worktrees of a project: what each is called, whether it has " +
diff --git a/internal/cli/mcp_test.go b/internal/cli/mcp_test.go
index a27e2aa3..17e60961 100644
--- a/internal/cli/mcp_test.go
+++ b/internal/cli/mcp_test.go
@@ -221,6 +221,7 @@ func TestMCPListsEveryTool(t *testing.T) {
 		"list_sessions":    {},
 		"open_session":     {},
 		"close_session":    {"session"},
+		"rename_session":   {"label"},
 		"list_worktrees":   {},
 		"send_to_session":  {"session", "prompt"},
 		"wait_for_answer":  {},
@@ -695,6 +696,52 @@ func TestMCPCloseSessionPassesTheWorktreeAnswer(t *testing.T) {
 	}
 }
 
+func TestMCPRenameSessionPassesTheTargetAndTheName(t *testing.T) {
+	f := newFakeLich(t, `{"id":"9f8e","project":"lich","label":"the login bug","previous":"auth-fix"}`)
+
+	replies := speak(t, f, `{"jsonrpc":"2.0","id":1,"method":"tools/call","params":
+		{"name":"rename_session","arguments":{"session":"auth-fix","label":"the login bug"}}}`)
+
+	text, failed := textOf(t, replies[0])
+	if failed {
+		t.Fatalf("tool reported a failure: %s", text)
+	}
+	if !strings.Contains(text, `"auth-fix" to "the login bug"`) {
+		t.Errorf("text = %q, want both ends of the change", text)
+	}
+	call := f.only(t)
+	want := []any{"s1", "auth-fix", "", "the login bug"}
+	if len(call.args) != len(want) {
+		t.Fatalf("args = %v, want %v", call.args, want)
+	}
+	for i := range want {
+		if call.args[i] != want[i] {
+			t.Errorf("argument %d = %v, want %v", i, call.args[i], want[i])
+		}
+	}
+}
+
+// Omitting the session is how an agent renames its own card, and the empty
+// target is what the app reads as "the caller's own" — so it must be sent, not
+// dropped into the label's slot.
+func TestMCPRenameSessionWithoutATargetRenamesItsOwn(t *testing.T) {
+	f := newFakeLich(t, `{"id":"s1","project":"lich","label":"planner","previous":"Session 1"}`)
+
+	speak(t, f, `{"jsonrpc":"2.0","id":1,"method":"tools/call","params":
+		{"name":"rename_session","arguments":{"label":"planner"}}}`)
+
+	call := f.only(t)
+	want := []any{"s1", "", "", "planner"}
+	if len(call.args) != len(want) {
+		t.Fatalf("args = %v, want %v", call.args, want)
+	}
+	for i := range want {
+		if call.args[i] != want[i] {
+			t.Errorf("argument %d = %v, want %v", i, call.args[i], want[i])
+		}
+	}
+}
+
 // force discards work that is in no commit and on no remote, so only a real yes
 // counts: the boolean, or the one string that spells it. A model that sends
 // "false" — or "yes", which reads like consent and is not the word — must not.
diff --git a/internal/cli/wire_test.go b/internal/cli/wire_test.go
index 7e63fe63..4f415ac4 100644
--- a/internal/cli/wire_test.go
+++ b/internal/cli/wire_test.go
@@ -144,6 +144,8 @@ type spawnStore struct {
 	mu    sync.Mutex
 	rows  int
 	model string
+	// renamed is the session id and label the last rename wrote.
+	renamed [2]string
 }
 
 func (*spawnStore) LoadState() ([]store.Project, error) {
@@ -174,6 +176,13 @@ func (s *spawnStore) DeleteSession(_, _, _ string) error {
 	return nil
 }
 
+func (s *spawnStore) RenameSession(sessionID, label string) error {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	s.renamed = [2]string{sessionID, label}
+	return nil
+}
+
 func (*spawnStore) CloseSession(_, _, _ string) error { return nil }
 
 func (*spawnStore) PurgeWorktreeSessions(_, _ string) error { return nil }
@@ -302,6 +311,41 @@ func TestCloseOverTheRealDispatcher(t *testing.T) {
 	}
 }
 
+// TestRenameOverTheRealDispatcher proves the four arguments `lich rename` posts
+// land on spawn.Rename in the order it declares them. Target and label are two
+// strings side by side, and swapped the command renames the wrong session to the
+// name of the right one.
+func TestRenameOverTheRealDispatcher(t *testing.T) {
+	env, rows, _ := wiredSpawn(t, &spawnGit{})
+
+	var stdout, stderr bytes.Buffer
+	args := []string{"rename", "--project", "lich", "auth-fix", "the login bug"}
+	if code := Run(args, "test", env, &stdout, &stderr); code != 0 {
+		t.Fatalf("exit = %d, stderr = %q", code, stderr.String())
+	}
+	if rows.renamed != [2]string{"s2", "the login bug"} {
+		t.Errorf("renamed = %v, want the target session under the new name", rows.renamed)
+	}
+	if !strings.Contains(stdout.String(), `"auth-fix" to "the login bug"`) {
+		t.Errorf("stdout = %q, want both ends of the change", stdout.String())
+	}
+}
+
+// TestRenameWithoutATargetRenamesTheCallersOwnSession proves the one-argument
+// form reads the label rather than a session: LICH_SESSION_ID is the target, and
+// a client that posted the name in the target's slot would resolve no session.
+func TestRenameWithoutATargetRenamesTheCallersOwnSession(t *testing.T) {
+	env, rows, _ := wiredSpawn(t, &spawnGit{})
+
+	var stdout, stderr bytes.Buffer
+	if code := Run([]string{"rename", "planner"}, "test", env, &stdout, &stderr); code != 0 {
+		t.Fatalf("exit = %d, stderr = %q", code, stderr.String())
+	}
+	if rows.renamed != [2]string{"s1", "planner"} {
+		t.Errorf("renamed = %v, want the calling session under the new name", rows.renamed)
+	}
+}
+
 // TestWorktreesOverTheRealDispatcher proves `lich worktrees` posts the caller's
 // session before the project name: swapped, the app resolves the project by a
 // session id and finds none.
diff --git a/internal/spawn/close.go b/internal/spawn/close.go
index cf235030..20f4aa01 100644
--- a/internal/spawn/close.go
+++ b/internal/spawn/close.go
@@ -60,10 +60,15 @@ func (s *Service) Close(fromID, target, projectName, worktree string, force bool
 	if err != nil {
 		return Closed{}, fmt.Errorf("read the workspace: %w", err)
 	}
-	found, err := findSession(projects, fromID, target, projectName)
+	found, err := findSession(projects, target, projectName)
 	if err != nil {
 		return Closed{}, err
 	}
+	if found.session.ID == fromID {
+		return Closed{}, fmt.Errorf(
+			"%q is this session — closing it would take down the agent asking for it", target,
+		)
+	}
 
 	closed := Closed{
 		ID:        found.session.ID,
@@ -173,7 +178,10 @@ type located struct {
 //
 // Unlike the relay it looks past the live ones: a card whose terminal was never
 // opened is still a session, and closing it is the one thing you can do with it.
-func findSession(projects []store.Project, fromID, target, projectName string) (located, error) {
+//
+// Whether the caller's own session is a legal answer is the caller's rule, not
+// this one's: a close refuses it, a rename is the main thing it is asked for.
+func findSession(projects []store.Project, target, projectName string) (located, error) {
 	target = strings.TrimSpace(target)
 	if target == "" {
 		return located{}, fmt.Errorf("no session given to close")
@@ -204,12 +212,6 @@ func findSession(projects []store.Project, fromID, target, projectName string) (
 
 	switch len(matches) {
 	case 1:
-		if matches[0].session.ID == fromID {
-			return located{}, fmt.Errorf(
-				"%q is this session — closing it would take down the agent asking for it",
-				target,
-			)
-		}
 		return matches[0], nil
 	case 0:
 		where := ""
diff --git a/internal/spawn/close_test.go b/internal/spawn/close_test.go
index 9ecd0e50..46709d7a 100644
--- a/internal/spawn/close_test.go
+++ b/internal/spawn/close_test.go
@@ -84,6 +84,19 @@ func TestCloseRefusesToDecideAWorktreesFateOnItsOwn(t *testing.T) {
 	}
 }
 
+// Closing the session the request came from would take down the agent asking
+// for it, halfway through the call.
+func TestCloseRefusesTheSessionItWasAskedFrom(t *testing.T) {
+	svc, sessions, _, term, _ := closer(t)
+
+	if _, err := svc.Close("s2", "shared-a", "", "", false); err == nil {
+		t.Fatal("closed the session the caller is running in")
+	}
+	if len(sessions.deleted) != 0 || len(term.closed) != 0 {
+		t.Error("wrote something for a close that was refused")
+	}
+}
+
 func TestCloseKeepingAWorktreeParksTheSession(t *testing.T) {
 	svc, sessions, worktrees, _, _ := closer(t)
 
diff --git a/internal/spawn/rename.go b/internal/spawn/rename.go
new file mode 100644
index 00000000..5f7da96b
--- /dev/null
+++ b/internal/spawn/rename.go
@@ -0,0 +1,105 @@
+package spawn
+
+import (
+	"errors"
+	"fmt"
+	"strings"
+
+	"github.com/omartelo/lich/internal/store"
+)
+
+// RenamedEventName carries a session renamed outside the window, so the card
+// takes the new name without a reload.
+//
+// It is the event the auto-applied ai-title already emits
+// (terminal.titleEventName) rather than one of its own: the payload is the same
+// pair and the window's answer to both is the same — relabel that card. A second
+// name for one instruction would have bought a second handler saying it again.
+const RenamedEventName = "session-title"
+
+// renamedEvent is RenamedEventName's payload, the shape terminal's title event
+// writes.
+type renamedEvent struct {
+	ID    string `json:"id"`
+	Label string `json:"label"`
+}
+
+// Renamed is what a caller is told about the session it renamed. Previous is
+// the name that is gone, which is the half the caller cannot look up afterwards.
+type Renamed struct {
+	ID       string `json:"id"`
+	Project  string `json:"project"`
+	Label    string `json:"label"`
+	Previous string `json:"previous"`
+}
+
+// Rename gives a session the name on its card, the window's rename from outside
+// the window. Like the window's, it makes the name the user's: the provider's
+// ai-title never stomps a chosen name again (store.RenameSession).
+//
+// target is the session to rename, by either of the names it answers to; empty
+// renames the caller's own, which is the one form an agent can reach without
+// discovery — list_sessions shows it every session but itself.
+//
+// A name another session in that project already holds is refused rather than
+// written, because two sessions under one label is the one thing `lich send`
+// cannot resolve. The window has no such rule: it renames what the user is
+// pointing at, and the user can see which card they meant.
+func (s *Service) Rename(fromID, target, projectName, label string) (Renamed, error) {
+	label = strings.TrimSpace(label)
+	if label == "" {
+		return Renamed{}, errors.New("a rename needs a name, and none was given")
+	}
+
+	projects, err := s.sessions.LoadState()
+	if err != nil {
+		return Renamed{}, fmt.Errorf("read the workspace: %w", err)
+	}
+	found, err := renameTarget(projects, fromID, target, projectName)
+	if err != nil {
+		return Renamed{}, err
+	}
+	if labelTaken(found.project, label, found.session.ID) {
+		return Renamed{}, fmt.Errorf(
+			"%q already names another session in %s, and two sessions under one name is the "+
+				"one thing `lich send` cannot resolve",
+			label, found.project.Name,
+		)
+	}
+
+	if err := s.sessions.RenameSession(found.session.ID, label); err != nil {
+		return Renamed{}, err
+	}
+	if s.events != nil {
+		s.events.Emit(RenamedEventName, renamedEvent{ID: found.session.ID, Label: label})
+	}
+	return Renamed{
+		ID:       found.session.ID,
+		Project:  found.project.Name,
+		Label:    label,
+		Previous: found.session.Label,
+	}, nil
+}
+
+// renameTarget resolves the session a rename names: the one findSession finds,
+// or the caller's own when the rename named none. A command line run outside a
+// session has no own to fall back on, and is told so rather than handed the
+// resolver's "no session named """.
+func renameTarget(projects []store.Project, fromID, target, projectName string) (located, error) {
+	if strings.TrimSpace(target) != "" {
+		return findSession(projects, target, projectName)
+	}
+	if fromID == "" {
+		return located{}, errors.New(
+			"no session was named to rename, and this is not running in one — name the session",
+		)
+	}
+	for _, p := range projects {
+		for _, sess := range p.Sessions {
+			if sess.ID == fromID {
+				return located{project: p, session: sess}, nil
+			}
+		}
+	}
+	return located{}, fmt.Errorf("this session (%s) is not in the workspace anymore", fromID)
+}
diff --git a/internal/spawn/rename_test.go b/internal/spawn/rename_test.go
new file mode 100644
index 00000000..1c04ff23
--- /dev/null
+++ b/internal/spawn/rename_test.go
@@ -0,0 +1,131 @@
+package spawn
+
+import (
+	"errors"
+	"strings"
+	"testing"
+
+	"github.com/omartelo/lich/internal/store"
+)
+
+func TestRenameGivesTheCardTheNameAndAnnouncesIt(t *testing.T) {
+	svc, sessions, _, _, events := closer(t)
+
+	renamed, err := svc.Rename("s1", "alone", "", "the login bug")
+	if err != nil {
+		t.Fatalf("Rename: %v", err)
+	}
+	if renamed.Previous != "alone" || renamed.Label != "the login bug" {
+		t.Errorf("renamed = %+v, want both ends of the change", renamed)
+	}
+	if sessions.renamed["s4"] != "the login bug" {
+		t.Errorf("renamed = %v, want the target session written under the new name", sessions.renamed)
+	}
+	if len(events.events) != 1 || events.events[0].name != RenamedEventName {
+		t.Errorf("events = %+v, want the card told to relabel", events.events)
+	}
+}
+
+// The caller's own session is the one an agent can reach without discovery —
+// list_sessions shows it every session but itself.
+func TestRenameWithoutATargetRenamesTheCaller(t *testing.T) {
+	svc, sessions, _, _, _ := closer(t)
+
+	renamed, err := svc.Rename("s2", "", "", "shared-worker")
+	if err != nil {
+		t.Fatalf("Rename: %v", err)
+	}
+	if renamed.ID != "s2" || sessions.renamed["s2"] != "shared-worker" {
+		t.Errorf("renamed %+v / %v, want the calling session", renamed, sessions.renamed)
+	}
+}
+
+// Two sessions under one label is the one thing `lich send` cannot resolve, so
+// the write that would create the pair is refused rather than made.
+func TestRenameRefusesALabelAnotherSessionHolds(t *testing.T) {
+	svc, sessions, _, _, events := closer(t)
+
+	_, err := svc.Rename("s1", "alone", "", "Shared-A")
+	if err == nil {
+		t.Fatal("renamed a session onto a label another one already answers to")
+	}
+	if !strings.Contains(err.Error(), "Shared-A") {
+		t.Errorf("error = %q, want it to name the label that is taken", err)
+	}
+	if len(sessions.renamed) != 0 || len(events.events) != 0 {
+		t.Error("wrote something for a rename that was refused")
+	}
+}
+
+// Renaming a session to what it already answers to is not competition with
+// itself — only a differently-cased spelling of its own name.
+func TestRenameAcceptsTheSessionsOwnLabelBack(t *testing.T) {
+	svc, sessions, _, _, _ := closer(t)
+
+	if _, err := svc.Rename("s1", "alone", "", "Alone"); err != nil {
+		t.Fatalf("Rename: %v", err)
+	}
+	if sessions.renamed["s4"] != "Alone" {
+		t.Errorf("renamed = %v, want the recased name written", sessions.renamed)
+	}
+}
+
+func TestRenameRefusesAnEmptyName(t *testing.T) {
+	svc, sessions, _, _, _ := closer(t)
+
+	if _, err := svc.Rename("s1", "alone", "", "   "); err == nil {
+		t.Fatal("accepted a name that is nothing but whitespace")
+	}
+	if len(sessions.renamed) != 0 {
+		t.Error("wrote an empty name")
+	}
+}
+
+// A command line outside any session that names no target has nothing to
+// rename, and is told that rather than handed the resolver's "no session named".
+func TestRenameOutsideASessionNeedsATarget(t *testing.T) {
+	svc, _, _, _, _ := closer(t)
+
+	_, err := svc.Rename("", "", "", "planner")
+	if err == nil {
+		t.Fatal("renamed something for a caller that is in no session")
+	}
+	if !strings.Contains(err.Error(), "name the session") {
+		t.Errorf("error = %q, want it to say what the caller must do", err)
+	}
+}
+
+// A failed write leaves the card alone: the event says the name changed, and a
+// window told that over a row that still holds the old name shows a name that
+// the next reload takes away.
+func TestRenameThatCannotBeWrittenAnnouncesNothing(t *testing.T) {
+	svc, sessions, _, _, events := closer(t)
+	sessions.renameErr = errors.New("disk is gone")
+
+	if _, err := svc.Rename("s1", "alone", "", "planner"); err == nil {
+		t.Fatal("reported a rename the store refused")
+	}
+	if len(events.events) != 0 {
+		t.Errorf("events = %+v, want none for a rename that was not written", events.events)
+	}
+}
+
+// The same label in two projects is ambiguous, exactly as it is for a close.
+func TestRenameNarrowsAnAmbiguousLabelWithTheProject(t *testing.T) {
+	svc, sessions, _, _, _ := closer(t)
+	twin := sessions.projects[0]
+	twin.ID, twin.Name, twin.Path = "p2", "other", "/src/other"
+	twin.Sessions = []store.Session{{ID: "s9", Label: "alone", Kind: "claude", Path: "/wt/alone"}}
+	sessions.projects = append(sessions.projects, twin)
+
+	if _, err := svc.Rename("s1", "alone", "", "planner"); err == nil {
+		t.Fatal("picked one of two sessions answering to the same label")
+	}
+	renamed, err := svc.Rename("s1", "alone", "other", "planner")
+	if err != nil {
+		t.Fatalf("Rename: %v", err)
+	}
+	if renamed.ID != "s9" {
+		t.Errorf("renamed %q, want the session in the project that was named", renamed.ID)
+	}
+}
diff --git a/internal/spawn/spawn.go b/internal/spawn/spawn.go
index 40cb7265..a51db5e7 100644
--- a/internal/spawn/spawn.go
+++ b/internal/spawn/spawn.go
@@ -74,6 +74,7 @@ type Sessions interface {
 		projectID, sessionID, label, kind, path string, nextSeq int, originID, originLabel string,
 	) error
 	SetSessionModel(sessionID, model string) error
+	RenameSession(sessionID, label string) error
 	DeleteSession(projectID, sessionID, activeID string) error
 	CloseSession(projectID, sessionID, activeID string) error
 	PurgeWorktreeSessions(projectID, path string) error
@@ -294,7 +295,7 @@ type checkout struct {
 // unnamed here and takes the project's counter instead.
 func (s *Service) resolveCheckout(target store.Project, worktree, base string) (checkout, error) {
 	label := worktree
-	if labelTaken(target, worktree) {
+	if labelTaken(target, worktree, "") {
 		label = ""
 	}
 	if path, ok := s.checkoutAt(target, worktree); ok {
@@ -436,9 +437,14 @@ func originOf(projects []store.Project, fromID string) (string, string) {
 	return "", ""
 }
 
-// labelTaken reports whether a project already holds a session under a label.
-func labelTaken(p store.Project, label string) bool {
+// labelTaken reports whether a project already holds a session under a label,
+// ignoring the session exceptID names — the one a rename is about to give that
+// label, which is not competition with itself.
+func labelTaken(p store.Project, label, exceptID string) bool {
 	for _, sess := range p.Sessions {
+		if sess.ID == exceptID {
+			continue
+		}
 		if strings.EqualFold(sess.Label, label) {
 			return true
 		}
diff --git a/internal/spawn/spawn_test.go b/internal/spawn/spawn_test.go
index d2422cb1..792ee7ea 100644
--- a/internal/spawn/spawn_test.go
+++ b/internal/spawn/spawn_test.go
@@ -35,6 +35,10 @@ type fakeSessions struct {
 	deleted []closedRow
 	parked  []closedRow
 	purged  []string
+	// renamed records the label each rename wrote, keyed by session id, and
+	// renameErr is the write refusing.
+	renamed   map[string]string
+	renameErr error
 }
 
 // closedRow is one session the store was asked to take out of the workspace.
@@ -54,6 +58,17 @@ func (f *fakeSessions) CloseSession(projectID, sessionID, activeID string) error
 	return nil
 }
 
+func (f *fakeSessions) RenameSession(sessionID, label string) error {
+	if f.renameErr != nil {
+		return f.renameErr
+	}
+	if f.renamed == nil {
+		f.renamed = map[string]string{}
+	}
+	f.renamed[sessionID] = label
+	return nil
+}
+
 func (f *fakeSessions) PurgeWorktreeSessions(_, path string) error {
 	f.purged = append(f.purged, path)
 	return nil