dsh-agent-lines 0.3.5 → 0.3.7

package/CHANGELOG.en.md

@@ -2,6 +2,22 @@
 
 English | [中文](CHANGELOG.md)
 
+## 0.3.7 (2026-11-09)
+
+- Added line_handoff: structured handoff snapshots (JSON/Markdown), no model call.
+- line_status / line_list now expose lifecycle/title/generation/pending/lastActivityAt/oldSessionId.
+- rebind sends a noReply handoff notice to the new line; replace reuses the onboarding message.
+- list --json can feed an external dashboard; added examples/dashboard notes.
+- Tests 33/33 pass.
+
+## 0.3.6 (2026-11-09)
+
+- Added line lifecycle: line_retire, line_rebind, line_create replace:true, line_rename.
+- Schema v7: lines.title/lifecycle/generation/rebind_at/rebind_from + line_events audit; additive migration from v6.
+- Backlog migration: queued/claimed migrate; delivered/acked are never re-delivered; migrate:none fails closed when backlog is non-empty.
+- Persistent titles: line_create/line_rename write lines.title and survive restarts.
+- Tests 32/32 pass; existing 0.3.5 behavior unchanged.
+
 ## 0.3.5 (2026-11-05)
 
 - Integrated P0/P1 bootstrap: line_create queues an onboarding message by default, adds bootstrapOnCreate, and line_status/line_list expose materialized / visibleInSidebar / bootstrapQueued.
@@ -69,4 +85,4 @@ English | [中文](CHANGELOG.md)
 - Explicit `delivered` vs `acked`; at-least-once with effectively-once Session log semantics.
 - Local filesystem check (NFS/CIFS/SMB/FUSE refused).
 
-Not included: HTTP transport, Web UI, Postgres adapter, automatic process wake.
+Not included: HTTP transport, Web UI, Postgres adapter, automatic process wake.

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 [English](CHANGELOG.en.md) | 中文
 
+## 0.3.7 (2026-11-09)
+
+- 新增 line_handoff：结构化交接快照（JSON/Markdown），不调用模型。
+- line_status / line_list 增加 lifecycle/title/generation/pending/lastActivityAt/oldSessionId。
+- rebind 后给新线发 noReply 交接通知；replace 复用 onboarding 消息。
+- list --json 可直接喂给外部看板；新增 examples/dashboard 说明。
+- 测试 33/33 通过。
+
+## 0.3.6 (2026-11-09)
+
+- 新增线生命周期：line_retire、line_rebind、line_create replace:true、line_rename。
+- schema v7：lines.title/lifecycle/generation/rebind_at/rebind_from + line_events 审计；旧 DB additive 迁移。
+- 积压迁移：queued/claimed 迁移，delivered/acked 不重投；migrate:none 在 backlog 非空时 fail-closed。
+- 标题持久化：line_create/line_rename 写 lines.title，重启保留。
+- 测试 32/32 通过；旧 0.3.5 行为不变。
+
 ## 0.3.5 (2026-11-05)
 
 - 集成 P0/P1 bootstrap：line_create 默认排队 onboarding 消息，新增 bootstrapOnCreate，line_status/line_list 暴露 materialized / visibleInSidebar / bootstrapQueued。
@@ -68,4 +84,4 @@
 - 显式区分 delivered 和 acked；至少一次投递，Session 日志有效一次。
 - 本地文件系统检查（拒绝 NFS/CIFS/SMB/FUSE）。
 
-未包含：HTTP transport、Web UI、Postgres adapter、自动拉起进程。
+未包含：HTTP transport、Web UI、Postgres adapter、自动拉起进程。

package/README.en.md

@@ -36,7 +36,7 @@ The script picks the DSH Web profile, installs the plugin, and verifies agent-li
 
 Offline or when npm is unavailable, use the local tarball:
 
-    bash install.sh ./dsh-agent-lines-0.3.5.tgz
+    bash install.sh ./dsh-agent-lines-0.3.7.tgz
 
 After install and restart, it works without a config. When you want a fixed manager/worker setup, paste the "Manager config" block below into the file printed by the installer.
 
@@ -137,7 +137,11 @@ Tools:
 | `line_status` | Read-only: current Session binding, manager Session live/persisted, lines, repair command; visible even when unbound |
 | `line_claim_manager` | Bind this live root Session as manager; requires `allowClaim: true` and `confirm: "bind-manager"`; global, no shell needed |
 | `line_list` | List lines, status, unread counts, current line and role |
-| `line_create` | Manager only: create a DSH Session in the manager workspace (or a named existing workspace) and register it as a line; same label is idempotent |
+| `line_create` | Manager only: create a line; same label is idempotent; replace:true swaps the label to a fresh Session |
+| `line_handoff` | Manager only: structured handoff snapshot (JSON/Markdown), no model call |
+| `line_retire` | Manager only: soft-retire; reject new sends, keep Session and history |
+| `line_rebind` | Manager only: atomically switch a line to a new live Session, optionally migrating backlog |
+| `line_rename` | Manager only: rename the sidebar title and persist it in lines.db |
 | `line_move_workspace` | Manager only: attach an existing line Session to a workspace whose path exactly matches the Session cwd |
 | `line_send` | Send to `line` or `agent#line`; optional `idempotencyKey`, `replyTo`, `noReply`, `forceDistinct`, `ttlMs` |
 | `line_inbox` | Read delivered messages for the current line |
@@ -147,6 +151,17 @@ Line tools other than `line_status` and `line_claim_manager` are registered only
 
 `line_create` creates an ordinary DSH Session in the manager workspace (or in the manager cwd when no workspace exists). It does **not** create a separate OS process, profile, or port; all lines in that call share the DSH process. It also does not transfer an existing Session.
 
+### Replacing a line when context is full
+
+A line does not inherit the old Session context. Recommended flow:
+
+1. Have the old line write a handoff file (line_handoff is available from 0.3.7);
+2. The manager calls `line_create({ label, replace: true, force: true, reason: "context full" })`;
+3. The plugin creates a clean Session, atomically swaps the same label, and marks the old Session retired but keeps it;
+4. queued/claimed messages migrate to the new line; delivered/acked stay on the old Session and are never re-delivered.
+
+With `migrate: "none"`, a non-empty queue returns `LINE_BACKLOG_NOT_EMPTY` instead of silently switching.
+
 Created lines are recorded with `created_by` and restored by the manager on process startup. line_create uses the manager's workspace (workspaceId, so DSH attaches the Session) when one exists; otherwise it falls back to the manager cwd and the line is ungrouped. Pass `workspace` (existing path or id) to create in another workspace. A line whose Session was never materialized may fail on first delivery with `session/not-found`; send it a task (or recreate it) to persist the Session.
 
 CLI:
