flower-trellis 0.5.2-beta.1 → 0.5.3

package/enhancements/0.6/overrides/bundles/control-plane-integrity.json

@@ -5,6 +5,7 @@
   "installMode": "full-only",
   "patches": [
     "scripts/task-store-write-integrity",
-    "scripts/runtime-state-integrity"
+    "scripts/runtime-state-integrity",
+    "scripts/session-context-update-boundary"
   ]
 }

package/enhancements/0.6/overrides/conflicts.json

@@ -1101,6 +1101,28 @@
       },
       "owner": "trellis-route",
       "reason": "Claude workflow meta 必须与 shared route owner 模型一致。"
+    },
+    {
+      "id": "session-context-no-legacy-update-check",
+      "severity": "error",
+      "target": ".trellis/scripts/common/session_context.py",
+      "whenOperations": [
+        "session-context-update-imports",
+        "session-context-update-constants",
+        "session-context-update-helpers",
+        "session-context-update-output"
+      ],
+      "assertion": {
+        "type": "absent-literal",
+        "values": [
+          "def _get_update_hint(",
+          "def _mark_update_check_attempted(",
+          "def _update_marker_path(",
+          "[\"trellis\", \"--version\"]"
+        ]
+      },
+      "owner": "flower-update-hook",
+      "reason": "默认 Session Context 只负责项目上下文；更新检查必须统一由 Flower SessionStart Hook 进入。"
     }
   ]
 }

package/enhancements/0.6/overrides/patches/scripts/session-context-update-boundary/constants-selector.py

@@ -0,0 +1,6 @@
+_PACKAGE_NAME = "@mindfoldhq/trellis"
+_UPDATE_CHECK_TIMEOUT_SECONDS = 1.0
+_VERSION_RE = re.compile(
+    r"^\s*(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:-([0-9A-Za-z.-]+))?\s*$"
+)
+_VERSION_TOKEN_RE = re.compile(r"\b\d+(?:\.\d+){1,2}(?:-[0-9A-Za-z.-]+)?\b")

package/enhancements/0.6/overrides/patches/scripts/session-context-update-boundary/helpers-selector.py

