@foxden-app/foxclaw 0.5.8 → 0.5.9

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable FoxClaw changes are listed here. Each release note is bilingual so GitHub Releases and the npm package are useful to both Chinese and English readers.
 
+## 0.5.9 - 2026-06-07
+
+### 中文
+- Linux 用户级 systemd 安装现在会在 `foxclaw start` / `restart` / `install-systemd` 时自动尝试启用 systemd user linger，避免用户退出 SSH 或桌面会话后 FoxClaw 停止接收 Telegram 消息。
+- `foxclaw doctor` 新增 linger 状态检查；如果自动启用失败，会提示使用 `sudo loginctl enable-linger <user>` 手动修复。
+- 中文/英文安装指南和故障排查文档更新为默认自动处理 linger，失败时再手动介入。
+
+### English
+- Linux user-systemd installation now tries to enable systemd user linger during `foxclaw start`, `restart`, and `install-systemd`, preventing FoxClaw from stopping after SSH or desktop logout.
+- `foxclaw doctor` now checks linger state and tells users to run `sudo loginctl enable-linger <user>` if automatic setup fails.
+- Updated the Chinese and English install and troubleshooting docs to describe automatic linger setup with manual recovery only when needed.
+
 ## 0.5.8 - 2026-06-05
 
 ### 中文

package/dist/main.js

