@abelxiaoxing/cadence 1.8.0 → 1.8.2

package/README.md

@@ -14,6 +14,50 @@
 4. 首次进入项目先运行 `/abel-init`，然后 `/abel-design <需求>`，确认集中呈现的目标与方案，设计完成后运行 `/abel-implement <change>`。
 5. 暂停时先查看原因和建议，不要靠反复 resume 或重启“碰运气”；未完成的工作会保留。
 
+### 每次加载时的配置提示卡
+
+每次扩展启动、重载或恢复会话，Cadence 都会在输入框上方显示一张简短研究能力提示卡，不需要额外记住配置或诊断命令。
+卡片只检查本地配置，显示 Context7、Grok 与可选 Tavily 的配置状态及当前生效文件；“已配置”不代表网络、认证或服务能力已验证。
+开始处理任务后卡片收起，下次加载重新显示；不记录“已看过”或“暂时不用”来抑制后续提示。
+安装 Cadence 时会创建用户级模板 `~/.pi/agent/cadence/.env`（已有文件不会覆盖）；卡片本身不会联网、调用模型、写入配置、索要密钥或自动激活 Abel 工作流，可选服务未配置不阻塞普通任务。
+未信任的项目只显示未检查提示，不读取研究配置。
+
+安装后用户级模板已包含 Grok 配置占位字段；Context7 无配置文件时仍使用默认地址匿名访问，显式配置文件损坏仍会报错。
+联网搜索需要在本地文件中配置以下内容，每项一行（替换为实际服务地址和密钥）：
+
+```dotenv
+GROK_API_URL=https://api.x.ai/v1
+GROK_API_KEY=<your-api-key>
+```
+
+安装器会创建用户级 `~/.pi/agent/cadence/.env` 及其父目录，并且只在文件不存在时写入模板；也可手动创建该文件以跨项目复用。
+如果项目已有 `.pi/cadence/.env`，它按整文件优先，**不会与用户级文件合并**；请编辑卡片显示的生效文件，不要覆盖已有无关配置。
+研究 Skills 不读取 shell 中的 API 环境变量，也不读取安装包旁的 `.env`；保存后下次 Skill 调用生效，无需重启。
+可选 `CONTEXT7_API_KEY` 提供认证访问；可选 `TAVILY_API_KEY` 启用扩展检索、抓取和站点映射，`TAVILY_ENABLED=false` 可关闭它。
+完整字段见 [配置模板](config/.env.example)，配置文件限普通文件且不超过 64 KiB。
+密钥只在本地编辑，勿发送到聊天或提交 Git；使用项目级文件时应将其加入忽略规则。
+
+TUI 显示卡片；RPC 通过非阻塞 `setWidget` 事件发送同一卡片，Web UI 需实现该事件的展示。
+Print / JSON 无交互界面，不额外输出卡片、不等待输入，也不污染标准输出；可按上述路径直接配置。
+本版本提供提示与本地编辑指引，不提供密钥输入向导或自动重试搜索。
+
+### Pi / Web UI 阶段启动约定
+
+阶段命令需要 Cadence 扩展与包内 prompts 同时加载；只有提示正文可见，不代表 `abel_dispatch` 已注册或已激活。
+Web UI / SDK 集成应在会话空闲时提交原始命令：`session.prompt("/abel-design <需求>", { source: "rpc" })`。
+不要在客户端预展开模板，也不要通过 `steer()`、`followUp()` 或运行中的排队请求启动阶段。
+运行中的显式阶段命令会被拒绝并报告 `abel-stage-requires-idle`，等待当前请求结束后重新提交即可；原有阶段不会因此被退出或丢弃。
+
+启动失败有明确错误码：`abel-stage-provenance-invalid`（包来源不匹配）、`abel-stage-unverified-input`（缺少可验证的原始调用）和 `abel-stage-tools-unavailable`（工具未暴露或 Design 工具边界设置失败）。
+扩展会阻止失败请求的工具执行；不能改用 bash、subagent 或 terminal 工具绕过。
+空闲时正常启动会在首次模型请求前启用 `abel_dispatch` 并限制 Design 工具集合，显式退出后恢复进入前的工具集合。
+恢复会话或重载不会从历史提示自动激活阶段。
+
+如果扩展根本没有加载，扩展自身无法执行检查；提示中的缺失工具说明只是模型侧兜底，不是宿主级拦截。
+Web UI 必须展示资源加载器的 `getExtensions().errors`，核实当前会话已绑定扩展，并在发送阶段提示前检查 `session.getAllTools()` 中的 `abel_dispatch`；不存在时直接报告配置错误，不发送阶段正文。
+请检查包资源过滤是否禁用了 extensions、实际运行的 Node / Pi 版本，以及是否恢复了旧的工具清单。
+诊断时只记录工具名、命令来源和脱敏错误，不记录密钥或完整需求。
+
 ### 先检查环境，不先花模型调用
 
 在 Cadence 开发仓库中可用：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abelxiaoxing/cadence",
