flower-trellis 0.6.4 → 0.6.6

package/enhancements/MANIFEST.json

@@ -1,7 +1,7 @@
 {
-  "syncedAt": "2026-08-28T18:19:48.301Z",
+  "syncedAt": "2026-09-07T02:30:42.961Z",
   "syncedFrom": "vendor/skill-garden",
-  "sourceCommit": "124b592037eef542d7faf7ecb3be93b4bfd3aed0",
+  "sourceCommit": "ad64c8ab30cb14184895aa31d672cf1b846e5726",
   "common": {
     "codexSkills": [
       "aliyun-ops",
@@ -216,6 +216,12 @@
         "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-current-query-contract/patch.json",
+        "scripts/task-current-query-contract/task-current-content.py",
+        "scripts/task-current-query-contract/task-current-selector.py",
+        "scripts/task-reference-resolution/patch.json",
+        "scripts/task-reference-resolution/task-reference-content.py",
+        "scripts/task-reference-resolution/task-reference-selector.py",
         "scripts/task-start-brief-gate/degraded-content.py",
         "scripts/task-start-brief-gate/degraded-selector.py",
         "scripts/task-start-brief-gate/guard-content.py",
@@ -451,6 +457,7 @@
         "maven-verification.json",
         "shared-hook-runtime.json",
         "task-progress-recovery.json",
+        "task-reference-contract.json",
         "trellis-meta.json",
         "trellis-session-insight.json",
         "untracked-execution.json",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flower-trellis",
-  "version": "0.6.4",
+  "version": "0.6.6",
   "description": "一键安装/升级 Trellis 并自动融合 skill-garden 强化包(默认 Claude + agents)",
   "type": "module",
   "bin": {
@@ -33,7 +33,7 @@
     "README.md"
   ],
   "scripts": {
-    "test": "node --test test/js/*.test.js && python3 -m unittest discover -s test/python -p 'test_*.py' && node scripts/check-patch-conflicts.mjs && npm run patch:targets:check && node scripts/check-ai-context-budget.mjs && node scripts/check-output-templates.mjs",
+    "test": "node scripts/run-js-tests.mjs && python3 -m unittest discover -s test/python -p 'test_*.py' && node scripts/check-patch-conflicts.mjs && npm run patch:targets:check && node scripts/check-ai-context-budget.mjs && node scripts/check-output-templates.mjs",
     "sync": "node scripts/sync-enhancements.mjs",
     "patch:targets": "node scripts/run-skill-garden-compiled-targets.mjs",
     "patch:targets:check": "node scripts/run-skill-garden-compiled-targets.mjs --check",
@@ -70,9 +70,9 @@
     "commit-and-tag-version": "^12.7.3"
   },
   "flowerReleaseNotes": {
-    "version": "0.6.4",
+    "version": "0.6.6",
     "source": "CHANGELOG.md",
-    "body": "### 🐛 修复 Bug Fixes\n\n* **plugin:** 支持离线冻结未更新的外部 Plugin ([6210cfa](https://github.com/SilentFlower/flower-trellis/commit/6210cfae8d459a3e7b105043e4ecbc23d1b5bed9))",
+    "body": "### 🐛 修复 Bug Fixes\n\n* **codex:** 明确 Astra 规划授权边界 ([07428f8](https://github.com/SilentFlower/flower-trellis/commit/07428f8c4406449656edfe2e6dd6463d4540370a))",
     "truncated": false
   },
   "optionalDependencies": {

package/src/assets/flower_session_start.py

@@ -0,0 +1,195 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""复用 Trellis 原生 SessionStart，将启动上下文分成三个独立输出。"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+from contextlib import redirect_stdout
+from importlib.util import module_from_spec, spec_from_file_location
+from io import StringIO
+from pathlib import Path
+
+
+PARTS = ("state", "rules", "stages")
+HOOKS = (".codex/hooks/session-start.py", ".claude/hooks/session-start.py")
+MAX_PART_CHARS = 8000
+WORKFLOW_BLOCK = re.compile(r"<trellis-workflow>\n(.*?)\n</trellis-workflow>\n*", re.DOTALL)
+ASTRA_MODEL = "gpt-6-astra"
+ASTRA_HINT_MAX_BYTES = 2048
+ASTRA_WORKFLOW_HINT = """<trellis-astra-workflow-hint model="gpt-6-astra" version="1">
+Applies only while the active model is gpt-6-astra; it does not apply after switching models. Perform checks internally, without a routine checklist report. Keep ordinary answers brief.
+When executing the current task:
+- Treat required steps, required references, phase boundaries, and output templates in applicable SKILL and WORKFLOW instructions as execution and delivery checks.
+- Before a step, review its rules and required references. Reuse material already read in full and unchanged; search matches are not full reads.
+- Preserve required heading levels, section order, and conditional sections in specified templates. General brevity or no-heading preferences apply to ordinary prose and do not justify flattening, shortening, or reshaping a specified template.
+- Resolve conflicts by instruction hierarchy. Follow the owning workflow's phase-transition and review requirements, checking the scope of prior authorization; do not infer approval of the final plan from permission to begin planning.
+- Before claiming "read", "checked", or "complete", verify actual tool records and artifacts. Successful reading and compliant execution are separate facts.
+- When corrected, review the applicable rules, execution records, and actual result before repairing it. If evidence is missing, state uncertainty. Do not invent causes such as "not read", "forgot", or "file missing", or consult unrelated rules in place of the relevant ones.
+</trellis-astra-workflow-hint>"""
+
+
+def _astra_workflow_hint(root: Path) -> str:
+    """读取项目开关，返回唯一来源的 Astra 提示或空串。
+
+    @param root: 当前部署项目根目录。
+    @return: 完整提示块；显式关闭时为空串，非法配置或超预算时抛出异常。
+    """
+    scripts_dir = str(root / ".trellis" / "scripts")
+    if scripts_dir not in sys.path:
+        sys.path.insert(0, scripts_dir)
+    from common.trellis_config import read_trellis_config
+
+    config = read_trellis_config(root)
+    codex = config.get("codex", {})
+    if not isinstance(codex, dict):
+        raise ValueError("codex 配置必须为映射")
+    enabled = codex.get("astra_workflow_hint", True)
+    # 上游无依赖 YAML 读取器返回字符串，不能把字符串 false 当作真值。
+    if isinstance(enabled, str) and enabled.lower() in ("true", "false"):
+        enabled = enabled.lower() == "true"
+    if not isinstance(enabled, bool):
+        raise ValueError("codex.astra_workflow_hint 必须为 true 或 false")
+    if not enabled:
+        return ""
+    if len(ASTRA_WORKFLOW_HINT.encode("utf-8")) > ASTRA_HINT_MAX_BYTES:
+        raise ValueError("Astra 工作流提示超过 2048 字节预算")
+    return ASTRA_WORKFLOW_HINT
+
+
+def split_workflow(summary: str) -> dict[str, str]:
+    """按完整章节拆分工作流，保持原文和顺序。
+
+    @param summary: 原生 hook 生成的工作流摘要。
+    @return: rules 与 stages 的无损分段。
+    """
+    boundary = re.search(r"^### Planning Artifacts\s*$", summary, re.MULTILINE)
+    if boundary is None:
+        # 不能猜测新模板的边界，否则可能静默遗漏未知的工作流规则。
+        raise ValueError("工作流摘要缺少 Planning Artifacts 分段边界")
+    return {"rules": summary[:boundary.start()], "stages": summary[boundary.start():]}
+
+
+def _load_hook(root: Path, hook: str):
+    """加载已部署的原生 hook，避免复制平台状态与会话绑定逻辑。"""
+    path = root / hook
+    spec = spec_from_file_location("flower_native_session_start", path)
+    if spec is None or spec.loader is None:
+        raise ValueError(f"无法加载原生 hook：{hook}")
+    module = module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def render_part(root: Path, hook: str, part: str, hook_input: dict) -> dict | None:
+    """生成指定分段，只有 state 执行原生主入口的副作用。
+
+    @param root: 目标项目根目录。
+    @param hook: 已验证的原生平台 hook 相对路径。
+    @param part: state、rules 或 stages。
+    @param hook_input: 宿主传入的事件 JSON。
+    @return: 标准 SessionStart 输出；原生 hook 禁用时返回 None。
+    """
+    if hook not in HOOKS or part not in PARTS:
+        raise ValueError("不支持的 SessionStart hook 或分段")
+    module = _load_hook(root, hook)
+    if module.should_skip_injection():
+        return None
+    if part == "state":
+        output = StringIO()
+        original_stdin = sys.stdin
+        try:
+            sys.stdin = StringIO(json.dumps(hook_input, ensure_ascii=False))
+            with redirect_stdout(output):
+                module.main()
+        finally:
+            sys.stdin = original_stdin
+        if not output.getvalue().strip():
+            return None
+        result = json.loads(output.getvalue())
+        context = result["hookSpecificOutput"]["additionalContext"]
+        if len(WORKFLOW_BLOCK.findall(context)) != 1:
+            raise ValueError("原生启动输出必须包含且仅包含一个 trellis-workflow 块")
+        context = WORKFLOW_BLOCK.sub("", context)
+        # Claude 原生文件同时兼容其他平台；这里仅输出当前宿主的标准通道。
+        result.pop("additional_context", None)
+        if re.fullmatch(r"Trellis context injected \(\d+ chars\)", result.get("systemMessage", "")):
+            # 原计数对应拆分前的全文；保留其他原生诊断，避免以后吞掉重要提示。
+            result.pop("systemMessage")
+        if (hook == HOOKS[0] and hook_input.get("model") == ASTRA_MODEL
+                and hook_input.get("source") in ("startup", "clear", "compact")):
+            try:
+                hint = _astra_workflow_hint(root)
+                if hint:
+                    context = f"{context}\n{hint}"
+            except Exception as error:
+                # 提示是可选增强；失败不能吞掉已成功生成的原生启动上下文。
+                message = f"Astra 工作流提示未注入：{error}"
+                result["systemMessage"] = "\n".join(filter(None, [result.get("systemMessage"), message]))
+                print(message, file=sys.stderr)
+    else:
+        builder = module._build_workflow_toc if hook == HOOKS[0] else module._build_workflow_overview
+        context = split_workflow(builder(root / ".trellis/workflow.md"))[part]
+        result = {"hookSpecificOutput": {"hookEventName": "SessionStart"}}
+
+    context = f'<trellis-session-part name="{part}">\n{context}\n</trellis-session-part>'
+    result["hookSpecificOutput"]["additionalContext"] = context
+    if len(context) > MAX_PART_CHARS:
+        # 保留正文供宿主落盘补读，不能为了满足预算再次静默截断规则。
+        message = (
+            f"Trellis {part} 注入为 {len(context)} 字符，超过 {MAX_PART_CHARS} 字符预算；"
+            "请检查分段大小，并补读宿主保存的全文及 .trellis/workflow.md。"
+        )
+        result["systemMessage"] = "\n".join(filter(None, [result.get("systemMessage"), message]))
+    return result
+
+
+def main() -> int:
+    """读取事件并输出一个分段，异常以可见诊断交付。
+
+    @return: 成功或已输出诊断时为 0。
+    """
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--hook", required=True, choices=HOOKS)
+    parser.add_argument("--part", required=True, choices=PARTS)
+    args = parser.parse_args()
+    if os.environ.get("TRELLIS_HOOKS") == "0" or os.environ.get("TRELLIS_DISABLE_HOOKS") == "1":
+        return 0
+    if args.hook == HOOKS[0] and os.environ.get("CODEX_NON_INTERACTIVE") == "1":
+        return 0
+    try:
+        hook_input = json.load(sys.stdin)
+        if not isinstance(hook_input, dict):
+            raise ValueError("hook 输入必须为 JSON 对象")
+        if hook_input.get("source") == "resume":
+            return 0
+        # 脚本随项目部署；使用自身位置，避免宿主 cwd 进入子目录时加载另一份 hook。
+        root = Path(__file__).resolve().parents[2]
+        hook_input = {**hook_input, "cwd": str(root)}
+        result = render_part(root, args.hook, args.part, hook_input)
+    except Exception as error:
+        message = f"Trellis SessionStart {args.part} 注入失败：{error}"
+        print(message, file=sys.stderr)
+        result = {
+            "systemMessage": message,
+            "hookSpecificOutput": {
+                "hookEventName": "SessionStart",
+                "additionalContext": (
+                    f"<trellis-injection-error part=\"{args.part}\">\n"
+                    "Startup context is incomplete. Read .trellis/workflow.md and run "
+                    "python3 ./.trellis/scripts/get_context.py before continuing.\n"
+                    "</trellis-injection-error>"
+                ),
+            },
+        }
+    if result is not None:
+        print(json.dumps(result, ensure_ascii=False), flush=True)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/src/assets/flower_telemetry_hook.py

@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""将明确的平台活动交给 Flower 本地采集器；不输出或传递会话内容。"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+def config_directory(env: dict, platform: str, home: Path) -> Path:
+    """按 Node flowerConfigDirectory 相同规则定位用户目录。
+
+    @param env: 环境变量。
+    @param platform: win32 或其他平台。
+    @param home: 用户主目录。
+    @return: 用户配置路径。
+    """
+    if env.get("XDG_CONFIG_HOME"):
+        return Path(env["XDG_CONFIG_HOME"]) / "flower-trellis"
+    if platform == "win32" and env.get("APPDATA"):
+        return Path(env["APPDATA"]) / "flower-trellis"
+    return home / ".config" / "flower-trellis"
+
+
+def _read_json(file: Path) -> dict:
+    """只读普通小文件；损坏提示由 Node 最终判断。"""
+    if any(parent.is_symlink() for parent in [file, *file.parents]):
+        raise ValueError("symlink")
+    if not file.is_file() or file.stat().st_size > 16384:
+        raise ValueError("invalid file")
+    value = json.loads(file.read_text(encoding="utf-8"))
+    if not isinstance(value, dict):
+        raise ValueError("invalid json")
+    return value
+
+
+def _can_skip(platform: str) -> bool:
+    """同日提示命中后仍为到期 pending 留出唤醒机会。"""
+    try:
+        directory = config_directory(os.environ, sys.platform, Path.home())
+        state = _read_json(directory / "telemetry.json")
+        if state.get("enabled") is False:
+            return True
+        meta = _read_json(directory / "telemetry-v2" / "meta.json")
+        key = datetime.now(timezone.utc).date().isoformat() + ":" + platform
+        hint = meta.get("hints", {}).get(key)
+        if not isinstance(hint, dict) or not hint.get("event_id"):
+            return False
+        if meta.get("pending") == 0:
+            return hint.get("delivered") is True
+        retry = meta.get("nextRetryAt")
+        return bool(retry and datetime.fromisoformat(retry.replace("Z", "+00:00")).timestamp() > time.time())
+    except (OSError, ValueError, TypeError, AttributeError):
+        return False
+
+
+def main() -> None:
+    """适配 SessionStart/UserPromptSubmit，所有失败静默退出。
+
+    @return: 无输出。
+    """
+    try:
+        args = sys.argv[1:]
+        if len(args) != 2 or args[0] != "--platform" or args[1] not in ("claude", "codex"):
+            return
+        platform = args[1]
+        if os.environ.get("FLOWER_NO_TELEMETRY") or os.environ.get("TRELLIS_HOOKS") == "0" or os.environ.get("TRELLIS_DISABLE_HOOKS") == "1":
+            return
+        if platform == "codex" and os.environ.get("CODEX_NON_INTERACTIVE") == "1":
+            return
+        hook_input = json.loads(sys.stdin.read(1048577) or "{}")
+        if not isinstance(hook_input, dict) or hook_input.get("hook_event_name") not in ("SessionStart", "UserPromptSubmit"):
+            return
+        if _can_skip(platform):
+            return
+        target = os.environ.get("CLAUDE_PROJECT_DIR" if platform == "claude" else "CODEX_PROJECT_DIR") or hook_input.get("cwd")
+        if not isinstance(target, str) or not Path(target).is_dir():
+            return
+        command = shutil.which("flower-trellis")
+        if not command:
+            return
+        # 只转交固定事件类型、平台和本地定位参数；Node 独占身份创建及队列写入。
+        subprocess.run([command, "telemetry", "record-activity", platform, "--target", target],
+                       cwd=target, stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL,
+                       stderr=subprocess.DEVNULL, timeout=3, check=False)
+    except (OSError, ValueError, TypeError, subprocess.SubprocessError):
+        return
+
+
+if __name__ == "__main__":
+    main()

package/src/builtin-plugins/skill-garden/content-adapter.js

@@ -23,7 +23,7 @@ import {
   hashDirectoryIfExists,
   hashFileIfExists,
 } from "../../plugin/install/content-hash.js";
-import { FLOWER_UPDATE_HOOK, FLOWER_UPDATE_HOOK_REL } from "../../lib/flower-assets.js";
+import { FLOWER_UPDATE_HOOK, FLOWER_UPDATE_HOOK_REL, FLOWER_SESSION_HOOK, FLOWER_SESSION_HOOK_REL, FLOWER_TELEMETRY_HOOK, FLOWER_TELEMETRY_HOOK_REL } from "../../lib/flower-assets.js";
 import { PKG_ROOT } from "../../lib/paths.js";
 import { injectWorkflow } from "../../lib/workflow-inject.js";
 import { applyCodexTweaks } from "../../lib/codex-tweaks.js";
@@ -746,6 +746,20 @@ export function projectSkillGardenContent(options) {
       `flower:asset:${FLOWER_UPDATE_HOOK}`,
     );
     installed.add(`script:${FLOWER_UPDATE_HOOK}`);
+    if (pluginPackage.skillGarden.variant === "0.6") {
+      addFile(
+        FLOWER_SESSION_HOOK_REL,
+        fs.readFileSync(path.join(PKG_ROOT, "src", "assets", FLOWER_SESSION_HOOK)),
+        `flower:asset:${FLOWER_SESSION_HOOK}`,
+      );
+      installed.add(`script:${FLOWER_SESSION_HOOK}`);
+      addFile(
+        FLOWER_TELEMETRY_HOOK_REL,
+        fs.readFileSync(path.join(PKG_ROOT, "src", "assets", FLOWER_TELEMETRY_HOOK)),
+        `flower:asset:${FLOWER_TELEMETRY_HOOK}`,
+      );
+      installed.add(`script:${FLOWER_TELEMETRY_HOOK}`);
+    }
     const commonSync = describeInstalledCommonSkillSync(projectRoot);
     for (const common of commonSync.refreshes) {
       addTree(

package/src/cli.js

@@ -88,6 +88,7 @@ function printHelp() {
                                                         管理分支本地化 Git worktree
   flower-trellis uninstall [-y | --dry-run]              卸载 + 清理强化残留
   flower-trellis <其它命令> [...]                        透传给 trellis(面向未来)
+  flower-trellis <命令> --help                           查看命令级用法与下一步引导
   flower-trellis -v                                      打印版本
 
 flower 自有 flag:
@@ -107,6 +108,7 @@ flower 自有 flag:
   update-check skip|reset           跳过当前提示或清空提示节流状态
 
 Worktree:
+  worktree --help                     查看子命令、推荐流程和已有分支引导
   worktree create --target <dir> --branch <name> --task-title <title> --task-slug <slug>
                                       只读预检；默认 base 为当前来源分支
   worktree create ... --yes --plan-fingerprint <sha256>
@@ -137,7 +139,7 @@ async function main() {
 
   const argv = process.argv.slice(2);
 
-  // 顶层 -v / -h 仅在作为首个参数时拦截;子命令的 --help/--version 透传给 trellis
+  // 顶层 -v / -h 仅在作为首个参数时拦截；Flower 子命令各自处理帮助，其它命令透传 Trellis。
   if (argv[0] === "-v" || argv[0] === "--version") {
     printVersion(process.cwd());
     return;

package/src/commands/init.js

@@ -1,3 +1,4 @@
+import { observeTelemetryOperation, beginTelemetryOperation, completeTelemetryOperation } from "../lib/telemetry-operation.js";
 import fs from "node:fs";
 import { runTrellisPty } from "../lib/trellis-runner.js";
 import { plugin } from "./plugin.js";
@@ -9,6 +10,26 @@ import { ProjectStore } from "../plugin/state/project-store.js";
 import { SKILL_GARDEN_PLUGIN_ID } from "../builtin-plugins/skill-garden/provider.js";
 import { showCommandCompletion } from "../lib/command-completion.js";
 import { reportTelemetry } from "../lib/telemetry.js";
+import { hasHelpFlag } from "../lib/cli-args.js";
+
+/** 打印 init 命令帮助。 */
+function printInitHelp() {
+  console.log(`flower-trellis init — 初始化 Trellis 并安装 Skill Garden 强化
+
+用法:
+  flower-trellis init [trellis flags] [flower flags]
+
+常用选项:
+  -y, --yes               非交互执行，默认启用 Codex + Claude Code
+  --target <dir>           目标目录，必须已经存在
+  --no-enhance             只运行 Trellis init
+  --enhance-only           只安装强化包
+  --skills <a,b,...>       仅安装指定技能
+  --variant <old|0.5|0.6>  指定强化包变体
+  --no-update-check        本次跳过版本检查
+
+需要选择模板、monorepo 或平台时，移除 -y 进入交互流程。`);
+}
 
 /**
  * flower-trellis init:驱动 `trellis init`,随后叠加强化包。
@@ -23,6 +44,18 @@ import { reportTelemetry } from "../lib/telemetry.js";
  * @returns {Promise<void>} Trellis 初始化、强化叠加与完成交互结束后返回
  */
 export async function init(ctx) {
+  return observeTelemetryOperation(ctx, "init", executeInit);
+}
+
+/** 执行已建立外部操作上下文的命令。
+ * @param {object} ctx 命令上下文
+ * @returns {Promise<void>} 完成
+ */
+async function executeInit(ctx) {
+  if (hasHelpFlag(ctx.passthrough)) {
+    printInitHelp();
+    return;
+  }
   const { target } = ctx;
   if (!fs.existsSync(target) || !fs.statSync(target).isDirectory()) {
     throw new Error(`目标目录不存在:${target}`);
@@ -62,13 +95,14 @@ export async function init(ctx) {
     }
   }
 
+  if (!ctx.passthrough.includes("--dry-run")) beginTelemetryOperation(ctx);
   if (!ctx.enhanceOnly) {
     // 伪终端运行:保留 trellis 的模板 / monorepo 交互 + 过滤其重复 banner
     const code = await runTrellisPty(["init", ...passthrough], target, {
       stripBanner: true,
     });
     if (code !== 0) {
-      throw new Error(`trellis init 失败(退出码 ${code}),已中止,未叠加强化包`);
+      throw Object.assign(new Error(`trellis init 失败(退出码 ${code}),已中止,未叠加强化包`), { code: code === 130 ? "FLOWER_OPERATION_CANCELLED" : "FLOWER_UPSTREAM_FAILED" });
     }
   } else {
     console.log("· --enhance-only:跳过 trellis init,仅叠加强化包");
@@ -89,6 +123,7 @@ export async function init(ctx) {
     console.log("· --no-enhance:跳过强化包叠加");
   }
 
+  completeTelemetryOperation(ctx, "init");
   const telemetryPromise = reportTelemetry(target, "init_completed", { force: true });
   await showCommandCompletion("init", target, { passthrough });
   await telemetryPromise;

package/src/commands/plugin-remote.js

@@ -19,6 +19,22 @@ import { SourceRegistry } from "../plugin/sources/source-registry.js";
 import { UserSourceStore } from "../plugin/sources/user-source-store.js";
 import { listContentSkillChoices } from "../plugin/content-selection.js";
 import { compareUtf8 } from "../plugin/stable-order.js";
+import { classifyLockReachability } from "../plugin/lock-reachability.js";
+
+/**
+ * 计算远程准备允许读取的既有 lock 节点。
+ *
+ * 兼容直接调用测试时没有传入 `pluginsFile` 的旧签名，此时才回退到 lock roots；真实 CLI
+ * 始终传入当前声明，避免半清理项目的陈旧 roots 触发外部来源访问。
+ *
+ * @param {import("../plugin/contracts.js").ProjectPluginsFile|undefined} pluginsFile 当前声明
+ * @param {import("../plugin/contracts.js").PluginLock|null} lock 既有 lock
+ * @returns {Set<string>} 可准备的既有 lock ID
+ */
+function reachableRemoteLockIds(pluginsFile, lock) {
+  const declarations = pluginsFile?.plugins || (lock?.roots || []).map((id) => ({ id }));
+  return classifyLockReachability(declarations, lock).reachableIds;
+}
 
 /**
  * 输出 source、auth 与 search 管理命令结果。
@@ -537,22 +553,35 @@ export async function runPluginManagementCommand(parsed, ctx, options, output) {
 /**
  * 为生命周期命令登记所需的远程 Source Provider。
  *
- * @param {{parsed:object,projectRoot:string,options:object,registry:object,lock:object|null,preserveIds?:string[]}} context 远程准备上下文
+ * @param {{parsed:object,projectRoot:string,options:object,registry:object,lock:object|null,pluginsFile?:import("../plugin/contracts.js").ProjectPluginsFile,preserveIds?:string[]}} context 远程准备上下文
  * @returns {Promise<void>} 登记完成
  */
-export async function registerRemotePluginSources({ parsed, projectRoot, options, registry, lock, preserveIds = [] }) {
+export async function registerRemotePluginSources({
+  parsed,
+  projectRoot,
+  options,
+  registry,
+  lock,
+  pluginsFile,
+  preserveIds = [],
+}) {
   const preserved = new Set(preserveIds);
+  const reachableLockedIds = reachableRemoteLockIds(pluginsFile, lock);
   const remoteIds = new Set(["add", "update", "remove", "verify", "replay"].includes(parsed.command)
     ? (lock?.plugins || [])
-      .filter(({ id, source }) => !preserved.has(id) && ["gitlab", "github"].includes(source.type))
+      .filter(({ id, source }) => (
+        reachableLockedIds.has(id) &&
+        !preserved.has(id) &&
+        ["gitlab", "github"].includes(source.type)
+      ))
       .map(({ source }) => source.id)
     : []);
+  const declaredSourceId = parsed.pluginId?.includes("/")
+    ? parseCanonicalPluginId(parsed.pluginId).sourceId
+    : null;
   let sourceStore = null;
   let configuredSources = null;
   if (parsed.command === "add") {
-    const declaredSourceId = parsed.pluginId?.includes("/")
-      ? parseCanonicalPluginId(parsed.pluginId).sourceId
-      : null;
     const simpleSourceOption = parsed.source && !parsed.source.includes("/") && !parsed.source.includes(".")
       ? parsed.source
       : null;
@@ -587,7 +616,13 @@ export async function registerRemotePluginSources({ parsed, projectRoot, options
       remoteIds.add(simpleSourceOption);
     }
   }
-  if (parsed.command === "update" && parsed.pluginId?.includes("/")) {
+  const shouldCollectDependencySources = parsed.command === "update" || (
+    parsed.command === "add" &&
+    declaredSourceId &&
+    registry.has(declaredSourceId) &&
+    registry.get(declaredSourceId).type === "builtin"
+  );
+  if (shouldCollectDependencySources && parsed.pluginId?.includes("/")) {
     for (const sourceId of collectUnregisteredDependencySources(
       registry,
       [parsed.pluginId],
@@ -640,24 +675,34 @@ export async function registerRemotePluginSources({ parsed, projectRoot, options
 /**
  * 准备远程 Plugin 候选及固定 lock 缓存。
  *
- * @param {{parsed:object,canonicalId:string|null,registry:object,lock:object|null,preserveIds?:string[]}} context 候选准备上下文
+ * @param {{parsed:object,canonicalId:string|null,registry:object,lock:object|null,pluginsFile?:import("../plugin/contracts.js").ProjectPluginsFile,preserveIds?:string[]}} context 候选准备上下文
  * @returns {Promise<void>} 准备完成
  */
-export async function prepareRemotePluginCandidates({ parsed, canonicalId, registry, lock, preserveIds = [] }) {
+export async function prepareRemotePluginCandidates({
+  parsed,
+  canonicalId,
+  registry,
+  lock,
+  pluginsFile,
+  preserveIds = [],
+}) {
+  const reachableLockedIds = reachableRemoteLockIds(pluginsFile, lock);
   if (parsed.command === "add" && registry.has(parseCanonicalPluginId(canonicalId).sourceId)) {
-    await prepareRemoteLock(registry, lock, preserveIds);
+    await prepareRemoteLock(registry, lock, preserveIds, reachableLockedIds);
     await prepareRemoteClosure(registry, [canonicalId], preserveIds);
   } else if (parsed.command === "update") {
     // 更新单一 Plugin 时，解析器仍会 lock-first 重放完整图；先恢复全部远程固定包，
     // 再只为本轮显式更新目标加载新候选，避免顺带升级其它外部 Plugin。
-    await prepareRemoteLock(registry, lock, preserveIds);
+    await prepareRemoteLock(registry, lock, preserveIds, reachableLockedIds);
     const updateIds = canonicalId
       ? [canonicalId]
-      : (lock?.plugins || []).filter(({ source }) => ["gitlab", "github"].includes(source.type)).map(({ id }) => id);
+      : (lock?.plugins || [])
+        .filter(({ id, source }) => reachableLockedIds.has(id) && ["gitlab", "github"].includes(source.type))
+        .map(({ id }) => id);
     await prepareRemoteClosure(registry, updateIds, preserveIds);
     assertExternalVersionsNotReused(registry, lock, updateIds);
   } else if (["remove", "verify", "replay"].includes(parsed.command)) {
-    await prepareRemoteLock(registry, lock, preserveIds);
+    await prepareRemoteLock(registry, lock, preserveIds, reachableLockedIds);
   }
 }
 
@@ -725,12 +770,14 @@ async function prepareRemoteClosure(registry, initialIds, preserveIds = []) {
  * @param {object} registry Provider 注册表
  * @param {import("../plugin/contracts.js").PluginLock|null} lock 当前 lock
  * @param {string[]} [preserveIds] 不读取来源的冻结 Plugin ID
+ * @param {Set<string>|null} [reachableIds] 当前声明可达的既有 lock ID
  * @returns {Promise<void>} 恢复完成
  */
-async function prepareRemoteLock(registry, lock, preserveIds = []) {
+async function prepareRemoteLock(registry, lock, preserveIds = [], reachableIds = null) {
   const preserved = new Set(preserveIds);
   for (const plugin of lock?.plugins || []) {
     if (
+      (reachableIds && !reachableIds.has(plugin.id)) ||
       preserved.has(plugin.id) ||
       !["gitlab", "github"].includes(plugin.source.type) ||
       !registry.has(plugin.source.id)