@@ -274,4 +289,4 @@ See [CONTRIBUTING.en.md](CONTRIBUTING.en.md); code of conduct [CODE_OF_CONDUCT.e
 
 ## License
 
-Apache-2.0. See [LICENSE](LICENSE).
+Apache-2.0. See [LICENSE](LICENSE).

package/README.md

@@ -36,7 +36,7 @@ DSH 的 super agent 平替插件。
 
 离线或 npm 不可用时，用本地 tarball：
 
-    bash install.sh ./dsh-agent-lines-0.3.5.tgz
+    bash install.sh ./dsh-agent-lines-0.3.7.tgz
 
 安装并重启后，不写配置也可以直接使用；需要固定管理线/worker 时，再把下面“管理线配置”粘贴到脚本打印的配置文件。
 
@@ -137,7 +137,11 @@ line_create({ label: "ops", role: "运维" })
 | `line_status` | 只读：当前会话绑定、manager Session 是否存在/live、线列表、修复命令；未绑定也可见 |
 | `line_claim_manager` | 把当前 live 根 Session 绑成 manager；需要 `allowClaim: true` 和 `confirm: "bind-manager"`；全局工具，不需要 shell |
 | `line_list` | 列出线、状态、未读数、当前线和 role |
-| `line_create` | 仅管理线：在管理线工作区（或指定的已有工作区）创建 DSH Session 并注册为线；同 label 幂等 |
+| `line_create` | 仅管理线：创建新线；同 label 幂等；传 replace:true 可给同 label 换新 Session |
+| `line_handoff` | 仅管理线：生成结构化交接单（JSON/Markdown），不调模型 |
+| `line_retire` | 仅管理线：软下线；拒绝新发送，保留 Session/历史 |
+| `line_rebind` | 仅管理线：把线原子切到新的 live Session，可迁移积压 |
+| `line_rename` | 仅管理线：改侧栏标题，持久化到 lines.db |
 | `line_move_workspace` | 仅管理线：把已有线的 Session 挂到路径完全匹配的工作区 |
 | `line_send` | 发到 `line` 或 `agent#line`；可选 `idempotencyKey`、`replyTo`、`noReply`、`forceDistinct`、`ttlMs` |
 | `line_inbox` | 读当前线已投递消息 |
@@ -147,6 +151,17 @@ line_create({ label: "ops", role: "运维" })
 
 `line_create` 在管理线所属工作区（没有工作区时回退当前目录）创建普通 DSH Session；它**不会**创建独立 OS 进程、profile 或端口，也不转移已有 Session。
 
+### 上下文满时换人
+
+线不会自动继承旧 Session 的上下文。推荐流程：
+
+1. 让旧线写交接单（0.3.7 起可用 `line_handoff`）；
+2. 管理线调用 `line_create({ label, replace: true, force: true, reason: "context full" })`；
+3. 插件创建干净 Session、同 label 原子切换，旧 Session 标记 retired 但保留；
+4. queued/claimed 消息迁移到新线；delivered/acked 留在旧 Session，不重投。
+
+`migrate: "none"` 时若还有 queued/claimed 会直接报 `LINE_BACKLOG_NOT_EMPTY`，不会静默切走。
+
 创建的线会记录 `created_by`，进程重启时由管理线恢复。line_create 会解析管理线所属工作区并传 workspaceId（DSH 会自动 attach），所以新线出现在该工作区而不是“未分组”；如果管理线本身不在工作区，则回退 cwd，线保持未分组。传 `workspace`（已有路径或 id）可指定其他工作区。若某条线的 Session 还从未落盘，首次投递可能 `session/not-found`；给它发一条任务（或重新创建）即可让它持久化。
 
 CLI：
@@ -267,4 +282,4 @@ claim 不会对每个新会话自动执行：需要用户明确要求，或运
 
 ## 许可
 
-Apache-2.0，见 [LICENSE](LICENSE)。
+Apache-2.0，见 [LICENSE](LICENSE)。

package/docs/PROTOCOL.en.md

@@ -98,6 +98,21 @@ The new line is an ordinary DSH Session in the same DSH process; no OS process,
 
 `line_move_workspace({ line, workspace })` attaches an existing line Session to an existing workspace. DSH's `attachSession` validates that the Session's stored cwd resolves exactly to the workspace path; a different directory fails with `WORKSPACE_ATTACH_FAILED`. It does not move a Session between different directories. If Session creation succeeds but registration fails, the error carries `detail.sessionId` and the Session is not deleted automatically.
 
+## Line lifecycle (0.3.6)
+
+    line_retire({ line, reason? })
+    line_rebind({ line, sessionId, migrate?: "queued" | "none", reason? })
+    line_create({ label, replace: true, force?, migrate?, title?, reason? })
+    line_handoff({ line, format?: "md" | "json", limit?: number })
+    line_rename({ line, title })
+
+- retired: line_send returns LINE_RETIRED; the Session and history are kept.
+- rebind: atomically switches lines.session_id and increments generation; the old Session is never deleted.
+- migrate=queued: queued/claimed messages move to the new Session; delivered/acked are never re-delivered.
+- migrate=none: returns LINE_BACKLOG_NOT_EMPTY if the backlog is non-empty.
+- replace: creates a fresh Session for the same label and rebinds; an active line requires force + reason.
+- line_events records title/retire/rebind audit; titles survive restarts.
+
 ## Echo and reply depth
 
 - `rootMessageId` groups a reply chain; a root message has null.
@@ -141,4 +156,4 @@ The new line is an ordinary DSH Session in the same DSH process; no OS process,
 | `LINE_NO_REPLY` | Reply to a noReply message |
 | `LINE_REPLY_DEPTH_EXCEEDED` | Reply chain exceeds maxReplyDepth |
 | `LINE_REPLY_TARGET_NOT_FOUND` | replyTo names an unknown message |
-| `session/writer-held` (DSH) | Another DSH process holds the target Session's writer lock; close the other view or use a dedicated Session |
+| `session/writer-held` (DSH) | Another DSH process holds the target Session's writer lock; close the other view or use a dedicated Session |

package/docs/PROTOCOL.md

@@ -90,6 +90,21 @@ line_create 通过 workspaceRegistry.resolveByPath(managerCwd) 解析管理线
 
 line_move_workspace({ line, workspace }) 把已有线 Session 挂到已有工作区。DSH 的 attachSession 要求 Session 存储的 cwd 与工作区 path 完全一致；不同目录会 WORKSPACE_ATTACH_FAILED，不会迁移 Session。如果 Session 创建成功但注册失败，错误里带 detail.sessionId，Session 不会自动删除。
 
+## 线生命周期（0.3.6）
+
+    line_retire({ line, reason? })
+    line_rebind({ line, sessionId, migrate?: "queued" | "none", reason? })
+    line_create({ label, replace: true, force?, migrate?, title?, reason? })
+    line_handoff({ line, format?: "md" | "json", limit?: number })
+    line_rename({ line, title })
+
+- retired：line_send 返回 LINE_RETIRED；Session 和消息历史保留。
+- rebind：原子切换 lines.session_id，generation+1；旧 Session 不删除。
+- migrate=queued：queued/claimed 迁移到新 Session；delivered/acked 不重投。
+- migrate=none：backlog 非空时返回 LINE_BACKLOG_NOT_EMPTY。
+- replace：同 label 创建新 Session 并 rebind；active 线需 force + reason。
+- line_events 记录 title/retire/rebind 审计；title 持久化，重启保留。
+
 ## 回声与回复深度
 
 - rootMessageId 标识回复链；根消息为 null。
@@ -133,4 +148,4 @@ line_move_workspace({ line, workspace }) 把已有线 Session 挂到已有工作
 | LINE_NO_REPLY | 回复 noReply 消息 |
 | LINE_REPLY_DEPTH_EXCEEDED | 回复链超过 maxReplyDepth |
 | LINE_REPLY_TARGET_NOT_FOUND | replyTo 指向未知消息 |
-| session/writer-held (DSH) | 另一个 DSH 进程持有目标 Session 的 writer 锁；关闭另一个视图或使用专用 Session |
+| session/writer-held (DSH) | 另一个 DSH 进程持有目标 Session 的 writer 锁；关闭另一个视图或使用专用 Session |

package/docs/en/index.html

@@ -43,7 +43,7 @@ footer{padding:34px 0 48px;color:var(--muted);font-size:12px}
 <div class="wrap">
 <header>
   <a class="brand" href="../"><span class="mark"></span>dsh-agent-lines</a>
-  <nav><a href="../">中文</a><a href="https://github.com/Lencen/dsh-agent-lines">GitHub</a><a href="https://github.com/Lencen/dsh-agent-lines/releases/tag/v0.3.5">Release</a></nav>
+  <nav><a href="../">中文</a><a href="https://github.com/Lencen/dsh-agent-lines">GitHub</a><a href="https://github.com/Lencen/dsh-agent-lines/releases/tag/v0.3.7">Release</a></nav>
 </header>
 <main>
 <section class="hero" style="border:0;padding-bottom:22px">
@@ -54,7 +54,7 @@ footer{padding:34px 0 48px;color:var(--muted);font-size:12px}
     <div class="install">curl -fsSL https://raw.githubusercontent.com/Lencen/dsh-agent-lines/main/install.sh -o install.sh &amp;&amp; bash install.sh</div>
     <div class="actions">
       <a class="btn primary" href="https://github.com/Lencen/dsh-agent-lines">GitHub repository</a>
-      <a class="btn" href="https://github.com/Lencen/dsh-agent-lines/releases/tag/v0.3.5">Download 0.3.5</a>
+      <a class="btn" href="https://github.com/Lencen/dsh-agent-lines/releases/tag/v0.3.7">Download 0.3.7</a>
     </div>
   </div>
   <div class="shot">
@@ -92,8 +92,8 @@ research (调研), architecture (架构), uiux (UIUX), dev (开发), test (测
 After the team is ready, wait for my first task. Do not start by yourself.</pre>
   <p style="color:var(--muted);font-size:14px">Restart DSH Web after install or update. Technical details, protocol, and limits: <a href="https://github.com/Lencen/dsh-agent-lines">README / architecture</a>. Community plugin, not an official DeepSeek product.</p>
 </section>
-<footer>dsh-agent-lines 0.3.5 · Apache-2.0 · Community plugin for DeepSeek Harness. Not an official DeepSeek product.</footer>
+<footer>dsh-agent-lines 0.3.7 · Apache-2.0 · Community plugin for DeepSeek Harness. Not an official DeepSeek product.</footer>
 </main>
 </div>
 </body>
-</html>
+</html>

package/docs/index.html

@@ -43,7 +43,7 @@ footer{padding:34px 0 48px;color:var(--muted);font-size:12px}
 <div class="wrap">
 <header>
   <a class="brand" href="./"><span class="mark"></span>dsh-agent-lines</a>
-  <nav><a href="en/index.html">English</a><a href="https://github.com/Lencen/dsh-agent-lines">GitHub</a><a href="https://github.com/Lencen/dsh-agent-lines/releases/tag/v0.3.5">Release</a></nav>
+  <nav><a href="en/index.html">English</a><a href="https://github.com/Lencen/dsh-agent-lines">GitHub</a><a href="https://github.com/Lencen/dsh-agent-lines/releases/tag/v0.3.7">Release</a></nav>
 </header>
 <main>
 <section class="hero" style="border:0;padding-bottom:22px">
@@ -54,7 +54,7 @@ footer{padding:34px 0 48px;color:var(--muted);font-size:12px}
     <div class="install">curl -fsSL https://raw.githubusercontent.com/Lencen/dsh-agent-lines/main/install.sh -o install.sh &amp;&amp; bash install.sh</div>
     <div class="actions">
       <a class="btn primary" href="https://github.com/Lencen/dsh-agent-lines">GitHub 仓库</a>
-      <a class="btn" href="https://github.com/Lencen/dsh-agent-lines/releases/tag/v0.3.5">下载 0.3.5</a>
+      <a class="btn" href="https://github.com/Lencen/dsh-agent-lines/releases/tag/v0.3.7">下载 0.3.7</a>
     </div>
   </div>
   <div class="shot">
@@ -92,8 +92,8 @@ research（调研）、architecture（架构）、uiux（UIUX）、dev（开发
 团队建好后先待命，不要自动开工，等我发第一个任务。</pre>
   <p style="color:var(--muted);font-size:14px">安装或更新后需要重启 DSH Web。技术细节、协议和限制见 <a href="https://github.com/Lencen/dsh-agent-lines">README / 架构文档</a>。社区插件，不是 DeepSeek 官方产品。</p>
 </section>
-<footer>dsh-agent-lines 0.3.5 · Apache-2.0 · Community plugin for DeepSeek Harness. Not an official DeepSeek product.</footer>
+<footer>dsh-agent-lines 0.3.7 · Apache-2.0 · Community plugin for DeepSeek Harness. Not an official DeepSeek product.</footer>
 </main>
 </div>
 </body>
-</html>
+</html>

package/docs/market-index.json

@@ -50,11 +50,11 @@
         ]
       },
       "dist-tags": {
-        "latest": "0.3.5"
+        "latest": "0.3.7"
       },
       "versions": [
         {
-          "version": "0.3.5",
+          "version": "0.3.7",
           "publishTimestamp": 1793771000,
           "source": {
             "type": "npm"
@@ -66,4 +66,4 @@
       ]
     }
   ]