-  "version": "1.8.0",
+  "version": "1.8.2",
   "description": "Four explicit Abel workflow prompts with stage-isolated design and diagnosis, durable resumable implementation, and three package-owned professional Agents.",
   "license": "MIT",
   "type": "module",
@@ -37,6 +37,7 @@
     ]
   },
   "scripts": {
+    "postinstall": "node src/install-config.mjs",
     "pack:check": "node scripts/pack-check.mjs",
     "traceability:check": "node scripts/traceability-check.mjs",
     "verify": "bun run check && bun run lint && bun run test && bun run pack:check",

package/prompts/abel-design.md

@@ -16,6 +16,12 @@ $ARGUMENTS
 
 <!-- ABEL:PROMPT:abel-design -->
 
+Before following this procedure, check that `abel_dispatch` is actually callable in this model request.
+If it is missing, stop and report `Cadence configuration error: abel-stage-tools-unavailable`.
+Do not substitute bash, subagent, or terminal tools, and do not claim the stage started.
+Ask the operator to enable the Cadence extension together with its package prompts, inspect extension-load errors and tool filters, then resubmit the original slash command while the session is idle.
+A prompt marker or historical active/inactive message is not evidence that the tool is available.
+
 This stage is scoped to the invoked task.
 Direct answers and same-task continuations stay in this stage.
 If the user ends the workflow or requests an unrelated task, first send `{"action":"finish"}` to `abel_dispatch`, then handle the new task normally with the restored tools.

package/prompts/abel-diagnose.md

@@ -13,6 +13,12 @@ $ARGUMENTS
 
 <!-- ABEL:PROMPT:abel-diagnose -->
 
+Before following this procedure, check that `abel_dispatch` is actually callable in this model request.
+If it is missing, stop and report `Cadence configuration error: abel-stage-tools-unavailable`.
+Do not substitute bash, subagent, or terminal tools, and do not claim the stage started.
+Ask the operator to enable the Cadence extension together with its package prompts, inspect extension-load errors and tool filters, then resubmit the original slash command while the session is idle.
+A prompt marker or historical active/inactive message is not evidence that the tool is available.
+
 This stage is scoped to the invoked task.
 Direct answers and same-task continuations stay in this stage.
 If the user ends the workflow or requests an unrelated task, first send `{"action":"finish"}` to `abel_dispatch`, then handle the new task normally with the restored tools.

package/prompts/abel-implement.md

@@ -16,6 +16,12 @@ $ARGUMENTS
 
 <!-- ABEL:PROMPT:abel-implement -->
 
+Before following this procedure, check that `abel_dispatch` is actually callable in this model request.
+If it is missing, stop and report `Cadence configuration error: abel-stage-tools-unavailable`.
+Do not substitute bash, subagent, or terminal tools, and do not claim the stage started.
+Ask the operator to enable the Cadence extension together with its package prompts, inspect extension-load errors and tool filters, then resubmit the original slash command while the session is idle.
+A prompt marker or historical active/inactive message is not evidence that the tool is available.
+
 This stage is scoped to the invoked task.
 Direct answers and same-task continuations stay in this stage.
 If the user ends the workflow or requests an unrelated task, first send `{"action":"finish"}` to `abel_dispatch`, then handle the new task normally with the restored tools.

package/skills/_shared/load-config.d.mts

@@ -1,7 +1,13 @@
 export declare function parseEnvFile(content: string): Record<string, string>;
 
+export declare function selectConfigPath(options: {
+  cwd: string;
+  home: string;
+}): string | null;
+
 export declare function loadConfig(options: {
   cwd: string;
   home: string;
   required?: readonly string[];
-}): { path: string; values: Record<string, string> };
+  allowMissing?: boolean;
+}): { path: string | null; values: Record<string, string> };