@@ -1132,6 +1132,7 @@ function runDoctorChecks() {
     warnIfProxyEnvMissingFromLoadedEnv();
     warnIfProxyConfigNeedsAttention();
     warnIfInstalledServiceNodeLooksWrong();
+    warnIfSystemdUserLingerDisabled();
     return passed;
 }
 function warnIfProxyConfigNeedsAttention() {
@@ -1204,6 +1205,21 @@ function warnIfInstalledServiceNodeLooksWrong() {
     console.log(`[WARN] installed service node is older than 24: ${nodePath}${version ? ` (${version})` : ''}`);
     console.log('[WARN] Run foxclaw start from a Node 24 shell to refresh the service unit.');
 }
+function warnIfSystemdUserLingerDisabled() {
+    if (process.platform !== 'linux' || !hasCommand('loginctl')) {
+        return;
+    }
+    const user = currentServiceUser();
+    const linger = readSystemdUserLinger(user);
+    if (linger === 'enabled') {
+        console.log(`[OK] systemd user linger enabled: ${user}`);
+        return;
+    }
+    if (linger === 'disabled') {
+        console.log(`[WARN] systemd user linger is disabled for ${user}; user services may stop after logout.`);
+        console.log('[WARN] Run foxclaw start to let FoxClaw enable it, or run: sudo loginctl enable-linger "$USER"');
+    }
+}
 function extractNodePathFromExecStart(execStart) {
     const tokens = execStart.split(/\s+/).map(systemdUnescape).filter(Boolean);
     const directNode = tokens[0] || '';
@@ -1262,6 +1278,7 @@ function installSystemd() {
             console.log(`[OK] updated FoxClaw ExecStart override: ${update.path}`);
         }
     }
+    ensureSystemdUserLingerEnabled();
     spawnChecked('systemctl', ['--user', 'daemon-reload']);
     spawnChecked('systemctl', ['--user', 'enable', unitName]);
     const restarted = spawnSync('systemctl', ['--user', 'restart', unitName], { stdio: 'inherit' });
@@ -1272,6 +1289,32 @@ function installSystemd() {
     console.log(`Status: systemctl --user status ${unitName}`);
     console.log(`Logs:   journalctl --user -u ${unitName} -f`);
 }
+function ensureSystemdUserLingerEnabled() {
+    if (process.platform !== 'linux') {
+        return;
+    }
+    if (!hasCommand('loginctl')) {
+        console.log('[WARN] loginctl not found; cannot enable systemd user linger automatically.');
+        return;
+    }
+    const user = currentServiceUser();
+    const before = readSystemdUserLinger(user);
+    if (before === 'enabled') {
+        console.log(`[OK] systemd user linger enabled: ${user}`);
+        return;
+    }
+    console.log(`[INFO] Enabling systemd user linger for ${user} so FoxClaw keeps running after logout.`);
+    let result = spawnSync('loginctl', ['enable-linger', user], { stdio: 'inherit' });
+    if (result.status !== 0 && hasCommand('sudo')) {
+        result = spawnSync('sudo', ['-n', 'loginctl', 'enable-linger', user], { stdio: 'inherit' });
+    }
+    if (result.status === 0 && readSystemdUserLinger(user) === 'enabled') {
+        console.log(`[OK] systemd user linger enabled: ${user}`);
+        return;
+    }
+    console.log(`[WARN] Could not enable systemd user linger automatically for ${user}.`);
+    console.log(`[WARN] FoxClaw is installed, but it may stop after logout until you run: sudo loginctl enable-linger ${shellQuote(user)}`);
+}
 function uninstallSystemd() {
     if (!hasCommand('systemctl')) {
         console.error('systemctl not found');
@@ -1392,6 +1435,36 @@ function buildServicePath(nodeDir) {
 function serviceEnvPath() {
     return path.resolve(process.env.FOXCLAW_ENV?.trim() || getLoadedEnvPath() || DEFAULT_ENV_PATH);
 }
+function currentServiceUser() {
+    return process.env.USER?.trim()
+        || process.env.LOGNAME?.trim()
+        || os.userInfo().username;
+}
+function readSystemdUserLinger(user) {
+    const valueResult = spawnSync('loginctl', ['show-user', user, '-p', 'Linger', '--value'], { encoding: 'utf8' });
+    if (valueResult.status === 0) {
+        return parseSystemdUserLinger(valueResult.stdout);
+    }
+    const propertyResult = spawnSync('loginctl', ['show-user', user, '-p', 'Linger'], { encoding: 'utf8' });
+    if (propertyResult.status === 0) {
+        return parseSystemdUserLinger(propertyResult.stdout);
+    }
+    return 'unknown';
+}
+function parseSystemdUserLinger(output) {
+    const value = output.trim().replace(/^Linger=/, '').toLowerCase();
+    if (value === 'yes')
+        return 'enabled';
+    if (value === 'no')
+        return 'disabled';
+    return 'unknown';
+}
+function shellQuote(value) {
+    if (/^[A-Za-z0-9_@%+=:,./-]+$/.test(value)) {
+        return value;
+    }
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
 function hasStandardNodeProxyEnv() {
     return STANDARD_NODE_PROXY_ENV_KEYS.some((key) => Boolean(proxyEnvValue(key)));
 }

package/docs/install-for-beginners.md

@@ -250,17 +250,17 @@ Create a short README-style summary of this folder.
 
 ## 10. Service Commands
 
-On Linux, `foxclaw start` manages a user-level systemd service. Check it with:
+On Linux, `foxclaw start` manages a user-level systemd service and tries to enable systemd user linger so the service keeps running after you leave SSH or log out. Check it with:
 
 ```bash
 systemctl --user status foxclaw.service
 journalctl --user -u foxclaw.service -f
 ```
 
-The service starts again when your user session starts. If you need it to start after reboot before you log in, run:
+If install reports that linger could not be enabled automatically, run:
 
 ```bash
-loginctl enable-linger "$USER"
+sudo loginctl enable-linger "$USER"
 ```
 
 On macOS, `foxclaw start` manages launchd and starts FoxClaw when you log in.

package/docs/troubleshooting.md

@@ -261,10 +261,10 @@ Linux user systemd:
 systemctl --user is-enabled foxclaw.service
 ```
 
-`enabled` means it starts with your user session. To start after reboot before login:
+`enabled` means it starts with your user session. `foxclaw start` tries to enable systemd user linger automatically so the service keeps running after SSH logout and before login. If automatic linger setup fails:
 
 ```bash
-loginctl enable-linger "$USER"
+sudo loginctl enable-linger "$USER"
 ```
 
 macOS launchd starts FoxClaw when you log in after running:

package/docs/zh/install-for-beginners.md

@@ -248,17 +248,17 @@ Create a short README-style summary of this folder.
 
 ## 10. 服务命令
 
-Linux 上 `foxclaw start` 管理用户级 systemd 服务。查看状态：
+Linux 上 `foxclaw start` 管理用户级 systemd 服务，并会尝试启用 systemd user linger，让服务在你退出 SSH 或桌面会话后继续运行。查看状态：
 
 ```bash
 systemctl --user status foxclaw.service
 journalctl --user -u foxclaw.service -f
 ```
 
-如果希望重启后未登录也能启动用户服务：
+如果安装时提示 linger 启用失败，手动执行：
 
 ```bash
-loginctl enable-linger "$USER"
+sudo loginctl enable-linger "$USER"
 ```
 
 macOS 上 `foxclaw start` 管理 launchd，并在你登录后启动 FoxClaw。

package/docs/zh/troubleshooting.md

@@ -262,10 +262,10 @@ Linux 用户级 systemd：
 systemctl --user is-enabled foxclaw.service
 ```
 
-`enabled` 表示会随用户会话启动。如果希望机器重启后未登录也启动用户服务：
+`enabled` 表示会随用户会话启动。`foxclaw start` 会尝试自动启用 systemd user linger，让服务在退出 SSH 或未登录时也继续运行。如果自动启用失败：
 
 ```bash
-loginctl enable-linger "$USER"
+sudo loginctl enable-linger "$USER"
 ```
 
 macOS 上，运行过下面命令后，FoxClaw 会在你登录时由 launchd 启动：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foxden-app/foxclaw",
-  "version": "0.5.8",
+  "version": "0.5.9",
   "description": "Foxden local execution claw for controlling Codex from trusted chat interfaces.",
   "type": "module",
   "main": "dist/main.js",