@@ -0,0 +1,150 @@
+def _read_project_version(repo_root: Path) -> str | None:
+    try:
+        version = (repo_root / DIR_WORKFLOW / ".version").read_text(
+            encoding="utf-8"
+        ).strip()
+    except OSError:
+        return None
+    return version or None
+
+
+def _fetch_trellis_version_output() -> str | None:
+    try:
+        result = subprocess.run(
+            ["trellis", "--version"],
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=_UPDATE_CHECK_TIMEOUT_SECONDS,
+        )
+    except (OSError, subprocess.SubprocessError, TimeoutError):
+        return None
+
+    if result.returncode != 0:
+        return None
+    output = f"{result.stdout}\n{result.stderr}".strip()
+    return output or None
+
+
+def _extract_available_update_version(output: str) -> str | None:
+    update_match = re.search(
+        r"Trellis update available:\s*"
+        r"(?P<current>\S+)\s*(?:→|->)\s*(?P<latest>\S+)",
+        output,
+    )
+    if update_match:
+        return update_match.group("latest").strip()
+    candidates = _VERSION_TOKEN_RE.findall(output)
+    return candidates[-1] if candidates else None
+
+
+def _resolve_available_update_version() -> str | None:
+    output = _fetch_trellis_version_output()
+    if not output:
+        return None
+    return _extract_available_update_version(output)
+
+
+def _parse_version(version: str) -> tuple[tuple[int, int, int], tuple[str, ...] | None] | None:
+    match = _VERSION_RE.match(version)
+    if not match:
+        return None
+    major, minor, patch, prerelease = match.groups()
+    numbers = (int(major), int(minor or "0"), int(patch or "0"))
+    prerelease_parts = tuple(prerelease.split(".")) if prerelease else None
+    return numbers, prerelease_parts
+
+
+def _compare_prerelease(
+    left: tuple[str, ...] | None,
+    right: tuple[str, ...] | None,
+) -> int:
+    if left is None and right is None:
+        return 0
+    if left is None:
+        return 1
+    if right is None:
+        return -1
+
+    for left_part, right_part in zip(left, right):
+        if left_part == right_part:
+            continue
+        left_numeric = left_part.isdigit()
+        right_numeric = right_part.isdigit()
+        if left_numeric and right_numeric:
+            left_int = int(left_part)
+            right_int = int(right_part)
+            return (left_int > right_int) - (left_int < right_int)
+        if left_numeric:
+            return -1
+        if right_numeric:
+            return 1
+        return (left_part > right_part) - (left_part < right_part)
+
+    return (len(left) > len(right)) - (len(left) < len(right))
+
+
+def _compare_versions(left: str, right: str) -> int | None:
+    parsed_left = _parse_version(left)
+    parsed_right = _parse_version(right)
+    if parsed_left is None or parsed_right is None:
+        return None
+
+    left_numbers, left_prerelease = parsed_left
+    right_numbers, right_prerelease = parsed_right
+    if left_numbers != right_numbers:
+        return (left_numbers > right_numbers) - (left_numbers < right_numbers)
+    return _compare_prerelease(left_prerelease, right_prerelease)
+
+
+def _update_marker_path(repo_root: Path) -> Path:
+    context_key = resolve_context_key()
+    if not context_key:
+        terminal_key = os.environ.get("TERM_SESSION_ID", "").strip()
+        context_key = terminal_key or f"ppid-{os.getppid()}"
+    safe_key = re.sub(r"[^A-Za-z0-9._-]+", "_", context_key).strip("._-")
+    if not safe_key:
+        safe_key = "session"
+    return (
+        repo_root
+        / DIR_WORKFLOW
+        / ".runtime"
+        / f"update-check-{safe_key[:160]}.marker"
+    )
+
+
+def _mark_update_check_attempted(repo_root: Path) -> bool:
+    marker_path = _update_marker_path(repo_root)
+    if marker_path.exists():
+        return False
+    try:
+        marker_path.parent.mkdir(parents=True, exist_ok=True)
+        marker_path.write_text("checked\n", encoding="utf-8")
+    except OSError:
+        pass
+    return True
+
+
+def _get_update_hint(repo_root: Path) -> str | None:
+    marker_path = _update_marker_path(repo_root)
+    if marker_path.exists():
+        return None
+
+    current_version = _read_project_version(repo_root)
+    if not current_version:
+        return None
+
+    latest_version = _resolve_available_update_version()
+    if not latest_version:
+        return None
+
+    _mark_update_check_attempted(repo_root)
+    comparison = _compare_versions(current_version, latest_version)
+    if comparison is None or comparison >= 0:
+        return None
+
+    return (
+        f"Trellis update available: {current_version} -> {latest_version}, "
+        "run trellis upgrade"
+    )

package/enhancements/0.6/overrides/patches/scripts/session-context-update-boundary/imports-content.py

@@ -0,0 +1,4 @@
+import json
+from pathlib import Path
+
+from .config import get_git_packages

package/enhancements/0.6/overrides/patches/scripts/session-context-update-boundary/imports-selector.py

@@ -0,0 +1,8 @@
+import json
+import os
+import re
+import subprocess
+from pathlib import Path
+
+from .active_task import resolve_context_key
+from .config import get_git_packages

package/enhancements/0.6/overrides/patches/scripts/session-context-update-boundary/output-content.py

@@ -0,0 +1,7 @@
+def output_text(repo_root: Path | None = None) -> None:
+    """Output context in text format.
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+    """
+    print(get_context_text(repo_root))

package/enhancements/0.6/overrides/patches/scripts/session-context-update-boundary/output-selector.py