-}
+}

package/examples/dashboard/README.md

@@ -0,0 +1,16 @@
+# Dashboard example
+
+The plugin deliberately does not run an HTTP server. Read the same SQLite queue with:
+
+~~~bash
+dsh-agent-lines --json list
+~~~
+
+Fields: label/title/role/lifecycle/generation/pending/unread/lastActivityAt/lease.
+The Surface feedback dashboard (refresh-dashboard.js) can consume this JSON and keep its own directory scan.
+
+For a handoff snapshot before replacing a line:
+
+~~~text
+line_handoff({ line: "writer", format: "json" })
+~~~

package/examples/market-index.json

@@ -50,11 +50,11 @@
         ]
       },
       "dist-tags": {
-        "latest": "0.3.5"
+        "latest": "0.3.7"
       },
       "versions": [
         {
-          "version": "0.3.5",
+          "version": "0.3.7",
           "publishTimestamp": 1793771000,
           "source": {
             "type": "npm"
@@ -66,4 +66,4 @@
       ]
     }
   ]
-}
+}

package/lib/index.js

@@ -34,7 +34,8 @@ function normalizeLine(entry, agentId, index) {
   const sessionId = String(entry.sessionId ?? '').trim()
   if (sessionId.length === 0) throw new LineError('LINE_INVALID_CONFIG', `lines[${index}].sessionId is required`)
   const role = entry.role === undefined || entry.role === null ? null : String(entry.role).trim() || null
-  return { agentId, label, sessionId, lineId: lineId(agentId, label), role }
+  const title = entry.title === undefined || entry.title === null ? null : String(entry.title).trim() || null
+  return { agentId, label, sessionId, lineId: lineId(agentId, label), role, title }
 }
 
 /** Validate and normalize plugin config. Exported for tests and the CLI. */
@@ -131,7 +132,7 @@ export async function apply(ctx, rawConfig) {
     if (def === undefined || bindings.has(agent.session.id)) return
     const binding = {
       prompt: bindAgentPrompt(agent, def),
-      tools: registerToolsForAgent(agent, def, { config, store, lineDefs, createLine, moveLineWorkspace }),
+      tools: registerToolsForAgent(agent, def, { config, store, lineDefs, createLine, moveLineWorkspace, retireLine, rebindLine, renameLine }),
     }
     bindings.set(agent.session.id, binding)
   }
@@ -147,10 +148,21 @@ export async function apply(ctx, rawConfig) {
     }
   }
 