package/skills/_shared/load-config.mjs

@@ -1,4 +1,11 @@
-import { existsSync, readFileSync } from "node:fs";
+import {
+  closeSync,
+  constants,
+  fstatSync,
+  lstatSync,
+  openSync,
+  readSync,
+} from "node:fs";
 import path from "node:path";
 
 export function parseEnvFile(content) {
@@ -37,22 +44,68 @@ export function parseEnvFile(content) {
   return values;
 }
 
-export function loadConfig({ cwd, home, required = [] }) {
+function pathEntryExists(filePath) {
+  try {
+    // lstat, rather than existsSync, intentionally retains dangling symlinks.
+    // They are an explicit configuration path and must fail closed when opened.
+    lstatSync(filePath);
+    return true;
+  } catch (error) {
+    if (error?.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+export function selectConfigPath({ cwd, home }) {
   const projectPath = path.join(cwd, ".pi", "cadence", ".env");
   const userPath = path.join(home, ".pi", "agent", "cadence", ".env");
-  const selectedPath = existsSync(projectPath)
+  return pathEntryExists(projectPath)
     ? projectPath
-    : existsSync(userPath)
+    : pathEntryExists(userPath)
       ? userPath
       : null;
+}
+
+export function loadConfig({ cwd, home, required = [], allowMissing = false }) {
+  const selectedPath = selectConfigPath({ cwd, home });
+  if (!selectedPath && allowMissing && required.length === 0) {
+    return { path: null, values: {} };
+  }
 
   if (!selectedPath) {
+    const projectPath = path.join(cwd, ".pi", "cadence", ".env");
+    const userPath = path.join(home, ".pi", "agent", "cadence", ".env");
     throw new Error(
       `No cadence configuration file found; create ${projectPath} or ${userPath}`,
     );
   }
 
-  const values = parseEnvFile(readFileSync(selectedPath, "utf8"));
+  // Configuration inspection also runs at extension startup: never block on
+  // a FIFO/device or read an unbounded file. Read one extra byte to detect growth.
+  const maxBytes = 64 * 1024;
+  const fd = openSync(selectedPath, constants.O_RDONLY | constants.O_NONBLOCK);
+  let content;
+  try {
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || stat.size > maxBytes) {
+      throw new Error(
+        "Cadence configuration must be a regular file of at most 64 KiB",
+      );
+    }
+    const buffer = Buffer.alloc(maxBytes + 1);
+    let size = 0;
+    while (size < buffer.length) {
+      const count = readSync(fd, buffer, size, buffer.length - size, null);
+      if (!count) break;
+      size += count;
+    }
+    if (size > maxBytes)
+      throw new Error("Cadence configuration exceeds 64 KiB");
+    content = buffer.subarray(0, size).toString("utf8");
+  } finally {
+    closeSync(fd);
+  }
+  const values = parseEnvFile(content);
   const missing = required.filter((name) => !values[name]);
   if (missing.length > 0) {
     throw new Error(

package/skills/context7-auto-research/SKILL.md

@@ -30,3 +30,8 @@ Treat a non-zero exit, invalid shape, or empty useful result as a failed lookup;
 The CLI selects the project `.pi/cadence/.env` as a whole file when present, otherwise `~/.pi/agent/cadence/.env`.
 It does not merge files, read ambient API configuration, or read `.env` beside the installed package.
 `CONTEXT7_API_KEY` may be empty; `CONTEXT7_API_URL` defaults to `https://context7.com/api/v2`.
+When neither configuration file exists, use those anonymous defaults without creating a file.
+An existing malformed or unreadable file is still an error; never silently fall back.
+Cadence shows a local configuration card on every extension load in TUI/RPC; configured does not mean network-verified.
+Configuration files must be regular files of at most 64 KiB.
+Never ask for API keys in chat.

package/skills/context7-auto-research/context7.mjs

@@ -9,7 +9,7 @@ import { loadConfig } from "../_shared/load-config.mjs";
 const DEFAULT_API_URL = "https://context7.com/api/v2";
 
 export function loadContext7Config({ cwd, home }) {
-  const selected = loadConfig({ cwd, home });
+  const selected = loadConfig({ cwd, home, allowMissing: true });
   return {
     path: selected.path,
     apiUrl: selected.values.CONTEXT7_API_URL || DEFAULT_API_URL,

package/skills/grok-search/SKILL.md

@@ -36,4 +36,9 @@ Treat non-zero exits and invalid result shapes as failed research.
 
 The CLI selects the project `.pi/cadence/.env` as a whole file when present, otherwise `~/.pi/agent/cadence/.env`.
 `GROK_API_URL` and `GROK_API_KEY` are required.
+Cadence shows the selected configuration path and missing fields on every extension load in TUI/RPC, without network verification.
+If configuration is missing, direct the user to edit that local file (prefer the user file when no project file exists); never ask them to paste a key in chat.
+The CLI does not read shell API variables.
+Save one `NAME=value` per line; the next invocation reads the changes without restarting Pi.
+Configuration files must be regular files of at most 64 KiB.
 `GROK_MODEL` defaults to `grok-4.20-non-reasoning`, `TAVILY_API_URL` defaults to `https://api.tavily.com`, and Tavily is enabled by default once a non-empty `TAVILY_API_KEY` is configured; set `TAVILY_ENABLED=false` to opt out.

package/src/index.ts

@@ -21,6 +21,8 @@ export { executePackageVerification } from "./package-verification.ts";
 // workflow routing (abel-design/implement/diagnose provenance) in the prompts
 // integration; abel-init and ordinary prompts never activate dispatch.
 
+import { createHash } from "node:crypto";
+import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import type {
@@ -57,7 +59,7 @@ import { canonicalJson } from "./implement-graph.ts";
 import { PACKET_ACTIONS, PacketRuntime } from "./packet-runtime.ts";
 
 import { RunStoreFormatError, RunStoreMigrationError } from "./run-store.ts";
-
+import { STARTUP_CARD_KEY, startupCardLines } from "./startup-card.ts";
 import { StateRootError } from "./state-root.ts";
 import {
   ACTIVITY_DETAILS_KEY,
@@ -369,6 +371,27 @@ function hasExpandedPromptMarker(
   );
 }
 
+// A marker is never authority. Recognize only the expanded entrypoint shape
+// here so quoted documentation and ordinary command discussions stay ordinary.
+function expandedStagePrompt(text: string): EligiblePrompt | undefined {
+  return ELIGIBLE_PROMPTS.find(
+    (name) =>
+      text.startsWith(
+        `This procedure applies only when the user explicitly invokes \`/${name}\`.`,
+      ) && hasExpandedPromptMarker(text, name),
+  );
+}
+
+type StageStartupError =
+  | "abel-stage-requires-idle"
+  | "abel-stage-provenance-invalid"
+  | "abel-stage-unverified-input"
+  | "abel-stage-tools-unavailable";
+
+function startupErrorText(code: StageStartupError): string {
+  return `Cadence configuration error: ${code}. Do not execute this workflow or substitute shell/subagent tools for abel_dispatch. Ensure the Cadence extension and its package prompts are enabled, inspect host extension-load errors and tool filters, then submit the original slash command through session.prompt when idle. Do not pre-expand the template or queue it through steer/followUp. No new stage authority was granted by this rejected request.`;
+}
+
 function isVerifiedStageInvocation(
   pi: ExtensionAPI,
   activation: Activation,
@@ -719,6 +742,21 @@ export function registerWorkflowControl(
   let exitingStage = false;
   let activePrompt: EligiblePrompt | undefined;
   let designToolSnapshot: string[] | undefined;
+  let startupFailure: StageStartupError | undefined;
+  let admittedPrompt: string | undefined;
+  let latestContextUser: string | undefined;
+  const admittedMessages = new Set<string>();
+  const reportStartupFailure = (code: StageStartupError) => {
+    pi.sendMessage(
+      {
+        customType: "abel-stage-startup-error",
+        content: startupErrorText(code),
+        display: true,
+        details: { code },
+      },
+      { triggerTurn: false },
+    );
+  };
   const activation = new (class implements Activation {
     state: Activation["state"] = "inactive";
 
@@ -791,6 +829,18 @@ export function registerWorkflowControl(
       ),
     );
   };
+  const stageToolsAvailable = () => {
+    if (!activation.isActive()) return true;
+    const tools = pi.getActiveTools();
+    return (
+      tools.includes(DISPATCH_TOOL) &&
+      (activePrompt !== "abel-design" ||
+        tools.every(
+          (name) =>
+            name === DISPATCH_TOOL || DESIGN_PARENT_READ_TOOLS.has(name),
+        ))
+    );
+  };
   const deactivate = () => {
     activation.drain();
     if (designToolSnapshot) {
@@ -900,7 +950,6 @@ export function registerWorkflowControl(
 
   const registerDispatchTool = (kind: "command" | "packet") => {
     if (registeredParameterKind === kind) return;
-    registeredParameterKind = kind;
     pi.registerTool({
       name: DISPATCH_TOOL,
       label: "Abel Control",
@@ -926,6 +975,7 @@ export function registerWorkflowControl(
         ctx: ExtensionContext,
       ) {
         if (
+          startupFailure ||
           exitingStage ||
           !activation.isActive() ||
           activePrompt === undefined
@@ -1353,6 +1403,7 @@ export function registerWorkflowControl(
         );
       },
     } as never);
+    registeredParameterKind = kind;
   };
   registerDispatchTool("packet");
 
@@ -1411,6 +1462,17 @@ export function registerWorkflowControl(
       // expose the complete workflow instructions to the parent model.
       return { action: prompt || init ? "handled" : "continue" };
     }
+    if (
+      prompt &&
+      (event.streamingBehavior || !hasPackageProvenance(pi, prompt))
+    ) {
+      reportStartupFailure(
+        event.streamingBehavior
+          ? "abel-stage-requires-idle"
+          : "abel-stage-provenance-invalid",
+      );
+      return { action: "handled" };
+    }
     pendingPrompt = prompt;
     pendingImplementChange =
       prompt === "abel-implement"
@@ -1430,6 +1492,9 @@ export function registerWorkflowControl(
     return { action: "continue" };
   });
   pi.on("before_agent_start", (event, ctx) => {
+    startupFailure = undefined;
+    admittedPrompt = undefined;
+    latestContextUser = undefined;
     const prompt = pendingPrompt;
     const implementChange = pendingImplementChange;
     const init =
@@ -1439,43 +1504,143 @@ export function registerWorkflowControl(
     pendingInit = false;
     const verified =
       prompt && isVerifiedStageInvocation(pi, activation, prompt, event.prompt);
-    if (verified) {
-      if (activePrompt === "abel-design" && prompt !== "abel-design") {
-        restoreDesignTools();
+    if (prompt && !verified) startupFailure = "abel-stage-unverified-input";
+    if (!prompt && expandedStagePrompt(event.prompt))
+      startupFailure = "abel-stage-unverified-input";
+    const toolsBefore = pi.getActiveTools();
+    const wasActive = activation.isActive();
+    try {
+      if (verified) {
+        if (activePrompt === "abel-design" && prompt !== "abel-design") {
+          restoreDesignTools();
+        }
+        registerDispatchTool(
+          prompt === "abel-implement" ? "command" : "packet",
+        );
+        activePrompt = prompt;
+        if (prompt === "abel-implement") {
+          if (
+            implementChange &&
+            implementPromptBindsChange(event.prompt, implementChange) &&
+            typeof ctx.cwd === "string"
+          )
+            implementContinuation.activate({
+              cwd: ctx.cwd,
+              change: implementChange,
+            });
+          else implementContinuation.deactivate();
+        } else {
+          implementContinuation.deactivate();
+        }
       }
-      registerDispatchTool(prompt === "abel-implement" ? "command" : "packet");
-      activePrompt = prompt;
-      if (prompt === "abel-implement") {
-        if (
-          implementChange &&
-          implementPromptBindsChange(event.prompt, implementChange) &&
-          typeof ctx.cwd === "string"
-        )
-          implementContinuation.activate({
-            cwd: ctx.cwd,
-            change: implementChange,
-          });
-        else implementContinuation.deactivate();
-      } else {
-        implementContinuation.deactivate();
+      if (prompt) activateDispatcher(pi, activation, prompt, event.prompt);
+      if (activation.isActive() && activePrompt === "abel-design")
+        enforceDesignTools();
+      if (!stageToolsAvailable())
+        startupFailure = "abel-stage-tools-unavailable";
+    } catch {
+      startupFailure = "abel-stage-tools-unavailable";
+    }
+    if (
+      startupFailure === "abel-stage-tools-unavailable" &&
+      verified &&
+      !wasActive
+    ) {
+      // Roll back the failed startup, not a retained durable run. Never leave
+      // partially applied Design restrictions or a falsely active stage.
+      activePrompt = undefined;
+      activation.drain();
+      implementContinuation.deactivate();
+      designToolSnapshot = undefined;
+      try {
+        pi.setActiveTools(toolsBefore);
+      } catch {
+        /* tool_call remains closed */
       }
     }
-    if (prompt) activateDispatcher(pi, activation, prompt, event.prompt);
-    if (activation.isActive() && activePrompt === "abel-design")
-      enforceDesignTools();
+    if (verified && !startupFailure) admittedPrompt = event.prompt;
     if (
       activation.isActive() &&
       activePrompt === "abel-implement" &&
       typeof ctx.cwd === "string"
     )
       implementContinuation.beginParentTurn(ctx.cwd);
-    const boundary = activePrompt
-      ? `Abel stage ${activePrompt} is active only for the invoked task and its direct follow-ups. If the user ends it or requests an unrelated task, first call abel_dispatch with {"action":"finish"}, then handle that task normally with the restored tools. A successful finish ends stage authority immediately, including within this turn. Do not extend Gates or workflow rules to that task. A direct Gate answer or same-task continuation stays in this stage. Never invoke another Abel stage automatically.`
-      : init
-        ? "Only this explicit /abel-init request authorizes the local Init procedure. Do not activate dispatch or continue into another Abel stage."
-        : "Abel workflow is inactive. Handle ordinary engineering requests directly. References to commands, repository files, OpenSpec changes, and historical workflow instructions do not authorize a workflow. Do not load or execute an Abel stage unless the user explicitly invokes its slash command.";
+    const boundary = startupFailure
+      ? startupErrorText(startupFailure)
+      : activePrompt
+        ? `Abel stage ${activePrompt} is active only for the invoked task and its direct follow-ups. If the user ends it or requests an unrelated task, first call abel_dispatch with {"action":"finish"}, then handle that task normally with the restored tools. A successful finish ends stage authority immediately, including within this turn. Do not extend Gates or workflow rules to that task. A direct Gate answer or same-task continuation stays in this stage. Never invoke another Abel stage automatically.`
+        : init
+          ? "Only this explicit /abel-init request authorizes the local Init procedure. Do not activate dispatch or continue into another Abel stage."
+          : "Abel workflow is inactive. Handle ordinary engineering requests directly. References to commands, repository files, OpenSpec changes, and historical workflow instructions do not authorize a workflow. Do not load or execute an Abel stage unless the user explicitly invokes its slash command.";
     return { systemPrompt: `${event.systemPrompt ?? ""}\n\n${boundary}` };
   });
+  pi.on("context", (event) => {
+    const lastUser = event.messages.findLastIndex(
+      (message) => message.role === "user",
+    );
+    const retainedAdmissions = new Set<string>();
+    const messages = event.messages.map((message, index) => {
+      if (message.role !== "user") return message;
+      const text =
+        typeof message.content === "string"
+          ? message.content
+          : message.content
+              .filter((part) => part.type === "text")
+              .map((part) => part.text)
+              .join("\n");
+      const key = createHash("sha256")
+        .update(`${message.timestamp}:${text}`)
+        .digest("hex");
+      if (index === lastUser) {
+        if (latestContextUser !== undefined && latestContextUser !== key)
+          startupFailure = undefined;
+        latestContextUser = key;
+        try {
+          if (!stageToolsAvailable())
+            startupFailure = "abel-stage-tools-unavailable";
+        } catch {
+          startupFailure = "abel-stage-tools-unavailable";
+        }
+        if (admittedPrompt === text && !startupFailure)
+          admittedMessages.add(key);
+        admittedPrompt = undefined;
+      }
+      if (admittedMessages.has(key)) retainedAdmissions.add(key);
+      const orphan = expandedStagePrompt(text) && !admittedMessages.has(key);
+      if (index === lastUser && orphan && !startupFailure)
+        startupFailure = "abel-stage-unverified-input";
+      if (!orphan && !(index === lastUser && startupFailure)) return message;
+      return {
+        ...message,
+        content: [
+          {
+            type: "text" as const,
+            text: startupErrorText(
+              index === lastUser && startupFailure
+                ? startupFailure
+                : "abel-stage-unverified-input",
+            ),
+          },
+        ],
+      };
+    });
+    // Keep only identities still present after compaction; never retain raw requirements.
+    admittedMessages.clear();
+    for (const key of retainedAdmissions) admittedMessages.add(key);
+    return { messages };
+  });
+  pi.on("tool_call", (event) => {
+    if (!stageToolsAvailable()) startupFailure = "abel-stage-tools-unavailable";
+    if (startupFailure)
+      return { block: true, reason: startupErrorText(startupFailure) };
+    // Defense in depth against a host/extension restoring a stale tool list.
+    if (
+      activePrompt === "abel-design" &&
+      event.toolName !== DISPATCH_TOOL &&
+      !DESIGN_PARENT_READ_TOOLS.has(event.toolName)
+    )
+      return { block: true, reason: "abel-design-tool-boundary" };
+  });
   pi.on("before_provider_request", (event, ctx) => {
     if (
       activePrompt !== "abel-design" ||
@@ -1495,6 +1660,7 @@ export function registerWorkflowControl(
     const aborted = () => runSignal?.aborted || ctx.signal?.aborted;
     if (
       aborted() ||
+      startupFailure ||
       exitingStage ||
       !activation.isActive() ||
       activePrompt !== "abel-implement"
@@ -1590,6 +1756,10 @@ export function registerWorkflowControl(
     );
   });
   pi.on("session_start", async (_event, ctx) => {
+    startupFailure = undefined;
+    admittedPrompt = undefined;
+    latestContextUser = undefined;
+    admittedMessages.clear();
     pendingPrompt = undefined;
     pendingImplementChange = undefined;
     pendingInit = false;
@@ -1603,6 +1773,10 @@ export function registerWorkflowControl(
     if (ctx.mode === "tui") activity.attach(ctx.ui);
   });
   pi.on("session_shutdown", async () => {
+    startupFailure = undefined;
+    admittedPrompt = undefined;
+    latestContextUser = undefined;
+    admittedMessages.clear();
     pendingPrompt = undefined;
     pendingImplementChange = undefined;
     pendingInit = false;
@@ -1619,4 +1793,22 @@ export function registerWorkflowControl(
 
 export default function register(pi: ExtensionAPI): void {
   registerWorkflowControl(pi);
+  // Presentation only: never persist a dismissal or inject a model message.
+  pi.on("session_start", (_event, ctx) => {
+    if (!ctx.hasUI) return;
+    ctx.ui.setWidget(
+      STARTUP_CARD_KEY,
+      startupCardLines({
+        cwd: ctx.cwd,
+        home: homedir(),
+        projectTrusted: ctx.isProjectTrusted(),
+      }),
+    );
+  });
+  pi.on("agent_start", (_event, ctx) => {
+    if (ctx.hasUI) ctx.ui.setWidget(STARTUP_CARD_KEY, undefined);
+  });
+  pi.on("session_shutdown", (_event, ctx) => {
+    if (ctx.hasUI) ctx.ui.setWidget(STARTUP_CARD_KEY, undefined);
+  });
 }

package/src/install-config.d.mts

@@ -0,0 +1,6 @@
+export declare const CONFIG_TEMPLATE: string;
+
+export declare function ensureUserConfig(home?: string): {
+  created: boolean;
+  path: string;
+};

package/src/install-config.mjs

@@ -0,0 +1,57 @@
+import { closeSync, constants, mkdirSync, openSync, writeSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const CONFIG_TEMPLATE = `# Cadence research configuration. Keep this file local and never commit it.
+# Context7 works anonymously with its default URL.
+# CONTEXT7_API_URL=https://context7.com/api/v2
+# CONTEXT7_API_KEY=
+
+# Required when using the Grok search skill.
+GROK_API_URL=https://api.x.ai/v1
+GROK_API_KEY=
+
+# Optional Tavily integration.
+# TAVILY_ENABLED=true
+# TAVILY_API_URL=https://api.tavily.com
+# TAVILY_API_KEY=
+`;
+
+export function ensureUserConfig(home = homedir()) {
+  const directory = path.join(home, ".pi", "agent", "cadence");
+  const file = path.join(directory, ".env");
+  mkdirSync(directory, { recursive: true, mode: 0o700 });
+  try {
+    const fd = openSync(
+      file,
+      constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL,
+      0o600,
+    );
+    try {
+      writeSync(fd, CONFIG_TEMPLATE, undefined, "utf8");
+    } finally {
+      closeSync(fd);
+    }
+    return { created: true, path: file };
+  } catch (error) {
+    if (error?.code === "EEXIST") return { created: false, path: file };
+    throw error;
+  }
+}
+
+if (
+  process.argv[1] &&
+  path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url))
+) {
+  try {
+    const result = ensureUserConfig();
+    if (result.created)
+      process.stderr.write(`Cadence created ${result.path}\n`);
+  } catch (error) {
+    process.stderr.write(
+      `Cadence could not create the user configuration template: ${error instanceof Error ? error.message : String(error)}\n`,
+    );
+    process.exitCode = 0;
+  }
+}

package/src/startup-card.ts

@@ -0,0 +1,84 @@
+import path from "node:path";
+import {
+  loadConfig,
+  selectConfigPath,
+} from "../skills/_shared/load-config.mjs";
+
+export const STARTUP_CARD_KEY = "cadence-configuration";
+
+// Only code-owned labels and paths enter the UI; never values, endpoints,
+// models, parser errors or credentials from the configuration file.
+function displayPath(value: string): string {
+  return JSON.stringify(value).slice(1, -1);
+}
+
+function validUrl(value: string): boolean {
+  try {
+    const url = new URL(value);
+    return url.protocol === "https:" || url.protocol === "http:";
+  } catch {
+    return false;
+  }
+}
+
+export function startupCardLines(options: {
+  cwd: string;
+  home: string;
+  projectTrusted: boolean;
+}): string[] {
+  const lines = ["Cadence · 研究能力（仅本地配置检查，未联网验证）"];
+  if (!options.projectTrusted) {
+    return [
+      ...lines,
+      "尚未信任当前项目：未读取研究配置；信任项目后重新加载可查看状态。",
+      "不自动启动 Abel 工作流；请勿在聊天中发送 API Key。",
+    ];
+  }
+
+  let selectedPath: string | null = null;
+  try {
+    selectedPath = selectConfigPath(options);
+    const { values } = loadConfig({ ...options, allowMissing: true });
+    const context7 = !validUrl(
+      values.CONTEXT7_API_URL || "https://context7.com/api/v2",
+    )
+      ? "CONTEXT7_API_URL 格式无效"
+      : values.CONTEXT7_API_KEY
+        ? "已配置密钥"
+        : "匿名模式，无需密钥";
+    const missing = ["GROK_API_URL", "GROK_API_KEY"].filter(
+      (name) => !values[name],
+    );
+    const grok = missing.length
+      ? `待配置 ${missing.join("、")}`
+      : !validUrl(values.GROK_API_URL)
+        ? "GROK_API_URL 格式无效"
+        : "已配置";
+    const tavily =
+      values.TAVILY_ENABLED === "false"
+        ? "已关闭"
+        : !values.TAVILY_API_KEY
+          ? "未配置（可选）"
+          : !validUrl(values.TAVILY_API_URL || "https://api.tavily.com")
+            ? "TAVILY_API_URL 格式无效"
+            : "已配置（Grok Skill 仍需 Grok 配置）";
+    lines.push(
+      `文档查询 Context7：${context7}`,
+      `联网搜索 Grok：${grok}；Tavily：${tavily}`,
+    );
+  } catch {
+    lines.push("研究配置无法读取或解析：请检查下方文件；未回退到其他配置。");
+  }
+
+  const userPath = path.join(options.home, ".pi", "agent", "cadence", ".env");
+  const projectPath = path.join(options.cwd, ".pi", "cadence", ".env");
+  lines.push(
+    selectedPath
+      ? `生效文件：${displayPath(selectedPath)}${selectedPath === projectPath ? "（项目整文件优先，不合并用户配置）" : "（用户级，跨项目复用）"}`
+      : `配置位置：${displayPath(userPath)}（用户级，跨项目复用）`,
+    "在本地编辑该文件：GROK_API_URL=<服务地址>、GROK_API_KEY=<密钥>，每项一行；可选 TAVILY_API_KEY。",
+    "研究 Skills 不读取 shell API 变量；保存后下次调用生效。不要把密钥发到聊天或提交到 Git。",
+    "可选服务未配置不阻塞普通任务，也不自动启动 Abel 工作流。",
+  );
+  return lines;
+}