@@ -0,0 +1,13 @@
+def output_text(repo_root: Path | None = None) -> None:
+    """Output context in text format.
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+    update_hint = _get_update_hint(repo_root)
+    if update_hint:
+        print(update_hint)
+        print("")
+    print(get_context_text(repo_root))

package/enhancements/0.6/overrides/patches/scripts/session-context-update-boundary/patch.json

@@ -0,0 +1,53 @@
+{
+  "schemaVersion": 2,
+  "id": "session-context-update-boundary",
+  "purpose": "control_plane_integrity",
+  "operations": [
+    {
+      "id": "session-context-update-imports",
+      "operation": "replace",
+      "targets": [{
+        "kind": "file",
+        "path": ".trellis/scripts/common/session_context.py",
+        "missing": "error",
+        "markerStyle": "hash"
+      }],
+      "selector": { "type": "literal", "source": "imports-selector.py" },
+      "content": { "source": "imports-content.py" }
+    },
+    {
+      "id": "session-context-update-constants",
+      "operation": "remove",
+      "targets": [{
+        "kind": "file",
+        "path": ".trellis/scripts/common/session_context.py",
+        "missing": "error",
+        "markerStyle": "hash"
+      }],
+      "selector": { "type": "literal", "source": "constants-selector.py" }
+    },
+    {
+      "id": "session-context-update-helpers",
+      "operation": "remove",
+      "targets": [{
+        "kind": "file",
+        "path": ".trellis/scripts/common/session_context.py",
+        "missing": "error",
+        "markerStyle": "hash"
+      }],
+      "selector": { "type": "literal", "source": "helpers-selector.py" }
+    },
+    {
+      "id": "session-context-update-output",
+      "operation": "replace",
+      "targets": [{
+        "kind": "file",
+        "path": ".trellis/scripts/common/session_context.py",
+        "missing": "error",
+        "markerStyle": "hash"
+      }],
+      "selector": { "type": "literal", "source": "output-selector.py" },
+      "content": { "source": "output-content.py" }
+    }
+  ]
+}

package/enhancements/MANIFEST.json

@@ -1,7 +1,7 @@
 {
-  "syncedAt": "2026-07-29T10:02:05.260Z",
+  "syncedAt": "2026-07-29T12:22:03.171Z",
   "syncedFrom": "vendor/skill-garden",
-  "sourceCommit": "1812258cdd48d99b97e8dbab41f5203134e411df",
+  "sourceCommit": "1916ef11ba3cb40bead9ad827957224af850bd4f",
   "common": {
     "codexSkills": [
       "craft-rpa",
@@ -161,6 +161,13 @@
         "scripts/runtime-state-integrity/active-task-set-content.py",
         "scripts/runtime-state-integrity/active-task-set-selector.py",
         "scripts/runtime-state-integrity/patch.json",
+        "scripts/session-context-update-boundary/constants-selector.py",
+        "scripts/session-context-update-boundary/helpers-selector.py",
+        "scripts/session-context-update-boundary/imports-content.py",
+        "scripts/session-context-update-boundary/imports-selector.py",
+        "scripts/session-context-update-boundary/output-content.py",
+        "scripts/session-context-update-boundary/output-selector.py",
+        "scripts/session-context-update-boundary/patch.json",
         "scripts/task-start-brief-gate/degraded-content.py",
         "scripts/task-start-brief-gate/degraded-selector.py",
         "scripts/task-start-brief-gate/guard-content.py",

package/enhancements/common/.common/.claude/skills/craft-rpa/SKILL.md

@@ -70,7 +70,7 @@ bash "$SKILL_DIR/scripts/run.sh" craft [--session <ts>] [OUT]
                                                    # 转 jsonl → trace.md;--session 默认 = 当前/最新;OUT 默认 ./trace.md
 ```
 
-运行时状态 / sessions / profile 全部在 `$(pwd)/.craft-rpa/`(可用 `CRAFT_RPA_HOME` env 覆盖到任意路径)。首次 `start` 自动 `npm install`(跳浏览器下载,~10s)。
+运行时状态 / sessions / profile / 依赖全部在 `$(pwd)/.craft-rpa/`(可用 `CRAFT_RPA_HOME` env 覆盖到任意路径)。首次 `start` 自动安装依赖(跳浏览器下载,~10s),受管 skill 目录只保留静态代码资产。
 
 **AI 行为约定**(看到下列触发就跑对应子命令,不要手敲底层 cd / nohup):
 
@@ -106,24 +106,23 @@ bash "$SKILL_DIR/scripts/run.sh" craft [--session <ts>] [OUT]
 │   ├── 2026-05-18_14-22-15/
 │   └── legacy-2026-05-17_...   ← 老版本遗留 / 升级时自动归档
 ├── profile/                    ← Chrome 持久 profile(登录态,项目独立)
+├── runtime/recorder/           ← package manifest + node_modules,可重建
 ├── .launch.pid / .launch.log   ← 进程管理 + 日志
 └── .current-session            ← 最近一次 start 的会话 ts
 
-.claude/skills/craft-rpa/recorder/   ← skill 内仅代码资产;start 时建两个软链 → 数据根:
-├── session.jsonl → <repo>/.craft-rpa/sessions/<latest>/session.jsonl
-└── profile        → <repo>/.craft-rpa/profile
+.claude/skills/craft-rpa/recorder/   ← skill 内仅静态代码资产,不写 profile/session/node_modules
 ```
 
 **为什么这样**:
 - 录制 jsonl 是**项目业务数据**,跟着仓库走(每个仓库独立 session 池,不串)
 - skill 代码可装 `~/.claude/skills/craft-rpa/` 全局,所有仓库共用同一份代码
-- launch.js / logger.js 用 `__dirname` 解析 session.jsonl / profile,通过 recorder/ 内软链自动落到项目根 —— **录制器代码不用改**
+- run.sh 通过显式环境变量把 session/profile/Playwright 模块路径传给 launch.js,避免运行时产物进入 Plugin 管理树
 
 **关键性质**:
 
 - 每次 `run.sh start` 创建新时间戳目录,**不覆盖**历史
-- `recorder/session.jsonl` / `recorder/profile` 始终是软链,随当前会话切换目标
-- 老版本遗留的 `recorder/session.jsonl`(普通文件)在新版第一次 start 时自动归档到 `sessions/legacy-<ts>/`;`recorder/profile/`(普通目录)归档到 `.craft-rpa/profile-legacy-<ts>/`
+- 新版不会在 `recorder/` 创建软链或 `node_modules`;依赖位于 `.craft-rpa/runtime/recorder/`
+- 老版本遗留的 `recorder/session.jsonl` / `recorder/profile` 软链只删除链接本身,真实目标数据保留;普通文件/目录仍自动归档
 - `run.sh craft` 默认转最新;`--session <ts>` 可转任意历史
 - 删历史:手动 `rm -rf .craft-rpa/sessions/<ts>/`,run.sh 不管删
 

package/enhancements/common/.common/.claude/skills/craft-rpa/recorder/launch.js

@@ -18,19 +18,21 @@
  *      没有系统 Chrome 时改成 false，并执行 npx playwright install chromium
  *
  * 数据存放：
- *   - profile/        : 用户数据目录（cookie / localStorage / 登录态等），下次启动自动复用
- *   - session.jsonl   : 事件日志（由内置 logger 写入）
+ *   - CRAFT_RPA_PROFILE_DIR  : 用户数据目录（cookie / localStorage / 登录态等）
+ *   - CRAFT_RPA_SESSION_FILE : 事件日志（由内置 logger 写入）
  */
-const { chromium } = require('playwright');
 const path = require('path');
 const fs = require('fs');
+const PLAYWRIGHT_MODULE = process.env.CRAFT_RPA_PLAYWRIGHT_MODULE || 'playwright';
+const { chromium } = require(PLAYWRIGHT_MODULE);
 const { startLogger } = require('./logger');
 
 // 启动参数：第一个 CLI 参数作为起始 URL，没传就开空白页
 const START_URL = process.argv[2] || 'about:blank';
 
-// profile 目录放在脚本同级 ./profile/，与日常 Chrome 完全隔离
-const PROFILE_DIR = path.join(__dirname, 'profile');
+// run.sh 显式传入运行时目录；直接执行时保留原有默认值。
+const PROFILE_DIR = path.resolve(process.env.CRAFT_RPA_PROFILE_DIR || path.join(__dirname, 'profile'));
+const SESSION_LOG = path.resolve(process.env.CRAFT_RPA_SESSION_FILE || path.join(__dirname, 'session.jsonl'));
 
 // 注入脚本路径
 const INJECT_SCRIPT = path.join(__dirname, 'inject.js');
@@ -164,7 +166,7 @@ if (!fs.existsSync(INJECT_SCRIPT)) {
 
     // 先启动日志 + 控制服务，再启动浏览器
     // 浏览器一打开页面，注入脚本立刻就能 POST 成功，不会丢首批事件
-    const loggerServer = startLogger({ browserController });
+    const loggerServer = startLogger({ browserController, logFile: SESSION_LOG });
 
     console.log(`[launch] profile dir : ${PROFILE_DIR}`);
     console.log(`[launch] start url   : ${START_URL}`);

package/enhancements/common/.common/.claude/skills/craft-rpa/recorder/logger.js

@@ -16,7 +16,9 @@ const fs = require('fs');
 const path = require('path');
 
 const DEFAULT_PORT = 7777;
-const DEFAULT_LOG_FILE = path.join(__dirname, 'session.jsonl');
+const DEFAULT_LOG_FILE = path.resolve(
+    process.env.CRAFT_RPA_SESSION_FILE || path.join(__dirname, 'session.jsonl'),
+);
 
 /**
  * 启动本地日志收集服务

package/enhancements/common/.common/.claude/skills/craft-rpa/recorder/test/runtime-layout.test.js

@@ -0,0 +1,96 @@
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const test = require('node:test');
+
+/**
+ * 写入可执行的测试替身。
+ *
+ * @param {string} target 文件路径。
+ * @param {string} content 脚本内容。
+ * @return {void}
+ */
+function writeExecutable(target, content) {
+    fs.writeFileSync(target, content, { mode: 0o755 });
+}
+
+test('run.sh 将旧运行时产物迁出 Plugin 管理树', { skip: process.platform === 'win32' }, t => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'craft-rpa-runtime-layout-'));
+    const sourceSkill = path.resolve(__dirname, '..', '..');
+    const skillRoot = path.join(tempRoot, 'skill');
+    const recorderRoot = path.join(skillRoot, 'recorder');
+    const projectRoot = path.join(tempRoot, 'project');
+    const dataRoot = path.join(projectRoot, '.craft-rpa');
+    const fakeBin = path.join(tempRoot, 'bin');
+    let launchPid = null;
+
+    t.after(() => {
+        if (launchPid !== null) {
+            try { process.kill(launchPid, 'SIGTERM'); } catch (error) { /* 测试进程可能已结束。 */ }
+        }
+        fs.rmSync(tempRoot, { recursive: true, force: true });
+    });
+
+    fs.cpSync(sourceSkill, skillRoot, { recursive: true });
+    fs.mkdirSync(projectRoot, { recursive: true });
+    fs.mkdirSync(fakeBin, { recursive: true });
+
+    const profileTarget = path.join(dataRoot, 'profile');
+    const sessionTarget = path.join(dataRoot, 'sessions', 'old', 'session.jsonl');
+    fs.mkdirSync(profileTarget, { recursive: true });
+    fs.mkdirSync(path.dirname(sessionTarget), { recursive: true });
+    fs.writeFileSync(path.join(profileTarget, 'preserved.txt'), 'profile\n');
+    fs.writeFileSync(sessionTarget, '{"kind":"legacy"}\n');
+    fs.symlinkSync(profileTarget, path.join(recorderRoot, 'profile'), 'dir');
+    fs.symlinkSync(sessionTarget, path.join(recorderRoot, 'session.jsonl'));
+    fs.mkdirSync(path.join(recorderRoot, 'node_modules', 'playwright'), { recursive: true });
+    fs.writeFileSync(path.join(recorderRoot, 'node_modules', 'playwright', 'package.json'), '{}\n');
+
+    writeExecutable(path.join(fakeBin, 'npm'), `#!/usr/bin/env bash
+mkdir -p "$PWD/node_modules/playwright"
+printf '{}\\n' > "$PWD/node_modules/playwright/package.json"
+`);
+    writeExecutable(path.join(fakeBin, 'node'), `#!/usr/bin/env bash
+printf '%s\\n' "$CRAFT_RPA_SESSION_FILE" > "$CRAFT_RPA_HOME/fake-session-file"
+printf '%s\\n' "$CRAFT_RPA_PROFILE_DIR" > "$CRAFT_RPA_HOME/fake-profile-dir"
+printf '%s\\n' "$CRAFT_RPA_PLAYWRIGHT_MODULE" > "$CRAFT_RPA_HOME/fake-playwright-module"
+while true; do /bin/sleep 1; done
+`);
+
+    const result = spawnSync('bash', [path.join(skillRoot, 'scripts', 'run.sh'), 'start', 'about:blank'], {
+        cwd: projectRoot,
+        env: {
+            ...process.env,
+            CRAFT_RPA_HOME: dataRoot,
+            PATH: `${fakeBin}${path.delimiter}${process.env.PATH}`,
+        },
+        encoding: 'utf8',
+        timeout: 10000,
+    });
+
+    assert.equal(result.status, 0, `${result.stdout}\n${result.stderr}`);
+    launchPid = Number.parseInt(fs.readFileSync(path.join(dataRoot, '.launch.pid'), 'utf8'), 10);
+    assert.equal(Number.isInteger(launchPid), true);
+    assert.equal(fs.existsSync(path.join(recorderRoot, 'profile')), false);
+    assert.equal(fs.existsSync(path.join(recorderRoot, 'session.jsonl')), false);
+    assert.equal(fs.existsSync(path.join(recorderRoot, 'node_modules')), false);
+    assert.equal(fs.readFileSync(path.join(profileTarget, 'preserved.txt'), 'utf8'), 'profile\n');
+    assert.equal(fs.readFileSync(sessionTarget, 'utf8'), '{"kind":"legacy"}\n');
+
+    const runtimeRoot = path.join(dataRoot, 'runtime', 'recorder');
+    assert.equal(fs.existsSync(path.join(runtimeRoot, 'node_modules', 'playwright', 'package.json')), true);
+    assert.equal(
+        fs.readFileSync(path.join(dataRoot, 'fake-profile-dir'), 'utf8').trim(),
+        profileTarget,
+    );
+    assert.equal(
+        fs.readFileSync(path.join(dataRoot, 'fake-playwright-module'), 'utf8').trim(),
+        path.join(runtimeRoot, 'node_modules', 'playwright'),
+    );
+    const sessionFile = fs.readFileSync(path.join(dataRoot, 'fake-session-file'), 'utf8').trim();
+    assert.equal(sessionFile.startsWith(path.join(dataRoot, 'sessions')), true);
+    assert.equal(sessionFile.endsWith(path.join('', 'session.jsonl')), true);
+    assert.equal(fs.existsSync(sessionFile), true);
+});

package/enhancements/common/.common/.claude/skills/craft-rpa/scripts/run.sh

@@ -5,13 +5,11 @@
 #   ${CRAFT_RPA_HOME:-<cwd>/.craft-rpa}/
 #     ├── sessions/<YYYY-MM-DD_HH-MM-SS>/session.jsonl   每次 start 新建,不覆盖
 #     ├── profile/                                       Chrome 持久 profile(登录态)
+#     ├── runtime/recorder/node_modules/                  可重建运行时依赖
 #     ├── .launch.{pid,log}                              进程管理 + 日志
 #     └── .current-session                               最近一次 start 的 ts
 #
-# skill 内 .claude/skills/craft-rpa/recorder/ 启动时建两个软链 → 数据根:
-#   ├── session.jsonl → $CRAFT_RPA_HOME/sessions/<ts>/session.jsonl
-#   └── profile        → $CRAFT_RPA_HOME/profile
-# launch.js 用 __dirname 解析 session.jsonl / profile,通过软链落到项目根 .craft-rpa/
+# skill 内 recorder/ 只保留静态代码资产；运行时路径通过环境变量显式传给 launch.js。
 #
 # 用法:
 #   bash run.sh start [URL]
@@ -34,13 +32,73 @@ PROFILE_DIR="$CRAFT_RPA_HOME/profile"
 PID_FILE="$CRAFT_RPA_HOME/.launch.pid"
 LOG_FILE="$CRAFT_RPA_HOME/.launch.log"
 CURRENT_FILE="$CRAFT_RPA_HOME/.current-session"
-
-# skill 内 launch.js 通过 __dirname 看到的入口(软链 → 数据根)
-SESSION_LINK="$RECORDER_DIR/session.jsonl"
-PROFILE_LINK="$RECORDER_DIR/profile"
+RUNTIME_DIR="$CRAFT_RPA_HOME/runtime/recorder"
+RUNTIME_MODULES_DIR="$RUNTIME_DIR/node_modules"
+LEGACY_SESSION_PATH="$RECORDER_DIR/session.jsonl"
+LEGACY_PROFILE_PATH="$RECORDER_DIR/profile"
+LEGACY_MODULES_DIR="$RECORDER_DIR/node_modules"
 
 DASHBOARD_URL="http://localhost:7777/dashboard"
 
+prepare_runtime_dependencies() {
+    mkdir -p "$RUNTIME_DIR"
+    RUNTIME_CHANGED=false
+    for MANIFEST in package.json package-lock.json; do
+        if [ ! -f "$RECORDER_DIR/$MANIFEST" ]; then
+            continue
+        fi
+        if [ ! -f "$RUNTIME_DIR/$MANIFEST" ] || ! cmp -s "$RECORDER_DIR/$MANIFEST" "$RUNTIME_DIR/$MANIFEST"; then
+            cp "$RECORDER_DIR/$MANIFEST" "$RUNTIME_DIR/$MANIFEST"
+            RUNTIME_CHANGED=true
+        fi
+    done
+    if [ "$RUNTIME_CHANGED" = true ] || [ ! -d "$RUNTIME_MODULES_DIR/playwright" ]; then
+        echo "[craft-rpa] installing deps under $RUNTIME_DIR (one-time, ~30-60s) ..."
+        if [ -f "$RUNTIME_DIR/package-lock.json" ]; then
+            (cd "$RUNTIME_DIR" && PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 npm ci --no-audit --no-fund)
+        else
+            (cd "$RUNTIME_DIR" && PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 npm install --no-audit --no-fund)
+        fi
+    fi
+}
+
+cleanup_legacy_recorder_runtime() {
+    if [ -L "$LEGACY_SESSION_PATH" ]; then
+        # 只删除旧软链本身，真实 session 目标继续留在数据根。
+        rm -f "$LEGACY_SESSION_PATH"
+        echo "[craft-rpa] removed legacy recorder/session.jsonl symlink"
+    elif [ -e "$LEGACY_SESSION_PATH" ]; then
+        if [ -s "$LEGACY_SESSION_PATH" ]; then
+            LEGACY_TS=$(date +"%Y-%m-%d_%H-%M-%S")
+            LEGACY_DIR="$SESSIONS_DIR/legacy-$LEGACY_TS"
+            mkdir -p "$LEGACY_DIR"
+            mv "$LEGACY_SESSION_PATH" "$LEGACY_DIR/session.jsonl"
+            echo "[craft-rpa] migrated legacy recorder/session.jsonl → sessions/legacy-$LEGACY_TS/"
+        else
+            rm -f "$LEGACY_SESSION_PATH"
+        fi
+    fi
+
+    if [ -L "$LEGACY_PROFILE_PATH" ]; then
+        # 只删除旧软链本身，真实 profile 目标继续留在数据根。
+        rm -f "$LEGACY_PROFILE_PATH"
+        echo "[craft-rpa] removed legacy recorder/profile symlink"
+    elif [ -e "$LEGACY_PROFILE_PATH" ]; then
+        LEGACY_TS=$(date +"%Y-%m-%d_%H-%M-%S")
+        mv "$LEGACY_PROFILE_PATH" "$CRAFT_RPA_HOME/profile-legacy-$LEGACY_TS"
+        echo "[craft-rpa] migrated legacy recorder/profile → .craft-rpa/profile-legacy-$LEGACY_TS"
+    fi
+
+    if [ -L "$LEGACY_MODULES_DIR" ]; then
+        rm -f "$LEGACY_MODULES_DIR"
+        echo "[craft-rpa] removed legacy recorder/node_modules symlink"
+    elif [ -e "$LEGACY_MODULES_DIR" ]; then
+        # node_modules 只是可重建缓存，精确删除受管目录中的旧副本，避免 Plugin 重放再次扫描它。
+        rm -rf "$LEGACY_MODULES_DIR"
+        echo "[craft-rpa] removed legacy recorder/node_modules cache"
+    fi
+}
+
 cmd="${1:-status}"
 
 case "$cmd" in
@@ -60,44 +118,22 @@ case "$cmd" in
             exit 0
         fi
 
-        if [ ! -d "$RECORDER_DIR/node_modules" ]; then
-            echo "[craft-rpa] installing deps (one-time, ~30-60s) ..."
-            (cd "$RECORDER_DIR" && PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 npm install --no-audit --no-fund)
-        fi
-
         mkdir -p "$CRAFT_RPA_HOME" "$SESSIONS_DIR" "$PROFILE_DIR"
-
-        # 旧 session.jsonl 是普通文件(老版本遗留)→ 归档,避免 ln 覆盖丢数据
-        if [ -e "$SESSION_LINK" ] && [ ! -L "$SESSION_LINK" ]; then
-            if [ -s "$SESSION_LINK" ]; then
-                LEGACY_TS=$(date +"%Y-%m-%d_%H-%M-%S")
-                LEGACY_DIR="$SESSIONS_DIR/legacy-$LEGACY_TS"
-                mkdir -p "$LEGACY_DIR"
-                mv "$SESSION_LINK" "$LEGACY_DIR/session.jsonl"
-                echo "[craft-rpa] migrated legacy recorder/session.jsonl → sessions/legacy-$LEGACY_TS/"
-            else
-                rm -f "$SESSION_LINK"
-            fi
-        fi
-        # 旧 profile 是普通目录(老版本遗留)→ 归档到数据根
-        if [ -e "$PROFILE_LINK" ] && [ ! -L "$PROFILE_LINK" ]; then
-            LEGACY_TS=$(date +"%Y-%m-%d_%H-%M-%S")
-            mv "$PROFILE_LINK" "$CRAFT_RPA_HOME/profile-legacy-$LEGACY_TS"
-            echo "[craft-rpa] migrated legacy recorder/profile → .craft-rpa/profile-legacy-$LEGACY_TS"
-        fi
+        cleanup_legacy_recorder_runtime
+        prepare_runtime_dependencies
 
         TS=$(date +"%Y-%m-%d_%H-%M-%S")
         NEW_SESSION_DIR="$SESSIONS_DIR/$TS"
         mkdir -p "$NEW_SESSION_DIR"
         : > "$NEW_SESSION_DIR/session.jsonl"
 
-        # 建两个软链:launch.js / logger.js 通过 __dirname 读到的就是项目根的数据
-        ln -sfn "$NEW_SESSION_DIR/session.jsonl" "$SESSION_LINK"
-        ln -sfn "$PROFILE_DIR" "$PROFILE_LINK"
         echo "$TS" > "$CURRENT_FILE"
 
         cd "$RECORDER_DIR"
-        nohup node launch.js "$URL" > "$LOG_FILE" 2>&1 &
+        CRAFT_RPA_SESSION_FILE="$NEW_SESSION_DIR/session.jsonl" \
+            CRAFT_RPA_PROFILE_DIR="$PROFILE_DIR" \
+            CRAFT_RPA_PLAYWRIGHT_MODULE="$RUNTIME_MODULES_DIR/playwright" \
+            nohup node launch.js "$URL" > "$LOG_FILE" 2>&1 &
         PID=$!
         echo "$PID" > "$PID_FILE"
         sleep 1