session-trail 0.2.0__tar.gz → 0.2.2__tar.gz

{session_trail-0.2.0/src/session_trail.egg-info → session_trail-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: session-trail
-Version: 0.2.0
+Version: 0.2.2
 Summary: Local cross-agent work timeline: discover, browse and resume coding-agent sessions on your machine
 Author: fwt11
 License-Expression: MIT
@@ -101,9 +101,11 @@ agent-trail serve --interval 30      # 轮询间隔（watch 健康时自动降
 ```bash
 agent-trail tray             # 启动托盘（自动拉起 agent-trail serve）
 agent-trail tray --show      # 启动同时打开控制台窗口
-agent-trail tray --install   # 写入应用菜单入口；--uninstall 反向清理
+agent-trail tray --install   # 手动写入应用菜单入口；--uninstall 反向清理
 ```
 
+pip 安装后首次运行 `agent-trail tray` 会自动把"Agent 足迹"注册进系统应用菜单（应用启动器可直接搜索到），之后升级换路径也会自动刷新；无桌面会话（SSH/服务器）不写入。
+
 托盘壳本身不依赖任何第三方 pip 包，但需要 GTK 的 GI 绑定（系统 Python 通常自带）。`agent-trail tray` 在当前解释器缺 GI 绑定时会自动改用带绑定的系统 Python 重执行（例如 pip 装在 venv 里、托盘跑在系统 Python），无需任何手动操作；实在找不到时按提示安装：
 
 ```bash
@@ -111,7 +113,7 @@ agent-trail tray --install   # 写入应用菜单入口；--uninstall 反向清
 sudo apt install python3-gi gir1.2-webkit2-4.1
 ```
 
-托盘以子进程方式管理 `agent-trail serve`（可用环境变量 `AGENT_TRAIL_BIN` 覆盖可执行文件路径），服务异常退出自动重启（退避重试，连续失败后停在可手动启动的状态）。窗口直接关闭只是隐藏，退出走托盘菜单；flock 单实例锁防止重复启动。
+`agent-trail tray` 默认脱离终端后台运行：命令立即返回，日志追加在 `~/.agent-trail/tray.log`，关闭终端不影响托盘；`--foreground` 可前台运行调试。托盘以子进程方式管理 `agent-trail serve`——**启动托盘即自动拉起服务**（菜单里可停止/启动，异常退出自动重启）。窗口直接关闭只是隐藏，退出走托盘菜单，或 `kill $(cat ~/.agent-trail/tray.lock)`；flock 单实例锁防止重复启动（重复执行会提示"已在运行"）。
 
 托盘图标走原生 StatusNotifierItem/DBusMenu 协议（`agent_trail/tray/sni.py`，Gio 实现——libayatana 在 Deepin 23 的托盘守护上不工作，详见源码注释）。内嵌 WebView 默认使用软件合成（`WEBKIT_DISABLE_DMABUF_RENDERER` / `WEBKIT_DISABLE_COMPOSITING_MODE`，可用同名环境变量覆盖），避免在无 DRM 权限的会话里出现空白窗口。`serve` 的所有命令行形态保持不变，无托盘环境（SSH/无桌面）不受影响。
 

{session_trail-0.2.0 → session_trail-0.2.2}/README.en.md

@@ -74,9 +74,11 @@ Beyond `serve`, a tray application embeds the console in a native window and add
 ```bash
 agent-trail tray             # start the tray (spawns agent-trail serve)
 agent-trail tray --show      # also open the console window
-agent-trail tray --install   # add an applications-menu entry; --uninstall reverts
+agent-trail tray --install   # manually add an applications-menu entry; --uninstall reverts
 ```
 
+The first `agent-trail tray` run after pip install automatically registers "Agent Trail" in the desktop applications menu (searchable from your launcher) and refreshes it on upgrades; headless sessions (SSH/servers) write nothing.
+
 The tray needs GTK GI bindings (preinstalled on most distros as the system Python). If the interpreter running agent-trail lacks them — e.g. the package lives in a venv — `agent-trail tray` automatically re-executes itself with a system Python that has GI; no manual steps. If none is found, install:
 
 ```bash
@@ -84,7 +86,7 @@ The tray needs GTK GI bindings (preinstalled on most distros as the system Pytho
 sudo apt install python3-gi gir1.2-webkit2-4.1
 ```
 
-The tray manages `agent-trail serve` as a subprocess (override with `AGENT_TRAIL_BIN`) and restarts it automatically with backoff if it dies. Closing the window only hides it; quit lives in the tray menu. A flock single-instance lock prevents duplicates.
+`agent-trail tray` detaches from the terminal by default: the command returns immediately, logs append to `~/.agent-trail/tray.log`, and closing the terminal does not affect the tray; use `--foreground` to debug in the foreground. The tray manages `agent-trail serve` as a subprocess — **starting the tray starts the service** (stop/start from the menu; automatic restart with backoff if it dies). Closing the window only hides it; quit lives in the tray menu, or `kill $(cat ~/.agent-trail/tray.lock)`. A flock single-instance lock prevents duplicates (a second invocation prints "already running").
 
 The tray icon speaks the native StatusNotifierItem/DBusMenu protocol (`agent_trail/tray/sni.py`, implemented with Gio — libayatana does not work against Deepin 23's tray daemon; see source comments). The embedded WebView defaults to software compositing (`WEBKIT_DISABLE_DMABUF_RENDERER` / `WEBKIT_DISABLE_COMPOSITING_MODE`, overridable via env), avoiding blank windows on sessions without DRM access. All `serve`/CLI forms keep working without a desktop.
 

{session_trail-0.2.0 → session_trail-0.2.2}/README.md

@@ -75,9 +75,11 @@ agent-trail serve --interval 30      # 轮询间隔（watch 健康时自动降
 ```bash
 agent-trail tray             # 启动托盘（自动拉起 agent-trail serve）
 agent-trail tray --show      # 启动同时打开控制台窗口
-agent-trail tray --install   # 写入应用菜单入口；--uninstall 反向清理
+agent-trail tray --install   # 手动写入应用菜单入口；--uninstall 反向清理
 ```
 
+pip 安装后首次运行 `agent-trail tray` 会自动把"Agent 足迹"注册进系统应用菜单（应用启动器可直接搜索到），之后升级换路径也会自动刷新；无桌面会话（SSH/服务器）不写入。
+
 托盘壳本身不依赖任何第三方 pip 包，但需要 GTK 的 GI 绑定（系统 Python 通常自带）。`agent-trail tray` 在当前解释器缺 GI 绑定时会自动改用带绑定的系统 Python 重执行（例如 pip 装在 venv 里、托盘跑在系统 Python），无需任何手动操作；实在找不到时按提示安装：
 
 ```bash
@@ -85,7 +87,7 @@ agent-trail tray --install   # 写入应用菜单入口；--uninstall 反向清
 sudo apt install python3-gi gir1.2-webkit2-4.1
 ```
 
-托盘以子进程方式管理 `agent-trail serve`（可用环境变量 `AGENT_TRAIL_BIN` 覆盖可执行文件路径），服务异常退出自动重启（退避重试，连续失败后停在可手动启动的状态）。窗口直接关闭只是隐藏，退出走托盘菜单；flock 单实例锁防止重复启动。
+`agent-trail tray` 默认脱离终端后台运行：命令立即返回，日志追加在 `~/.agent-trail/tray.log`，关闭终端不影响托盘；`--foreground` 可前台运行调试。托盘以子进程方式管理 `agent-trail serve`——**启动托盘即自动拉起服务**（菜单里可停止/启动，异常退出自动重启）。窗口直接关闭只是隐藏，退出走托盘菜单，或 `kill $(cat ~/.agent-trail/tray.lock)`；flock 单实例锁防止重复启动（重复执行会提示"已在运行"）。
 
 托盘图标走原生 StatusNotifierItem/DBusMenu 协议（`agent_trail/tray/sni.py`，Gio 实现——libayatana 在 Deepin 23 的托盘守护上不工作，详见源码注释）。内嵌 WebView 默认使用软件合成（`WEBKIT_DISABLE_DMABUF_RENDERER` / `WEBKIT_DISABLE_COMPOSITING_MODE`，可用同名环境变量覆盖），避免在无 DRM 权限的会话里出现空白窗口。`serve` 的所有命令行形态保持不变，无托盘环境（SSH/无桌面）不受影响。
 

{session_trail-0.2.0 → session_trail-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "session-trail"
-version = "0.2.0"
+version = "0.2.2"
 description = "Local cross-agent work timeline: discover, browse and resume coding-agent sessions on your machine"
 readme = "README.md"
 license = "MIT"

{session_trail-0.2.0 → session_trail-0.2.2}/src/agent_trail/cli.py

@@ -31,6 +31,7 @@ def build_parser() -> argparse.ArgumentParser:
     serve.add_argument("--no-watch", action="store_true")
     tray = commands.add_parser("tray", help="system tray app (Linux)")
     tray.add_argument("--show", action="store_true", help="open the console window at startup")
+    tray.add_argument("--foreground", action="store_true", help="run in the foreground (default: detach with logs in ~/.agent-trail/tray.log)")
     tray.add_argument("--install", action="store_true", help="add an applications-menu entry")
     tray.add_argument("--uninstall", action="store_true", help="remove the menu entry and autostart")
     return parser

{session_trail-0.2.0 → session_trail-0.2.2}/src/agent_trail/tray/app.py

@@ -96,6 +96,7 @@ def tr(key: str, **params) -> str:
 
 
 LOCK_PATH = Path.home() / ".agent-trail" / "tray.lock"
+LOG_PATH = Path.home() / ".agent-trail" / "tray.log"
 AUTOSTART_PATH = Path.home() / ".config" / "autostart" / "agent-trail-tray.desktop"
 APP_MENU_PATH = Path.home() / ".local" / "share" / "applications" / "agent-trail-tray.desktop"
 
@@ -111,6 +112,11 @@ def emit(event: dict) -> None:
     print(json.dumps(event, ensure_ascii=False), flush=True)
 
 
+def _looks_executable(path: str) -> bool:
+    candidate = Path(path)
+    return candidate.is_file() and os.access(candidate, os.X_OK)
+
+
 class TrailCore:
     """平台无关的服务子进程管理器；不含任何 GUI 依赖。
 
@@ -128,9 +134,15 @@ class TrailCore:
         restart_delay: float = 3.0,
         stability_seconds: float = 300.0,
     ) -> None:
+        # serve 的拉起命令不依赖 PATH：executable 未显式给出（或给出的路径
+        # 无效）时，退到 [sys.executable, -m, agent_trail]——托盘进程自己能
+        # 跑，serve 就能跑（重执行场景的 PYTHONPATH 会被子进程继承）。
         self.executable = executable
-        if self.executable is None:
-            self.executable = os.environ.get("AGENT_TRAIL_BIN") or shutil.which("agent-trail")
+        if self.executable is not None and not _looks_executable(self.executable):
+            self.executable = None
+        self._env_bin = os.environ.get("AGENT_TRAIL_BIN")
+        if self._env_bin is not None and not _looks_executable(self._env_bin):
+            self._env_bin = None
         self.on_event = on_event or (lambda event: None)
         self.max_restarts = max_restarts
         self.restart_delay = restart_delay
@@ -149,7 +161,13 @@ class TrailCore:
 
     @property
     def available(self) -> bool:
-        return bool(self.executable)
+        return True  # 至少有 [sys.executable, -m agent_trail] 兜底
+
+    def _serve_command(self) -> list[str]:
+        for candidate in (self.executable, self._env_bin):
+            if candidate and _looks_executable(candidate):
+                return [candidate, "serve", "--no-browser"]
+        return [sys.executable, "-m", "agent_trail", "serve", "--no-browser"]
 
     def start(self, *, reset_attempts: bool = True) -> bool:
         with self._lock:
@@ -166,7 +184,7 @@ class TrailCore:
             self.url = self.port = self.key = None
             self._spawned_at = time.monotonic()
             self.process = subprocess.Popen(
-                [self.executable, "serve", "--no-browser"],
+                self._serve_command(),
                 stdout=subprocess.PIPE,
                 stderr=subprocess.STDOUT,
                 text=True,
@@ -287,6 +305,38 @@ class TrailCore:
 # -- 桌面入口文件 -----------------------------------------------------------
 
 
+def _desktop_session_present() -> bool:
+    return bool(
+        os.environ.get("DISPLAY")
+        or os.environ.get("WAYLAND_DISPLAY")
+        or os.environ.get("XDG_CURRENT_DESKTOP")
+    )
+
+
+def ensure_desktop_entry() -> None:
+    """首次运行 tray 时自动注册应用菜单入口，并在路径变化后自愈刷新。
+
+    pip 的 wheel 安装没有装后钩子，因此采用运行时自注册：仅在有桌面
+    会话的环境执行，内容与当前渲染一致时跳过写入。开机自启已开启时
+    同步刷新其 Exec 路径，避免包位置变化后自启失效。
+    """
+    if not _desktop_session_present():
+        return
+    executable = shutil.which("agent-trail") or sys.argv[0]
+    if not _looks_executable(executable):
+        return
+    entry = render_desktop_entry(executable, ICON_PATH)
+    try:
+        if not APP_MENU_PATH.exists() or APP_MENU_PATH.read_text(encoding="utf-8") != entry:
+            APP_MENU_PATH.parent.mkdir(parents=True, exist_ok=True)
+            APP_MENU_PATH.write_text(entry, encoding="utf-8")
+        if autostart_enabled():
+            if AUTOSTART_PATH.read_text(encoding="utf-8") != entry:
+                AUTOSTART_PATH.write_text(entry, encoding="utf-8")
+    except OSError:
+        pass  # 桌面注册失败不影响托盘本身；--install/--uninstall 仍可手动操作
+
+
 def render_desktop_entry(executable: str, icon: Path,
                          template: Path = DESKTOP_TEMPLATE) -> str:
     text = template.read_text(encoding="utf-8")
@@ -327,6 +377,13 @@ class SingleInstance:
         os.write(self._fd, f"{os.getpid()}\n".encode())
         return True
 
+    def rewrite_pid(self) -> None:
+        """守护化后由最终进程调用：锁文件里写自己的 pid。"""
+        if self._fd is not None:
+            os.ftruncate(self._fd, 0)
+            os.lseek(self._fd, 0, os.SEEK_SET)  # ftruncate 不回卷写偏移，必须显式归零
+            os.write(self._fd, f"{os.getpid()}\n".encode())
+
     def release(self) -> None:
         if self._fd is not None:
             try:
@@ -497,6 +554,28 @@ def run_gtk(icon_path: Path, show: bool = False) -> int:
 # -- 入口 --------------------------------------------------------------------
 
 
+def _daemonize(log_path: Path) -> bool:
+    """双 fork 脱离终端；返回 False 表示当前在父进程（调用方应立即退出）。
+
+    守护进程的 stdout/stderr 追加到日志文件，stdin 接到 /dev/null。
+    单实例锁的 fd 随 fork 继承，由守护进程继续持有。
+    """
+    if os.fork() > 0:
+        return False
+    os.setsid()
+    if os.fork() > 0:
+        os._exit(0)
+    log_fd = os.open(log_path, os.O_WRONLY | os.O_CREAT | os.O_APPEND, 0o600)
+    null_fd = os.open(os.devnull, os.O_RDONLY)
+    os.dup2(null_fd, 0)
+    os.dup2(log_fd, 1)
+    os.dup2(log_fd, 2)
+    for fd in (log_fd, null_fd):
+        if fd > 2:
+            os.close(fd)
+    return True
+
+
 def _reexec_with_system_python(argv: list[str], guard: "SingleInstance | None" = None) -> int | None:
     """当前解释器缺 GI 绑定时，改用带 gi 的系统 Python 重执行自己。
 
@@ -540,6 +619,7 @@ def main(argv: list[str] | None = None) -> int:
     parser.add_argument("--install", action="store_true", help="写入应用菜单入口")
     parser.add_argument("--uninstall", action="store_true", help="移除应用菜单入口与开机自启")
     parser.add_argument("--show", action="store_true", help="启动时同时打开控制台窗口")
+    parser.add_argument("--foreground", action="store_true", help="前台运行（默认脱离终端后台运行，日志见 ~/.agent-trail/tray.log）")
     args = parser.parse_args(argv)
 
     if args.uninstall:
@@ -558,10 +638,15 @@ def main(argv: list[str] | None = None) -> int:
     if not ICON_PATH.is_file():
         print(tr("error.no_icon", path=ICON_PATH), file=sys.stderr)
         return 1
+    ensure_desktop_entry()
+    # 锁在前台获取：重复启动时提示直接出现在用户终端；fd 由守护进程继承
     guard = SingleInstance()
     if not guard.acquire():
         print(tr("error.already_running"), flush=True)
         return 0
+    if not args.foreground and not _daemonize(LOG_PATH):
+        return 0  # 父进程：立即把终端还给用户；托盘在后台继续
+    guard.rewrite_pid()  # 锁文件写守护进程的 pid，kill $(cat 锁文件) 才有效
     try:
         return run_gtk(ICON_PATH, show=args.show)
     except (ImportError, ValueError) as error:

{session_trail-0.2.0 → session_trail-0.2.2/src/session_trail.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: session-trail
-Version: 0.2.0
+Version: 0.2.2
 Summary: Local cross-agent work timeline: discover, browse and resume coding-agent sessions on your machine
 Author: fwt11
 License-Expression: MIT
@@ -101,9 +101,11 @@ agent-trail serve --interval 30      # 轮询间隔（watch 健康时自动降
 ```bash
 agent-trail tray             # 启动托盘（自动拉起 agent-trail serve）
 agent-trail tray --show      # 启动同时打开控制台窗口
-agent-trail tray --install   # 写入应用菜单入口；--uninstall 反向清理
+agent-trail tray --install   # 手动写入应用菜单入口；--uninstall 反向清理
 ```
 
+pip 安装后首次运行 `agent-trail tray` 会自动把"Agent 足迹"注册进系统应用菜单（应用启动器可直接搜索到），之后升级换路径也会自动刷新；无桌面会话（SSH/服务器）不写入。
+
 托盘壳本身不依赖任何第三方 pip 包，但需要 GTK 的 GI 绑定（系统 Python 通常自带）。`agent-trail tray` 在当前解释器缺 GI 绑定时会自动改用带绑定的系统 Python 重执行（例如 pip 装在 venv 里、托盘跑在系统 Python），无需任何手动操作；实在找不到时按提示安装：
 
 ```bash
@@ -111,7 +113,7 @@ agent-trail tray --install   # 写入应用菜单入口；--uninstall 反向清
 sudo apt install python3-gi gir1.2-webkit2-4.1
 ```
 
-托盘以子进程方式管理 `agent-trail serve`（可用环境变量 `AGENT_TRAIL_BIN` 覆盖可执行文件路径），服务异常退出自动重启（退避重试，连续失败后停在可手动启动的状态）。窗口直接关闭只是隐藏，退出走托盘菜单；flock 单实例锁防止重复启动。
+`agent-trail tray` 默认脱离终端后台运行：命令立即返回，日志追加在 `~/.agent-trail/tray.log`，关闭终端不影响托盘；`--foreground` 可前台运行调试。托盘以子进程方式管理 `agent-trail serve`——**启动托盘即自动拉起服务**（菜单里可停止/启动，异常退出自动重启）。窗口直接关闭只是隐藏，退出走托盘菜单，或 `kill $(cat ~/.agent-trail/tray.lock)`；flock 单实例锁防止重复启动（重复执行会提示"已在运行"）。
 
 托盘图标走原生 StatusNotifierItem/DBusMenu 协议（`agent_trail/tray/sni.py`，Gio 实现——libayatana 在 Deepin 23 的托盘守护上不工作，详见源码注释）。内嵌 WebView 默认使用软件合成（`WEBKIT_DISABLE_DMABUF_RENDERER` / `WEBKIT_DISABLE_COMPOSITING_MODE`，可用同名环境变量覆盖），避免在无 DRM 权限的会话里出现空白窗口。`serve` 的所有命令行形态保持不变，无托盘环境（SSH/无桌面）不受影响。