+  const renameTitle = async (def) => {
+    if (def.sessionId === undefined || def.sessionId === '') return
+    const title = String(def.title || def.role || def.label || 'agent line').slice(0, 120)
+    try {
+      await ctx.sessionController?.rename?.({ sessionId: def.sessionId, title })
+    } catch (error) {
+      ctx.logger?.warn?.('agent-lines: rename %s failed: %s', def.label, String(error))
+    }
+  }
+
   const startLoop = (def) => {
     const loop = new DeliveryLoop({ ctx, config: loopConfig(config, def), store, logger: ctx.logger })
     loops.push(loop)
     loop.start()
+    void renameTitle(def)
   }
 
   const sessionExists = async (sessionId) => {
@@ -281,13 +293,156 @@ export async function apply(ctx, rawConfig) {
   }
   process.once('exit', releaseAll)
 
+  const rebinding = new Set()
+
+  const lineTitle = (def, row) => String((row && row.title) || (def && def.title) || (def && def.role) || (def && def.label) || 'agent line').slice(0, 120)
+
+  const rebindLine = async ({ label, sessionId, actor, reason, migrate = 'queued', force = false, notify = true }) => {
+    if (label === config.createFrom) throw new LineError('LINE_MANAGER_REBIND_UNSUPPORTED', 'The manager line is rebound with line_claim_manager, not line_rebind', { line: label })
+    const row = store.getLineRow(config.agentId, label)
+    if (row === undefined) throw new LineError('LINE_NOT_FOUND', `No such line: ${config.agentId}#${label}`)
+    if (rebinding.has(label) || row.lifecycle === 'rebinding') throw new LineError('LINE_REBIND_BUSY', `Line ${label} is already rebinding`, { line: label })
+    if (!(await sessionExists(sessionId))) throw new LineError('LINE_SESSION_NOT_FOUND', `Session is not live or persisted: ${sessionId}`, { sessionId })
+    const target = lineDefs.get(sessionId)
+    if (target !== undefined && target.label !== label) throw new LineError('LINE_SESSION_BOUND', `Session ${sessionId} is already bound to ${target.label}`, { sessionId, line: target.label })
+    const oldDef = [...lineDefs.values()].find(line => line.label === label)
+    if (oldDef !== undefined && oldDef.sessionId === sessionId) {
+      return { line: label, oldSessionId: row.session_id, newSessionId: sessionId, generation: row.generation, counts: store.messageCounts({ agentId: config.agentId, line: label }), already: true }
+    }
+    const oldLifecycle = row.lifecycle || 'active'
+    const oldAgent = oldDef === undefined ? undefined : ctx.agents.get(oldDef.sessionId)
+    rebinding.add(label)
+    let locked = false
+    try {
+      store.setLifecycle({ agentId: config.agentId, line: label, lifecycle: 'rebinding', actor, reason })
+      locked = true
+      await stopLoopFor(label)
+      if (oldDef !== undefined) lineDefs.delete(oldDef.sessionId)
+      if (oldAgent !== undefined) unbindAgent(oldAgent)
+      const updated = store.rebind({
+        agentId: config.agentId, line: label, sessionId, actor, reason, migrate, locked: true,
+      })
+      const def = {
+        agentId: config.agentId, label, sessionId, lineId: lineId(config.agentId, label),
+        role: (oldDef && oldDef.role) || row.role || null,
+        title: lineTitle(oldDef, updated), createdBy: row.created_by || (oldDef && oldDef.createdBy) || null,
+        lifecycle: 'active', generation: updated.generation,
+      }
+      lineDefs.set(sessionId, def)
+      startLoop(def)
+      const agent = ctx.agents.get(sessionId)
+      if (agent !== undefined) bindAgent(agent)
+      if (notify !== false) {
+        try {
+          store.send({
+            agentId: config.agentId, fromLine: config.createFrom, to: label,
+            text: `[Agent Line] ${label} switched to a fresh Session. old=${row.session_id} new=${sessionId} migrated=${JSON.stringify(updated.counts)}. Read the handoff file before continuing.`,
+            noReply: true, maxReplyDepth: config.maxReplyDepth, maxMessageBytes: config.maxMessageBytes,
+          })
+        } catch (error) { ctx.logger?.warn?.('agent-lines: rebind notification failed: %s', String(error)) }
+      }
+      return { line: label, oldSessionId: row.session_id, newSessionId: sessionId, generation: updated.generation, counts: updated.counts }
+    } catch (error) {
+      try { await stopLoopFor(label) } catch { /* best effort */ }
+      if (oldDef !== undefined) {
+        lineDefs.set(oldDef.sessionId, oldDef)
+        startLoop(oldDef)
+        const agent = ctx.agents.get(oldDef.sessionId)
+        if (agent !== undefined) bindAgent(agent)
+      }
+      if (locked) {
+        try { store.setLifecycle({ agentId: config.agentId, line: label, lifecycle: oldLifecycle === 'rebinding' ? 'active' : oldLifecycle, actor, reason: 'rebind rollback' }) } catch { /* best effort */ }
+      }
+      throw error
+    } finally {
+      rebinding.delete(label)
+    }
+  }
+
+  const retireLine = async ({ label, actor, reason }) => {
+    if (label === config.createFrom) throw new LineError('LINE_MANAGER_RETIRE_UNSUPPORTED', 'The manager line cannot be retired', { line: label })
+    const row = store.getLineRow(config.agentId, label)
+    if (row === undefined) throw new LineError('LINE_NOT_FOUND', `No such line: ${config.agentId}#${label}`)
+    const def = [...lineDefs.values()].find(line => line.label === label)
+    if (def !== undefined) def.lifecycle = 'retired'
+    await stopLoopFor(label)
+    const updated = store.retire({ agentId: config.agentId, line: label, actor, reason })
+    return { line: label, lifecycle: updated.lifecycle, counts: updated.counts, already: row.lifecycle === 'retired' }
+  }
+
+  const renameLine = async ({ label, title, actor }) => {
+    const row = store.getLineRow(config.agentId, label)
+    if (row === undefined) throw new LineError('LINE_NOT_FOUND', `No such line: ${config.agentId}#${label}`)
+    const updated = store.setTitle({ agentId: config.agentId, line: label, title, actor })
+    const def = [...lineDefs.values()].find(line => line.label === label)
+    if (def !== undefined) def.title = updated.title
+    try { await ctx.sessionController?.rename?.({ sessionId: row.session_id, title: updated.title || title }) } catch { /* blank session can rename later */ }
+    return { line: label, title: updated.title }
+  }
+
+  const replaceLine = async (existing, args, exec) => {
+    if (existing.label === config.createFrom) throw new LineError('LINE_MANAGER_REBIND_UNSUPPORTED', 'The manager line cannot be replaced', { line: existing.label })
+    if (existing.lifecycle === 'active' && args.force !== true) {
+      throw new LineError('LINE_REPLACE_ACTIVE', `Line ${existing.label} is active; pass force:true to replace it`, { line: existing.label, lifecycle: existing.lifecycle })
+    }
+    if (args.migrate === 'none') {
+      const backlog = store.messageCounts({ agentId: config.agentId, line: existing.label })
+      if (backlog.queued + backlog.claimed > 0) {
+        throw new LineError('LINE_BACKLOG_NOT_EMPTY', `Line ${existing.label} has ${backlog.queued + backlog.claimed} queued/claimed messages`, { line: existing.label, counts: backlog })
+      }
+    }
+    const baseCwd = exec?.agent?.session?.header?.cwd ?? process.cwd()
+    if (args.workspace !== undefined && args.cwd !== undefined) throw new LineError('LINE_INVALID_ARGUMENT', 'workspace and cwd are mutually exclusive')
+    const cwd = args.cwd === undefined || String(args.cwd).trim() === '' ? baseCwd : resolve(baseCwd, String(args.cwd).trim())
+    const targetWorkspace = args.workspace !== undefined ? await resolveWorkspace(args.workspace) : await managerWorkspace(baseCwd)
+    const role = args.role === undefined || args.role === null ? null : String(args.role).trim() || null
+    const title = args.title === undefined || args.title === null ? (role || existing.title || existing.role || existing.label) : String(args.title).trim().slice(0, 120)
+    const sessionId = `session-${randomUUID()}`
+    const created = await ctx.sessionController.create({
+      sessionId,
+      ...(targetWorkspace === undefined ? { cwd } : { workspaceId: targetWorkspace.id }),
+      agentPreset: args.agentPreset === undefined ? config.childPreset : String(args.agentPreset),
+    })
+    const actualSessionId = created.sessionId
+    const result = await rebindLine({
+      label: existing.label, sessionId: actualSessionId, actor: (exec && exec.agent && exec.agent.session && exec.agent.session.id) || null,
+      reason: String(args.reason || 'line_create replace'), migrate: args.migrate === 'none' ? 'none' : 'queued', force: args.force === true, notify: false,
+    })
+    const newDef = lineDefs.get(actualSessionId)
+    if (newDef !== undefined) {
+      newDef.role = role
+      newDef.title = title
+      try { store.setTitle({ agentId: config.agentId, line: existing.label, title }) } catch { /* best effort */ }
+    }
+    let bootstrapQueued = false
+    if (args.bootstrap !== false && config.bootstrapOnCreate !== false) {
+      const creator = lineDefs.get(exec.agent.session.id)
+      if (creator !== undefined) {
+        try {
+          store.send({
+            agentId: config.agentId, fromLine: creator.label, to: existing.label,
+            text: `[Agent Line] ${existing.label} replaced. You are ${role ?? existing.role ?? existing.label}. Read the handoff file before starting; this is an identity message, do not modify files yet.`,
+            noReply: true, maxReplyDepth: config.maxReplyDepth, maxMessageBytes: config.maxMessageBytes,
+          })
+          bootstrapQueued = true
+        } catch (error) { ctx.logger?.warn?.('agent-lines: replace bootstrap failed: %s', String(error)) }
+      }
+    }
+    return {
+      line: existing.label, sessionId: actualSessionId, oldSessionId: result.oldSessionId,
+      role, title, created: true, replaced: true, generation: result.generation, counts: result.counts,
+      cwd: targetWorkspace?.path ?? cwd, workspaceId: targetWorkspace?.id ?? null, bootstrapQueued,
+    }
+  }
+
   const createLine = async (args, exec) => {
     if (closed) throw new LineError('LINE_CLOSED', 'The agent-lines plugin is shutting down')
     if (!config.allowCreate) throw new LineError('LINE_CREATE_DISABLED', 'line_create is disabled by config')
     const label = validateLineLabel(args.label)
     const existing = store.getLineRow(config.agentId, label)
     if (existing !== undefined) {
-      return { line: existing.label, sessionId: existing.session_id, role: existing.role, created: false }
+      if (args.replace === true) return replaceLine(existing, args, exec)
+      return { line: existing.label, sessionId: existing.session_id, role: existing.role, title: existing.title ?? existing.role ?? existing.label, lifecycle: existing.lifecycle, created: false }
     }
     if (store.countLines(config.agentId) >= config.maxLines) {
       throw new LineError('LINE_LIMIT', `Line limit reached: ${config.maxLines}`, { maxLines: config.maxLines })
@@ -303,6 +458,7 @@ export async function apply(ctx, rawConfig) {
       ? await resolveWorkspace(args.workspace)
       : await managerWorkspace(baseCwd)
     const role = args.role === undefined || args.role === null ? null : String(args.role).trim() || null
+    const title = args.title === undefined || args.title === null ? (role || label) : String(args.title).trim().slice(0, 120)
     const sessionId = `session-${randomUUID()}`
     const created = await ctx.sessionController.create({
       sessionId,
@@ -311,7 +467,7 @@ export async function apply(ctx, rawConfig) {
     })
     const creator = lineDefs.get(exec.agent.session.id)
     const actualSessionId = created.sessionId
-    const def = { agentId: config.agentId, label, sessionId: actualSessionId, lineId: lineId(config.agentId, label), role, createdBy: creator?.lineId ?? null }
+    const def = { agentId: config.agentId, label, sessionId: actualSessionId, lineId: lineId(config.agentId, label), role, title, createdBy: creator?.lineId ?? null, lifecycle: 'active', generation: 1 }
     try {
       store.acquire({
         agentId: config.agentId,
@@ -329,13 +485,11 @@ export async function apply(ctx, rawConfig) {
       ctx.logger?.warn?.('agent-lines: created Session %s but failed to register line %s', actualSessionId, label)
       throw error
     }
+    try { store.setTitle({ agentId: config.agentId, line: label, title }) } catch { /* title is best-effort after acquire */ }
     lineDefs.set(actualSessionId, def)
     startLoop(def)
     const agent = ctx.agents.get(actualSessionId)
     if (agent !== undefined) bindAgent(agent)
-    try {
-      await ctx.sessionController.rename({ sessionId: actualSessionId, title: `line: ${label}` })
-    } catch { /* a blank session may not materialize on rename; bootstrap/first delivery will */ }
     let bootstrapQueued = false
     if (args.bootstrap !== false && config.bootstrapOnCreate !== false && creator !== undefined) {
       try {
@@ -357,6 +511,8 @@ export async function apply(ctx, rawConfig) {
       line: label,
       sessionId: actualSessionId,
       role,
+      title,
+      lifecycle: 'active',
       cwd: targetWorkspace?.path ?? cwd,
       workspaceId: targetWorkspace?.id ?? null,
       created: true,
@@ -384,6 +540,11 @@ export async function apply(ctx, rawConfig) {
         ctx.logger?.info?.('agent-lines: manager %s is unbound; waiting for claim', def.label)
         continue
       }
+      const stored = store.getLineRow(config.agentId, def.label)
+      if (stored !== undefined && stored.lifecycle !== 'active') {
+        ctx.logger?.info?.('agent-lines: line %s is %s; skipping delivery loop', def.label, stored.lifecycle)
+        continue
+      }
       if (!(await sessionExists(def.sessionId))) {
         ctx.logger?.warn?.('agent-lines: Session %s for line %s is missing; line stays unbound until claimed', def.sessionId, def.label)
         lineDefs.set(def.sessionId, { ...def, missing: true })
@@ -397,8 +558,9 @@ export async function apply(ctx, rawConfig) {
         ttlMs: config.leaseTtlMs,
         role: def.role,
       })
-      lineDefs.set(def.sessionId, def)
-      startLoop(def)
+      const effective = { ...def, title: lineTitle(def, stored), lifecycle: 'active', generation: Number(stored?.generation ?? 1) }
+      lineDefs.set(def.sessionId, effective)
+      startLoop(effective)
     }
     cleanupFns.push(ctx.on('agent/created', ({ agent }) => { bindAgent(agent) }))
     cleanupFns.push(ctx.on('agent/disposed', ({ agent }) => { unbindAgent(agent) }))
@@ -406,6 +568,7 @@ export async function apply(ctx, rawConfig) {
       const managerLineId = lineId(config.agentId, config.createFrom)
       for (const row of store.listLines()) {
         if (row.created_by !== managerLineId || lineDefs.has(row.session_id)) continue
+        if (row.lifecycle !== 'active') continue
         if (!(await sessionExists(row.session_id))) {
           ctx.logger?.warn?.('agent-lines: dynamic line %s has no persisted Session; skipped restore', row.label)
           continue
@@ -420,7 +583,7 @@ export async function apply(ctx, rawConfig) {
             role: row.role,
             createdBy: row.created_by,
           })
-          const def = { agentId: config.agentId, label: row.label, sessionId: row.session_id, lineId: row.line_id, role: row.role, createdBy: row.created_by }
+          const def = { agentId: config.agentId, label: row.label, sessionId: row.session_id, lineId: row.line_id, role: row.role, title: lineTitle({ role: row.role, label: row.label }, row), createdBy: row.created_by, lifecycle: 'active', generation: Number(row.generation ?? 1) }
           lineDefs.set(row.session_id, def)
           startLoop(def)
         } catch (error) {
@@ -469,4 +632,4 @@ export async function apply(ctx, rawConfig) {
     store.close()
     throw error
   }
-}
+}

package/lib/store.js

@@ -33,10 +33,15 @@ CREATE TABLE IF NOT EXISTS lines (
   agent_id TEXT NOT NULL,
   label TEXT NOT NULL,
   role TEXT,
+  title TEXT,
   created_by TEXT,
   session_id TEXT NOT NULL,
   instance_id TEXT,
   status TEXT NOT NULL DEFAULT 'offline',
+  lifecycle TEXT NOT NULL DEFAULT 'active',
+  generation INTEGER NOT NULL DEFAULT 1,
+  rebind_at INTEGER,
+  rebind_from TEXT,
   last_seen INTEGER NOT NULL DEFAULT 0,
   created_at INTEGER NOT NULL,
   UNIQUE(agent_id, label)
@@ -97,7 +102,20 @@ CREATE TABLE IF NOT EXISTS manager_bindings (
   updated_at INTEGER NOT NULL
 );
 
-PRAGMA user_version = 6;
+CREATE TABLE IF NOT EXISTS line_events (
+  id TEXT PRIMARY KEY,
+  line_id TEXT NOT NULL,
+  action TEXT NOT NULL,
+  old_session_id TEXT,
+  new_session_id TEXT,
+  actor TEXT,
+  reason TEXT,
+  detail TEXT,
+  created_at INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS line_events_line ON line_events(line_id, created_at);
+
+PRAGMA user_version = 7;
 `
 
 export function defaultDbPath() {
@@ -140,12 +158,19 @@ export class LineStore {
     this.db.exec(SCHEMA)
     const columns = this.db.prepare('PRAGMA table_info(lines)').all().map(column => column.name)
     if (!columns.includes('role')) this.db.exec('ALTER TABLE lines ADD COLUMN role TEXT')
+    if (!columns.includes('title')) this.db.exec('ALTER TABLE lines ADD COLUMN title TEXT')
     if (!columns.includes('created_by')) this.db.exec('ALTER TABLE lines ADD COLUMN created_by TEXT')
+    if (!columns.includes('lifecycle')) this.db.exec("ALTER TABLE lines ADD COLUMN lifecycle TEXT NOT NULL DEFAULT 'active'")
+    if (!columns.includes('generation')) this.db.exec('ALTER TABLE lines ADD COLUMN generation INTEGER NOT NULL DEFAULT 1')
+    if (!columns.includes('rebind_at')) this.db.exec('ALTER TABLE lines ADD COLUMN rebind_at INTEGER')
+    if (!columns.includes('rebind_from')) this.db.exec('ALTER TABLE lines ADD COLUMN rebind_from TEXT')
     const messageColumns = this.db.prepare('PRAGMA table_info(messages)').all().map(column => column.name)
     if (!messageColumns.includes('root_message_id')) this.db.exec('ALTER TABLE messages ADD COLUMN root_message_id TEXT')
     if (!messageColumns.includes('hop')) this.db.exec('ALTER TABLE messages ADD COLUMN hop INTEGER NOT NULL DEFAULT 0')
     if (!messageColumns.includes('no_reply')) this.db.exec('ALTER TABLE messages ADD COLUMN no_reply INTEGER NOT NULL DEFAULT 0')
-    this.db.exec('PRAGMA user_version = 6')
+    this.db.exec('CREATE TABLE IF NOT EXISTS line_events (id TEXT PRIMARY KEY, line_id TEXT NOT NULL, action TEXT NOT NULL, old_session_id TEXT, new_session_id TEXT, actor TEXT, reason TEXT, detail TEXT, created_at INTEGER NOT NULL)')
+    this.db.exec('CREATE INDEX IF NOT EXISTS line_events_line ON line_events(line_id, created_at)')
+    this.db.exec('PRAGMA user_version = 7')
     this.prepared = new Map()
     this.closed = false
     this.fresh = fresh
@@ -244,6 +269,8 @@ export class LineStore {
     const from = this.#stmt('SELECT * FROM lines WHERE agent_id = ? AND label = ?').get(agentId, fromLine)
     if (from === undefined) throw new LineError('LINE_NOT_FOUND', `Sender line is not registered: ${agentId}#${fromLine}`)
     const target = this.resolveTarget(agentId, to)
+    if (target.row.lifecycle === 'retired') throw new LineError('LINE_RETIRED', `Line ${target.lineId} is retired`, { line: target.lineId })
+    if (target.row.lifecycle === 'rebinding') throw new LineError('LINE_REBINDING', `Line ${target.lineId} is rebinding`, { line: target.lineId })
     const body = assertMessageSize(text, maxMessageBytes)
     let parent
     if (replyTo !== undefined && replyTo !== null && String(replyTo).trim() !== '') {
@@ -383,13 +410,19 @@ export class LineStore {
   /** All lines with unread counts and live lease state. */
   listLines(now = Date.now()) {
     const rows = this.#stmt(`SELECT l.*, (SELECT COUNT(*) FROM messages m
-        WHERE m.to_agent = l.agent_id AND m.to_line = l.label AND m.state IN ('queued', 'claimed', 'delivered')) AS unread
+        WHERE m.to_agent = l.agent_id AND m.to_line = l.label AND m.state IN ('queued', 'claimed', 'delivered')) AS unread,
+        (SELECT COUNT(*) FROM messages m
+          WHERE m.to_agent = l.agent_id AND m.to_line = l.label AND m.state IN ('queued', 'claimed')) AS pending,
+        (SELECT MAX(m.created_at) FROM messages m
+          WHERE m.to_agent = l.agent_id AND m.to_line = l.label) AS last_activity_at
       FROM lines l ORDER BY l.agent_id, l.label`).all()
     return rows.map(row => {
       const lease = this.#stmt('SELECT * FROM leases WHERE line_id = ?').get(row.line_id)
       return {
         ...row,
         unread: Number(row.unread),
+        pending: Number(row.pending ?? 0),
+        lastActivityAt: row.last_activity_at === null ? null : Number(row.last_activity_at),
         lease: lease === undefined ? null : {
           instanceId: lease.instance_id,
           expiresAt: lease.expires_at,
@@ -406,13 +439,138 @@ export class LineStore {
     if (row === undefined) return undefined
     const lease = this.#stmt('SELECT * FROM leases WHERE line_id = ?').get(id)
     const unread = this.#stmt(`SELECT COUNT(*) AS n FROM messages WHERE to_agent = ? AND to_line = ? AND state IN ('queued', 'claimed', 'delivered')`).get(agentId, line)
+    const pending = this.#stmt(`SELECT COUNT(*) AS n FROM messages WHERE to_agent = ? AND to_line = ? AND state IN ('queued', 'claimed')`).get(agentId, line)
+    const activity = this.#stmt('SELECT MAX(created_at) AS n FROM messages WHERE to_agent = ? AND to_line = ?').get(agentId, line)
     return {
       ...row,
       unread: Number(unread.n),
+      pending: Number(pending.n),
+      lastActivityAt: activity.n === null ? null : Number(activity.n),
       lease: lease === undefined ? null : { instanceId: lease.instance_id, expiresAt: lease.expires_at, live: lease.expires_at > now },
     }
   }
 
+  /** Update the display title of a line. Persisted so restarts keep it. */
+  setTitle({ agentId, line, title, actor = null, now = Date.now() }) {
+    const id = lineId(agentId, line)
+    return this.#tx(() => {
+      const row = this.#stmt('SELECT * FROM lines WHERE line_id = ?').get(id)
+      if (row === undefined) throw new LineError('LINE_NOT_FOUND', `No such line: ${id}`, { line: id })
+      const value = title === null || title === undefined ? null : String(title).trim().slice(0, 120) || null
+      this.#stmt('UPDATE lines SET title = ? WHERE line_id = ?').run(value, id)
+      this.#event({ lineId: id, action: 'title', actor, detail: { title: value }, now })
+      return { ...this.#stmt('SELECT * FROM lines WHERE line_id = ?').get(id) }
+    })
+  }
+
+  /** Set lifecycle without a Session rebind (used to lock a rebind in progress). */
+  setLifecycle({ agentId, line, lifecycle, actor = null, reason = null, now = Date.now() }) {
+    const id = lineId(agentId, line)
+    if (!['active', 'retired', 'rebinding'].includes(String(lifecycle))) {
+      throw new LineError('LINE_INVALID_LIFECYCLE', `Invalid lifecycle: ${lifecycle}`)
+    }
+    return this.#tx(() => {
+      const row = this.#stmt('SELECT * FROM lines WHERE line_id = ?').get(id)
+      if (row === undefined) throw new LineError('LINE_NOT_FOUND', `No such line: ${id}`, { line: id })
+      this.#stmt("UPDATE lines SET lifecycle = ?, status = CASE WHEN ? = 'active' THEN status ELSE 'offline' END WHERE line_id = ?")
+        .run(String(lifecycle), String(lifecycle), id)
+      this.#event({ lineId: id, action: lifecycle, actor, reason, now })
+      return { ...this.#stmt('SELECT * FROM lines WHERE line_id = ?').get(id) }
+    })
+  }
+
+  /** Queue/claimed/delivered counts for one line. */
+  messageCounts({ agentId, line }) {
+    const rows = this.#stmt(`SELECT state, COUNT(*) AS n FROM messages
+      WHERE to_agent = ? AND to_line = ? GROUP BY state`).all(agentId, line)
+    const out = { queued: 0, claimed: 0, delivered: 0, acked: 0, failed: 0, expired: 0, dead: 0 }
+    for (const row of rows) out[row.state] = Number(row.n)
+    return out
+  }
+
+  /** Retire a line: no new sends, keep Session/queue/history. */
+  retire({ agentId, line, actor = null, reason = null, now = Date.now() }) {
+    const id = lineId(agentId, line)
+    return this.#tx(() => {
+      const row = this.#stmt('SELECT * FROM lines WHERE line_id = ?').get(id)
+      if (row === undefined) throw new LineError('LINE_NOT_FOUND', `No such line: ${id}`, { line: id })
+      if (row.lifecycle !== 'retired') {
+        this.#stmt("UPDATE lines SET lifecycle = 'retired', status = 'offline' WHERE line_id = ?").run(id)
+        this.#event({ lineId: id, action: 'retire', actor, reason, detail: this.messageCounts({ agentId, line }), now })
+      }
+      return { ...this.#stmt('SELECT * FROM lines WHERE line_id = ?').get(id), counts: this.messageCounts({ agentId, line }) }
+    })
+  }
+
+  /**
+   * Atomically switch a line to a new Session.
+   * migrate=queued: requeue claimed messages; queued/claimed will be delivered by the new loop.
+   * migrate=none: fail-closed if queued+claimed > 0 (manager must drain first).
+   * delivered/acked/failed/expired are never re-delivered.
+   */
+  rebind({ agentId, line, sessionId, actor = null, reason = null, migrate = 'queued', locked = false, now = Date.now() }) {
+    const id = lineId(agentId, line)
+    if (!['queued', 'none'].includes(String(migrate))) {
+      throw new LineError('LINE_INVALID_ARGUMENT', `migrate must be queued or none: ${migrate}`)
+    }
+    return this.#tx(() => {
+      const row = this.#stmt('SELECT * FROM lines WHERE line_id = ?').get(id)
+      if (row === undefined) throw new LineError('LINE_NOT_FOUND', `No such line: ${id}`, { line: id })
+      if (row.lifecycle === 'rebinding' && locked !== true) throw new LineError('LINE_REBIND_BUSY', `Line ${id} is already rebinding`, { line: id })
+      const counts = this.messageCounts({ agentId, line })
+      if (String(migrate) === 'none' && counts.queued + counts.claimed > 0) {
+        throw new LineError('LINE_BACKLOG_NOT_EMPTY', `Line ${id} has ${counts.queued + counts.claimed} queued/claimed messages; drain or use migrate=queued`, { line: id, counts })
+      }
+      if (String(migrate) === 'queued') {
+        this.#stmt(`UPDATE messages SET state = 'queued', claimed_by = NULL, claimed_at = NULL, next_attempt_at = ?
+          WHERE to_agent = ? AND to_line = ? AND state = 'claimed'`).run(now, agentId, line)
+      }
+      this.#stmt('DELETE FROM leases WHERE line_id = ?').run(id)
+      const generation = Number(row.generation ?? 1) + 1
+      this.#stmt(`UPDATE lines SET session_id = ?, lifecycle = 'active', generation = ?, rebind_at = ?, rebind_from = ?,
+        instance_id = NULL, status = 'offline', last_seen = ? WHERE line_id = ?`)
+        .run(String(sessionId), generation, now, row.session_id, now, id)
+      const detail = { migrate: String(migrate), before: counts, after: this.messageCounts({ agentId, line }), generation }
+      this.#event({ lineId: id, action: 'rebind', oldSessionId: row.session_id, newSessionId: String(sessionId), actor, reason, detail, now })
+      return { ...this.#stmt('SELECT * FROM lines WHERE line_id = ?').get(id), oldSessionId: row.session_id, counts: detail.after }
+    })
+  }
+
+  /** Last rebind event for a line (used to show oldSessionId without overwriting the row). */
+  lastLineEvent({ agentId, line, action = 'rebind' }) {
+    const id = lineId(agentId, line)
+    return this.#stmt('SELECT * FROM line_events WHERE line_id = ? AND action = ? ORDER BY created_at DESC LIMIT 1').get(id, action)
+  }
+
+  /** Structured handoff snapshot: counts + recent messages + lifecycle events. */
+  handoff({ agentId, line, limit = 20, now = Date.now() }) {
+    const row = this.getLine(agentId, line, now)
+    if (row === undefined) throw new LineError('LINE_NOT_FOUND', `No such line: ${lineId(agentId, line)}`)
+    const recent = this.#stmt(`SELECT * FROM messages WHERE to_agent = ? AND to_line = ? ORDER BY created_at DESC LIMIT ?`).all(agentId, line, limit).reverse()
+    const events = this.lineEvents({ agentId, line, limit: 10 })
+    const lastEvent = events.length ? events[0] : null
+    return {
+      line: line, label: line, role: row.role, title: row.title ?? row.role ?? row.label,
+      sessionId: row.session_id, lifecycle: row.lifecycle ?? 'active', generation: row.generation ?? 1,
+      createdBy: row.created_by, createdAt: row.created_at, counts: this.messageCounts({ agentId, line }),
+      lastActivityAt: row.lastActivityAt, oldSessionId: lastEvent && lastEvent.action === 'rebind' ? lastEvent.old_session_id : null,
+      lastEvent, events, messages: recent,
+    }
+  }
+
+  /** Recent lifecycle events for diagnostics. */
+  lineEvents({ agentId, line, limit = 20 }) {
+    const id = lineId(agentId, line)
+    return this.#stmt('SELECT * FROM line_events WHERE line_id = ? ORDER BY created_at DESC LIMIT ?').all(id, limit)
+  }
+
+  #event({ lineId: target, action, oldSessionId = null, newSessionId = null, actor = null, reason = null, detail = null, now = Date.now() }) {
+    const id = 'lineev_' + randomUUID().replaceAll('-', '')
+    this.#stmt(`INSERT INTO line_events(id, line_id, action, old_session_id, new_session_id, actor, reason, detail, created_at)
+      VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(id, target, action, oldSessionId, newSessionId, actor, reason, detail === null ? null : JSON.stringify(detail), now)
+    return id
+  }
+
   counts(now = Date.now()) {
     const states = this.#stmt('SELECT state, COUNT(*) AS n FROM messages GROUP BY state ORDER BY state').all()
     const leases = this.#stmt('SELECT COUNT(*) AS n FROM leases WHERE expires_at > ?').get(now)
@@ -421,4 +579,4 @@ export class LineStore {
   }
 }
 
-export { expandHome }
+export { expandHome }

package/lib/tools.js

@@ -51,6 +51,7 @@ function materializationOf(ctx, sessionId) {
 function currentView(def) {
   return def === undefined ? null : {
     agentId: def.agentId, line: def.label, sessionId: def.sessionId, lineId: def.lineId, role: def.role,
+    title: def.title ?? def.role ?? def.label, lifecycle: def.lifecycle ?? 'active', generation: def.generation ?? 1,
   }
 }
 
@@ -94,6 +95,12 @@ export function registerStatusTool(ctx, { config, store, lineDefs }) {
       const lines = store.listLines().map(line => ({
         label: line.label,
         role: line.role,
+        title: line.title ?? line.role ?? line.label,
+        lifecycle: line.lifecycle ?? 'active',
+        generation: line.generation ?? 1,
+        oldSessionId: store.lastLineEvent({ agentId: line.agent_id, line: line.label, action: 'rebind' })?.old_session_id ?? null,
+        pending: line.pending ?? 0,
+        lastActivityAt: line.lastActivityAt ?? null,
         sessionId: line.session_id,
         createdBy: line.created_by,
         lease: line.lease,
@@ -107,6 +114,8 @@ export function registerStatusTool(ctx, { config, store, lineDefs }) {
             bound: currentDef !== undefined,
             line: currentDef?.label ?? null,
             role: currentDef?.role ?? null,
+            title: currentDef?.title ?? currentDef?.role ?? null,
+            lifecycle: currentDef?.lifecycle ?? null,
           }
       const repair = current === null
         ? 'No calling Session; line_status is informational.'
@@ -157,7 +166,7 @@ export function registerClaimTool(ctx, { config, lineDefs, rebindManager }) {
 }
 
 /** Register the model tools; returns their disposers. */
-export function registerToolsForAgent(agent, def, { config, store, lineDefs, createLine, moveLineWorkspace }) {
+export function registerToolsForAgent(agent, def, { config, store, lineDefs, createLine, moveLineWorkspace, retireLine, rebindLine, renameLine }) {
   const disposers = []
 
   disposers.push(agent.ctx.tools.register({
@@ -195,6 +204,7 @@ export function registerToolsForAgent(agent, def, { config, store, lineDefs, cre
     output: OUTPUT,
     execute: async (args, exec) => {
       const def = currentLine(exec, lineDefs)
+      if (def.lifecycle === 'retired') throw new LineError('LINE_RETIRED', `Line ${def.label} is retired; it cannot send new messages`, { line: def.label })
       const text = assertMessageSize(args.text, config.maxMessageBytes)
       const target = parseTarget(args.to, def.agentId)
       if (target.lineId === def.lineId && config.allowSelfSend !== true) {
@@ -291,6 +301,11 @@ export function registerToolsForAgent(agent, def, { config, store, lineDefs, cre
         properties: {
           label: { type: 'string', description: 'Stable line label, e.g. "frontend-line"' },
           role: { type: 'string', description: 'Short role or responsibility description for the new line' },
+          title: { type: 'string', description: 'Sidebar title; defaults to role or label' },
+          replace: { type: 'boolean', description: 'Replace an existing line with a fresh Session; old Session is retired (manager only)' },
+          force: { type: 'boolean', description: 'Allow replacing an active line; use with reason' },
+          migrate: { type: 'string', enum: ['queued', 'none'], description: 'Backlog policy on replace; none fails if queued/claimed exists' },
+          reason: { type: 'string', description: 'Reason for replace; shown in line_events' },
           agentPreset: { type: 'string', description: 'DSH agent preset; defaults to the plugin childPreset' },
           workspace: { type: 'string', description: 'Target workspace path or id; defaults to the manager workspace. Existing workspace only.' },
           cwd: { type: 'string', description: 'Working directory when no workspace is named; defaults to the manager Session cwd' },
@@ -310,6 +325,117 @@ export function registerToolsForAgent(agent, def, { config, store, lineDefs, cre
       },
     }))
 
+    disposers.push(agent.ctx.tools.register({
+      name: 'line_retire',
+      description: 'Retire an existing line: new line_send is rejected, the Session and message history are kept, and the delivery loop stops. Only the configured manager line may call this. Use line_create replace:true to hand the same role to a fresh Session.',
+      parameters: {
+        type: 'object', additionalProperties: false,
+        properties: {
+          line: { type: 'string', description: 'Existing line label' },
+          reason: { type: 'string', description: 'Why this line is being retired' },
+        },
+        required: ['line'],
+      },
+      output: OUTPUT,
+      execute: async (args, exec) => {
+        const caller = currentLine(exec, lineDefs)
+        if (caller.label !== config.createFrom) throw new LineError('LINE_CREATE_FORBIDDEN', `Only ${config.createFrom} may retire lines`, { caller: caller.label })
+        return retireLine({ label: String(args.line), actor: caller.label, reason: args.reason ?? null })
+      },
+    }))
+
+    disposers.push(agent.ctx.tools.register({
+      name: 'line_rebind',
+      description: 'Atomically switch an existing line to a new live Session, migrating queued/claimed messages. The old Session is kept, never deleted. Only the configured manager line may call this; use line_create replace:true to create a fresh Session in one step.',
+      parameters: {
+        type: 'object', additionalProperties: false,
+        properties: {
+          line: { type: 'string', description: 'Existing line label' },
+          sessionId: { type: 'string', description: 'Live root Session id to bind' },
+          migrate: { type: 'string', enum: ['queued', 'none'], description: 'queued migrates queued/claimed; none fails if backlog is non-empty' },
+          reason: { type: 'string', description: 'Why this line is being rebound' },
+          force: { type: 'boolean', description: 'Accepted for API compatibility; active replacement is gated by line_create replace' },
+        },
+        required: ['line', 'sessionId'],
+      },
+      output: OUTPUT,
+      execute: async (args, exec) => {
+        const caller = currentLine(exec, lineDefs)
+        if (caller.label !== config.createFrom) throw new LineError('LINE_CREATE_FORBIDDEN', `Only ${config.createFrom} may rebind lines`, { caller: caller.label })
+        return rebindLine({ label: String(args.line), sessionId: String(args.sessionId), actor: caller.label, reason: args.reason ?? null, migrate: args.migrate === 'none' ? 'none' : 'queued', force: args.force === true })
+      },
+    }))
+
+    disposers.push(agent.ctx.tools.register({
+      name: 'line_rename',
+      description: 'Rename a line display title in the sidebar. The title is persisted in lines.db and survives restarts. Only the configured manager line may call this.',
+      parameters: {
+        type: 'object', additionalProperties: false,
+        properties: {
+          line: { type: 'string', description: 'Existing line label' },
+          title: { type: 'string', description: 'New title, 1-120 chars' },
+        },
+        required: ['line', 'title'],
+      },
+      output: OUTPUT,
+      execute: async (args, exec) => {
+        const caller = currentLine(exec, lineDefs)
+        if (caller.label !== config.createFrom) throw new LineError('LINE_CREATE_FORBIDDEN', `Only ${config.createFrom} may rename lines`, { caller: caller.label })
+        if (String(args.title ?? '').trim() === '') throw new LineError('LINE_INVALID_ARGUMENT', 'title must not be empty')
+        return renameLine({ label: String(args.line), title: String(args.title), actor: caller.label })
+      },
+    }))
+
+    disposers.push(agent.ctx.tools.register({
+      name: 'line_handoff',
+      description: 'Generate a structured handoff snapshot for a line: current metadata, backlog counts, recent messages, lifecycle events. Does not call a model; write the returned markdown to a file before retire/replace/rebind.',
+      parameters: {
+        type: 'object', additionalProperties: false,
+        properties: {
+          line: { type: 'string', description: 'Existing line label' },
+          format: { type: 'string', enum: ['md', 'json'], description: 'md (default) returns markdown; json returns the snapshot object' },
+          limit: { type: 'number', description: 'Recent messages to include, 1-100 (default 20)' },
+        },
+        required: ['line'],
+      },
+      output: OUTPUT,
+      execute: async (args, exec) => {
+        const caller = currentLine(exec, lineDefs)
+        if (caller.label !== config.createFrom) throw new LineError('LINE_CREATE_FORBIDDEN', `Only ${config.createFrom} may create handoffs`, { caller: caller.label })
+        const limit = limitValue(args.limit, 20, 100)
+        const data = store.handoff({ agentId: config.agentId, line: String(args.line), limit })
+        if (args.format === 'json') return data
+        const lines = [
+          '# 交接单 · ' + data.label,
+          '',
+          '## 1 我是谁',
+          '- 角色: ' + (data.role ?? data.label),
+          '- 当前 label: ' + data.label,
+          '- Session: ' + data.sessionId,
+          '- lifecycle: ' + data.lifecycle + ' (generation ' + data.generation + ')',
+          '',
+          '## 2 积压',
+          '- queued: ' + data.counts.queued,
+          '- claimed: ' + data.counts.claimed,
+          '- delivered: ' + data.counts.delivered,
+          '- acked: ' + data.counts.acked,
+          '- failed/expired: ' + (data.counts.failed + data.counts.expired),
+          '',
+          '## 3 最近消息',
+          ...(data.messages.length === 0 ? ['- 无'] : data.messages.map(m => `- ${new Date(m.created_at).toISOString()} [${m.state}] ${m.from_line} -> ${m.to_line}: ${String(m.body).replace(/\s+/g, ' ').slice(0, 180)}`)),
+          '',
+          '## 4 生命周期',
+          ...(data.events.length === 0 ? ['- 无'] : data.events.map(e => `- ${new Date(e.created_at).toISOString()} ${e.action} ${e.old_session_id ? e.old_session_id + ' -> ' : ''}${e.new_session_id ?? ''}`)),
+          '',
+          '## 5 交接提示',
+          '- 先读本文件，再继续工作。',
+          '- 不要复用旧 Session；它只保留历史。',
+          '- 如有 queued/claimed，新线会继续收到。',
+        ]
+        return { line: data.label, format: 'md', markdown: lines.join('\n'), counts: data.counts, sessionId: data.sessionId, generation: data.generation }
+      },
+    }))
+
     disposers.push(agent.ctx.tools.register({
       name: 'line_move_workspace',
       description: 'Move an existing line Session into a target workspace record so it appears under that workspace in the sidebar. DSH only allows attachment when the Session cwd exactly matches the workspace path; it cannot move a Session to a different directory (use a new line for that).',
@@ -334,4 +460,4 @@ export function registerToolsForAgent(agent, def, { config, store, lineDefs, cre
   }
 
   return disposers
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-agent-lines",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "description": "DSH Agent 的持久、可寻址消息线（社区插件）。",
   "type": "module",
   "license": "Apache-2.0",