@istuen/pt 0.1.0

package/src/injection-status.ts

@@ -0,0 +1,155 @@
+// src/injection-status.ts — pt 注入状态检测（纯函数内核）
+//
+// 配套 .pt/docs/designs/pt-injection-status-manual-track.md §2.3：
+//   - footer 文本由 InjectionState × profile 决定
+//   - 自报（PiAdapter before_agent_start 三分支写 session.injectionState）
+//   - 不依赖 ExtensionAPI，可单测
+//
+// 边界纪律：
+//   - 不检测 Pi 的 system prompt——自报更准（ctx.getSystemPrompt() 不含注入后内容）
+//   - 不存进度——进度从 manual 实例文件 parse（见 manual-track.ts）
+//
+// v14.x（issue pt-asset-migration-visibility Layer 2 修复）：
+//   - renderInjectionFooter 加 healthIssueCount 参数 → footer 末尾追加 "⚠ N issue(s)"
+//   - useColor() 检测 TTY → TUI 用 ANSI 颜色（状态染色），web 用纯文本 + ⚠ 前缀
+//   - pi 的 ui.setStatus 不支持 level 参数，ANSI 烧在 text 字段里
+//   - back-compat：healthIssueCount 默认 0，旧 call site 行为不变
+
+import type { InjectionState } from "./session.js";
+
+/** ANSI 转义码集合。烧进 setStatus text 字段，让 TUI 渲染颜色。 */
+const ANSI = {
+  reset: "\x1b[0m",
+  dim: "\x1b[90m",
+  red: "\x1b[31m",
+  yellow: "\x1b[33m",
+  green: "\x1b[32m",
+  bold: "\x1b[1m",
+} as const;
+
+/** TTY 检测：TUI 模式 stdout 是 TTY（颜色可用）；web 模式 stdout 通常被 pipe（颜色退化为乱码）。
+ *  加 isTTY 检查避免 web 下输出 "[31m..." 字面量。 */
+function useColor(): boolean {
+  return process.stdout?.isTTY === true;
+}
+
+/** 把字符串截断到 N 字符（用 Array.from 避免 surrogate pair 切坏 emoji）。
+ *  v14.x（tagline）：footer 超长 tagline 裁短用。 */
+function truncate(s: string, n: number): string {
+  if (s.length <= n) return s;
+  // 防止切到 surrogate pair 中间
+  const arr = Array.from(s);
+  if (arr.length <= n) return s;
+  return `${arr.slice(0, n).join("")}...`;
+}
+
+/** v14.x（tagline）：对 footer tagline 作脱裁 + separator 拼装。
+ *  - 缺省 tagline → 返回 ''（外层拼接到 footer 不变）
+ *  - tagline.length ≤ maxLen → 原样
+ *  - tagline.length > maxLen → 裁到 maxLen - 1 + '…'
+ *  返回 `: <tagline>` 形式（带 separator），便于直拼。
+ *
+ *  maxLen 默认 35（与 health suffix 分享 footer 宽度预算）。
+ */
+export function formatTaglineForFooter(tagline: string | undefined, maxLen: number = 35): string {
+  if (!tagline) return "";
+  const trimmed = tagline.trim();
+  if (!trimmed) return "";
+  if (trimmed.length <= maxLen) return `: ${trimmed}`;
+  // 超长：本地手动截 codepoints + 1-char ellipsis（`…`）— 避开 truncate() 的 `...` 3-char 形态
+  const arr = Array.from(trimmed);
+  if (arr.length <= maxLen) return `: ${trimmed}`;
+  return `: ${arr.slice(0, maxLen - 1).join("")}…`;
+}
+
+/** 颜色模式。
+ *  - "auto"（默认）：根据 process.stdout.isTTY 自动判断（TUI 用颜色，web 不用）
+ *  - "always"：强制开启 ANSI（手动 debug / 调试 输出场景）
+ *  - "never"：  强制关闭 ANSI（CI / pipe / 重定向场景）
+ *
+ *  v14.x（issue pt-asset-migration-visibility Layer 2）：加 colorMode 让测试与 CLI 可覆盖默认 TTY 检测。
+ */
+export type ColorMode = "auto" | "always" | "never";
+
+/** 把 InjectionState × profile × error × healthIssueCount × tagline 渲染为 footer 文本。
+ *
+ *  状态颜色映射：
+ *   - injected  → green
+ *   - pending   → yellow
+ *   - idle      → dim gray
+ *   - failed    → red
+ *
+ *  Health suffix：healthIssueCount > 0 → 末尾追加 ` ⚠ N issue(s)`（emoji 前缀作主视觉信号，颜色补充）
+ *
+ *  Tagline（v14.x）：profile 名后追加 `: <tagline>`（≤35 字符），超长裁短 + …：
+ *   - tagline 缺省 → 不追加（back-compat）
+ *   - tagline 存在且短 → `pt: pt-dev: Senior dev + QA + Reviewer (3 agents) ok`
+ *   - tagline 超长 → 裁到 34 + '…'
+ *
+ *  profile=null → "pt: 无 context"（其它状态必先有 profile，统一降级）
+ *  failed 时追加 ": <error 前 40 字>"
+ *
+ *  TUI / Web 兼容：
+ *   - TUI（isTTY=true）：状态染色 ANSI + ⚠ 后缀（颜色补充）
+ *   - Web（isTTY=false）：纯文本 + ⚠ 前缀（无 ANSI 避免 [31m 字面量）
+ *   - colorMode='always'|'never'：覆盖自动检测（调试 / 测试用）
+ *
+ *  back-compat：healthIssueCount + colorMode + tagline 均有默认值，旧 call site 行为不变。 */
+export function renderInjectionFooter(
+  state: InjectionState,
+  profile: string | null,
+  error: string | null,
+  healthIssueCount: number = 0,
+  colorMode: ColorMode = "auto",
+  tagline: string | null = null
+): string {
+  if (profile === null) {
+    return "pt: 无 context";
+  }
+  // 1. 状态后缀（failed 追加 error，injected 用 "ok"，其它用 state 名）
+  //    failed + null error 仍拼 `: unknown`（与 v13 旧版兼容——存在不传 error 的旧 call site）
+  let stateSuffix: string;
+  if (state === "failed") {
+    const errText = error ? truncate(error, 40) : "unknown";
+    stateSuffix = ` failed: ${errText}`;
+  } else if (state === "injected") {
+    stateSuffix = " ok";
+  } else {
+    stateSuffix = ` ${state}`;
+  }
+
+  // 2. Health suffix：⚠ 前缀作主视觉信号（即便无 ANSI 也能看到）
+  //    - 0 issue → 不显示
+  //    - 1 issue → " ⚠ 1 issue"
+  //    - N issue → " ⚠ N issues"
+  const healthSuffix =
+    healthIssueCount > 0 ? ` ⚠ ${healthIssueCount} issue${healthIssueCount > 1 ? "s" : ""}` : "";
+
+  // 3. v14.x tagline：profile 名后拼 `: <tagline-truncated>`（≤35 字符）
+  //    无 tagline 时返空串 → 不影响 back-compat
+  const taglineSuffix = formatTaglineForFooter(tagline ?? undefined);
+
+  const baseText = `pt: ${profile}${taglineSuffix}${stateSuffix}${healthSuffix}`;
+
+  // 4. 颜色决策：colorMode 覆盖 TTY 默认检测
+  const colorEnabled = colorMode === "always" ? true : colorMode === "never" ? false : useColor();
+  if (!colorEnabled) return baseText;
+
+  const colorByState: Record<InjectionState, string> = {
+    injected: ANSI.green,
+    pending: ANSI.yellow,
+    idle: ANSI.dim,
+    failed: ANSI.red,
+  };
+  // health issue 染色优先于 state 颜色（视觉上"严重"更突出）
+  if (healthIssueCount > 0) {
+    return `${ANSI.red}${ANSI.bold}⚠ ${baseText.replace(/^pt: /, "pt: ")}${ANSI.reset}`;
+  }
+  return `${colorByState[state]}${baseText}${ANSI.reset}`;
+}
+
+/** 把 ANSI 颜色码剥成纯文本（test 工具——便于断言内容而忽略颜色）。 */
+export function stripAnsi(text: string): string {
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: ANSI CSI 序列故意用 ESC 控制符
+  return text.replace(/\x1b\[[0-9;]*m/g, "");
+}

package/src/log.ts

@@ -0,0 +1,173 @@
+// src/log.ts — Pt 持久化日志（NDJSON, append-only, 串行写链）
+//
+// 设计原则：
+// - 零运行时依赖：只用 node:fs/promises + node:path，std lib 搞定
+// - 异步串行链 (writeChain) 保证写入顺序，避免 race condition
+// - 文件路径：<cwd>/.pt/logs/pt.log（NDJSON 行式 JSON, 崩溃时只丢一行）
+// - 失败静默：日志写盘错误不影响主流程（仅 console.error 保留可见性）
+// - 不做自动 rotate：rollover 留作外部脚本 / 手工处理（Pt 转译是低频事件）
+//
+// 技术债 Tech Debt T-new: 与 pt-quality #9（error-via-notify）配套——
+//   notify 走 UI 瞬时反馈，log 走磁盘持久 trace，两者互补。
+
+import { appendFile, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+/** 日志根目录（项目根下，git 排除）。 */
+export const LOG_DIR = ".pt/logs";
+
+/** 主日志文件名（单文件 append）。 */
+export const LOG_FILE = "pt.log";
+
+/** Pt 支持的日志级别（与 ctx.ui.notify 的 level 集合兼容 + debug）。 */
+export type PtLogLevel = "debug" | "info" | "warning" | "error";
+
+/** 单条日志记录（NDJSON 行）。 */
+export interface PtLogEntry {
+  /** ISO 时间戳（毫秒精度） */
+  ts: string;
+  /** 日志级别 */
+  level: PtLogLevel;
+  /** 人类可读消息（与 notify msg 一致或更细） */
+  msg: string;
+  /** 结构化上下文（cwd / profile / 关联数据）。SourceAdapterContext 里 log api 走 unknown 留扩展位 */
+  ctx?: Record<string, unknown>;
+}
+
+/** 给 SourceAdapterContext.log 用的接口（不带 baseCtx，logger 内部注入）。
+ *  v10.x 设计：log 接口不暴露 file path, 仅暴露级别方法 → 适配器层无法绕过 logger 写文件。 */
+export interface PtLoggerWriter {
+  debug(msg: string, ctx?: Record<string, unknown>): void;
+  info(msg: string, ctx?: Record<string, unknown>): void;
+  warn(msg: string, ctx?: Record<string, unknown>): void;
+  error(msg: string, ctx?: Record<string, unknown>): void;
+}
+
+/** PtLogger：per-session 单例（由 SessionState.logger 持有，避免跨 session 串台）。
+ *
+ *  v10.x：构造时传入 sessionId → 多并发 `pi` 进程的日志文件分离：
+ *    - 主文件：`pt-<sessionId>.log`
+ *    - 反查：ctx.sessionId 字段注入每条 entry
+ *
+ *  使用方式（index.ts session_start）：
+ *    session.sessionId = randomUUID().slice(0, 8);
+ *    session.logger = new PtLogger(cwd, "", session.sessionId);
+ */
+export class PtLogger implements PtLoggerWriter {
+  private writeChain: Promise<void> = Promise.resolve();
+  private readonly baseCtx: Record<string, unknown>;
+
+  constructor(
+    public readonly cwd: string,
+    public readonly profile: string = "",
+    public readonly sessionId: string = ""
+  ) {
+    this.baseCtx = { cwd, profile, sessionId };
+  }
+
+  /** 当前 session 的日志文件路径：`pt-<sessionId>.log`。
+   *  sessionId 为空时 fallback 为 `pt.log`（兼容未走 session_start 的旧调用）。 */
+  get filePath(): string {
+    const name = this.sessionId ? `pt-${this.sessionId}.log` : LOG_FILE;
+    return join(this.cwd, LOG_DIR, name);
+  }
+
+  /** 给 SourceAdapterContext.log 用的适配对象（绑定 baseCtx 的 writer）。 */
+  toWriter(): PtLoggerWriter {
+    return {
+      debug: (m, c) => this.debug(m, c),
+      info: (m, c) => this.info(m, c),
+      warn: (m, c) => this.warn(m, c),
+      error: (m, c) => this.error(m, c),
+    };
+  }
+
+  /** 内部：链式串行 + 静默失败（写盘错误不传染到链上下一步）。 */
+  private write(level: PtLogLevel, msg: string, ctx?: Record<string, unknown>): void {
+    const entry: PtLogEntry = {
+      ts: new Date().toISOString(),
+      level,
+      msg,
+      ctx: { ...this.baseCtx, ...ctx },
+    };
+    this.writeChain = this.writeChain
+      .then(async () => {
+        try {
+          await mkdir(join(this.cwd, LOG_DIR), { recursive: true });
+          await appendFile(this.filePath, `${JSON.stringify(entry)}\n`, "utf8");
+        } catch (e) {
+          console.error("[pt-log] write failed:", e instanceof Error ? e.message : e);
+        }
+      })
+      .catch(() => {
+        /* 链上一步失败不传染到下一步 */
+      });
+  }
+
+  debug(msg: string, ctx?: Record<string, unknown>): void {
+    this.write("debug", msg, ctx);
+  }
+
+  info(msg: string, ctx?: Record<string, unknown>): void {
+    this.write("info", msg, ctx);
+  }
+
+  warn(msg: string, ctx?: Record<string, unknown>): void {
+    this.write("warning", msg, ctx);
+  }
+
+  error(msg: string, ctx?: Record<string, unknown>): void {
+    this.write("error", msg, ctx);
+  }
+
+  /** 等待在飞写入全部落地（session_shutdown 时调，避免丢尾）。 */
+  async flush(): Promise<void> {
+    await this.writeChain.catch(() => {});
+  }
+
+  /** /pt logs 命令支持：从磁盘读最近 N 条（按文件顺序，NDJSON 逐行解析）。
+   *  v10.x：默认从 `pt.log`（无 sessionId）读——兼容旧文件；如想读 session 文件，传 sessionId。 */
+  static async tail(cwd: string, n = 50, sessionId?: string): Promise<PtLogEntry[]> {
+    const file = sessionId
+      ? join(cwd, LOG_DIR, `pt-${sessionId}.log`)
+      : join(cwd, LOG_DIR, LOG_FILE);
+    let raw: string;
+    try {
+      raw = await readFile(file, "utf8");
+    } catch {
+      return []; // 文件不存在 → 返空（首次启动）
+    }
+    const lines = raw.trim().split("\n");
+    const slice = lines.slice(-n);
+    const out: PtLogEntry[] = [];
+    for (const line of slice) {
+      try {
+        out.push(JSON.parse(line) as PtLogEntry);
+      } catch {
+        /* 跳过损坏行（半行 / 篡改） */
+      }
+    }
+    return out;
+  }
+
+  /** /pt logs clear 命令。清空日志文件（保留目录）。
+   *  v10.x：清单一文件（默认 `pt.log` 或 sessionId 指定）。 */
+  static async clear(cwd: string, sessionId?: string): Promise<void> {
+    const dir = join(cwd, LOG_DIR);
+    await mkdir(dir, { recursive: true });
+    const file = sessionId ? join(dir, `pt-${sessionId}.log`) : join(dir, LOG_FILE);
+    await writeFile(file, "", "utf8");
+  }
+
+  /** /pt logs 命令支持：枚举所有日志文件（多 session 时列出全部）。 */
+  static async list(cwd: string): Promise<string[]> {
+    const dir = join(cwd, LOG_DIR);
+    let entries: string[];
+    try {
+      entries = await readdir(dir);
+    } catch {
+      return [];
+    }
+    return entries.filter((f) => f.startsWith("pt-") && f.endsWith(".log")).sort();
+  }
+}

package/src/manual-session.ts

@@ -0,0 +1,190 @@
+// src/manual-session.ts — manual 跟踪的 session/JSONL/widget 交互层
+//
+// v11.x：从 src/index.ts 抽出的 6 个函数 + 模块级缓存 + 常量。
+//
+// 职责分层（vs 已抽出的 manual-track.ts）：
+//   - manual-track.ts：纯函数渲染（renderManualFooterSuffix / renderManualWidgetLines / isManualActive / parseManualProgress）
+//   - manual-session.ts：session JSONL 读写 + widget/footer 交互 + ActiveManual 状态机
+//
+// v12.x（issue pt-session-singleton-pi-web-pollution 修复）：
+//   - 函数全部接受 `session: SessionState` 参数，调用方传 per-session state
+//   - `cachedManualProgress` 从 module-level let 搬到 SessionState 字段（session.cachedManualProgress）
+//   - 不再 import module-level `session` 单例
+//
+// 调用方：src/index.ts session_start / session_shutdown / 命令 + tool
+//
+// 依赖梳理：
+//   - Pi 类型：ExtensionAPI / ExtensionContext / ExtensionUIContext / AgentUIContext
+//   - session 单例 → SessionState 参数
+//   - manual-track 纯函数：parseManualProgress / renderManualWidgetLines / renderManualFooterSuffix / isManualActive / ManualProgress
+//   - injection-status：renderInjectionFooter
+//   - profile-persist：MinimalSessionManager
+//   - slog：slog（session-scoped logger 快捷）
+//   - diagnostics：errMsg
+
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+  ExtensionUIContext,
+} from "@earendil-works/pi-coding-agent";
+import {
+  isManualActive,
+  parseManualProgress,
+  renderManualFooterSuffix,
+  renderManualWidgetLines,
+} from "./manual-track.js";
+import { renderInjectionFooter } from "./injection-status.js";
+import type { MinimalSessionManager } from "./profile-persist.js";
+import { errMsg } from "./diagnostics.js";
+import { slog } from "./slog.js";
+import type { ActiveManual, SessionState } from "./session.js";
+
+/** session JSONL 中持久化 ActiveManual 的 custom entry customType。 */
+const PT_MANUAL_ENTRY = "pt:active-manual";
+
+/** 从 session JSONL 读上次保存的 ActiveManual。读出后由 caller 校验（isManualActive）。
+ *  静默 fallback：异常 / 无 entry → undefined。 */
+interface PersistedManualEntry {
+  filePath: string;
+  procedure: string;
+  args: string;
+}
+function readManualFromSession(
+  sessionManager: MinimalSessionManager
+): PersistedManualEntry | undefined {
+  try {
+    const entries = sessionManager.getEntries();
+    for (let i = entries.length - 1; i >= 0; i--) {
+      const e = entries[i];
+      if (e && e.type === "custom" && e.customType === PT_MANUAL_ENTRY) {
+        const data = (e as { data?: unknown }).data;
+        if (data && typeof data === "object") {
+          const d = data as Record<string, unknown>;
+          const filePath = d.filePath;
+          const procedure = d.procedure;
+          const args = d.args;
+          if (typeof filePath === "string" && filePath.trim() && typeof procedure === "string") {
+            return {
+              filePath: filePath.trim(),
+              procedure,
+              args: typeof args === "string" ? args : "",
+            };
+          }
+        }
+      }
+    }
+  } catch {}
+  return undefined;
+}
+
+/** 把当前 ActiveManual 写入 session JSONL。
+ *  失败静默（ephemeral session / 旧版 pi 无 appendEntry）——内存中 activeManual 仍可用本进程。 */
+function persistManualToSession(pi: ExtensionAPI, m: ActiveManual): void {
+  try {
+    if (typeof pi.appendEntry !== "function") return;
+    pi.appendEntry(PT_MANUAL_ENTRY, {
+      filePath: m.filePath,
+      procedure: m.procedure,
+      args: m.args,
+    });
+  } catch (e) {
+    slog("", "warn", "persistManualToSession failed", { procedure: m.procedure, err: errMsg(e) });
+  }
+}
+
+/** 计算 active manual 的 footer 后缀（空字符串 = 无 activeManual 或 completed）。 */
+function renderActiveManualSuffix(session: SessionState): string {
+  if (!session.activeManual) return "";
+  // 同步快速读（无 IO）—— widget 刷新会走 async parseManualProgress
+  // footer 只显示 procedure 名 + done/total，避免 IO 阻塞 setStatus
+  // 但 stepDone/total 是派生数据，需要同步可读——
+  // 这里走同步取缓存策略：保留 widget 异步 parse 的最新结果
+  if (!session.cachedManualProgress) return "";
+  return renderManualFooterSuffix(session.cachedManualProgress);
+}
+
+/** 刷新 footer 注入状态 + manual 后缀（合并写一次 setStatus）。
+ *  v14.x（issue pt-asset-migration-visibility Layer 2）：assetHealthIssues.length 透传给
+ *  renderInjectionFooter → footer 末尾追加 ⚠ N issues（染色）。
+ *  v14.x（tagline）：从 cachedProfile.tagline 读，footer 拼 `: <tagline>`。 */
+function refreshInjectionFooter(ui: ExtensionUIContext, session: SessionState): void {
+  const suffix = renderActiveManualSuffix(session);
+  const healthCount = session.assetHealthIssues?.length ?? 0;
+  const tagline = session.cachedProfile?.tagline ?? null;
+  const base = renderInjectionFooter(
+    session.injectionState,
+    session.activeProfile,
+    session.injectionError,
+    healthCount,
+    "auto",
+    tagline
+  );
+  ui.setStatus("pt", suffix ? `${base} ${suffix}` : base);
+}
+
+/** 刷新 widget（aboveEditor）。根据 session.activeManual 决定显示/撤掉。
+ *  - 无 activeManual → 撤 widget
+ *  - 文件不存在 / 已 completed → 清 activeManual + 撤 widget
+ *  - in-progress → 渲染 3 行 widget + 更新 cachedManualProgress（footer 同步读）
+ *  v12.x：state 全部从 session 参数读，不再读写 module-level 单例。 */
+async function refreshManualWidget(ui: ExtensionUIContext, session: SessionState): Promise<void> {
+  const m = session.activeManual;
+  if (!m) {
+    session.cachedManualProgress = null;
+    ui.setWidget("pt-manual", undefined);
+    return;
+  }
+  const p = await parseManualProgress(m.filePath);
+  if (!p || p.status === "completed") {
+    session.activeManual = null;
+    session.cachedManualProgress = null;
+    ui.setWidget("pt-manual", undefined);
+    return;
+  }
+  session.cachedManualProgress = p;
+  ui.setWidget("pt-manual", renderManualWidgetLines(m.filePath, p), {
+    placement: "aboveEditor",
+  });
+}
+
+/** session_start 时试恢复 manual：读 pt:active-manual entry → 校验文件存在 + status !== completed。
+ *  独立于 profile 加载链——profile 失败 / 无 profile 也能恢复 manual 追踪。 */
+async function tryRestoreManual(ctx: ExtensionContext, session: SessionState): Promise<void> {
+  const entry = readManualFromSession(ctx.sessionManager);
+  if (!entry) return;
+  const active = await isManualActive(entry.filePath);
+  if (!active) {
+    session.logger?.debug("manual:restore skipped (inactive)", {
+      filePath: entry.filePath,
+    });
+    return;
+  }
+  session.activeManual = {
+    filePath: entry.filePath,
+    procedure: entry.procedure,
+    args: entry.args,
+    activatedAt: Date.now(),
+  };
+  await refreshManualWidget(ctx.ui, session);
+  // widget 设置后才调 footer（refreshManualWidget 写 cachedManualProgress）
+  refreshInjectionFooter(ctx.ui, session);
+  session.logger?.info("manual:restored", {
+    filePath: entry.filePath,
+    procedure: entry.procedure,
+  });
+}
+
+/** 重置 module-level 缓存（session_shutdown 时调，避免新 session 残留旧 manual 状态）。
+ *  v12.x：改 no-op——cachedManualProgress / activeManual 都搬到 SessionState，
+ *  session_shutdown 时由 `clearSessionById(sessionId)` 整体删除 entry 即可。 */
+function resetManualSession(_session: SessionState): void {
+  // no-op: state 已在 session_shutdown 时通过 clearSessionById 删除
+}
+
+export {
+  persistManualToSession,
+  refreshInjectionFooter,
+  refreshManualWidget,
+  resetManualSession,
+  tryRestoreManual,
+};

package/src/manual-track.ts

@@ -0,0 +1,127 @@
+// src/manual-track.ts — pt Manual 实例追踪（纯函数内核）
+//
+// 配套 .pt/docs/designs/pt-injection-status-manual-track.md §2.4 / §2.5：
+//   - parseManualProgress：读文件 → 抽 frontmatter → 正则数 checklist
+//   - renderManualWidgetLines：3 行 string[] 给 setWidget 用
+//   - renderManualFooterSuffix：footer 后缀（"· manual: <procedure> 3/6"）
+//   - isManualActive：文件存在 + status !== completed
+//
+// 边界纪律：
+//   - manual 实例文件不是 Pt 资产（不是 Domain/Blueprint/Profile）→ 不进 parse/ 层
+//   - 进度（stepDone/stepTotal）不存 session——文件是 single source of truth
+//   - 不依赖 ExtensionAPI，可单测
+
+import { access, readFile } from "node:fs/promises";
+
+/** Manual 实例文件 parse 结果。
+ *  - procedure：从 frontmatter.procedure 取
+ *  - stepDone / stepTotal：实时正则数 "- [x]" / "- [ ]"
+ *  - status：frontmatter.status（in-progress / completed）
+ *  - nextStep：第一个 "- [ ]" 行去前缀的文本（下一步该做的），无则 null */
+export interface ManualProgress {
+  procedure: string;
+  stepDone: number;
+  stepTotal: number;
+  status: string;
+  nextStep: string | null;
+}
+
+/** 从 manual 实例文件 parse 进度。失败返回 null（容错，不抛）。 */
+export async function parseManualProgress(filePath: string): Promise<ManualProgress | null> {
+  try {
+    const content = await readFile(filePath, "utf8");
+    return parseManualProgressFromContent(content);
+  } catch {
+    // 文件不存在 / 权限不足 / 读取失败
+    return null;
+  }
+}
+
+/** 内部：从字符串内容 parse（便于单测 & 未来内联输入）。
+ *  算法：
+ *   1. frontmatter：取首段 `---` ... `---` 之间的 YAML
+ *   2. procedure / status：从 frontmatter 行解析（`key: value` 形式，宽松）
+ *   3. checklist：全文正则 `/^- \[([ x])\]\s+(.+)$/gm` 数 done / total
+ *   4. nextStep：第一个未完成项的文本（去前缀） */
+export function parseManualProgressFromContent(content: string): ManualProgress | null {
+  const fm = extractFrontmatter(content);
+  const procedure = fm?.procedure ?? "(unknown)";
+  const status = fm?.status ?? "unknown";
+
+  let stepDone = 0;
+  let stepTotal = 0;
+  let nextStep: string | null = null;
+  // 多行匹配（m 标志），匹配行首 "- [x]" 或 "- [ ]"
+  const re = /^- \[([ x])\]\s+(.+)$/gm;
+  for (const m of content.matchAll(re)) {
+    const checked = m[1] === "x";
+    const text = m[2]?.trim() ?? "";
+    stepTotal++;
+    if (checked) {
+      stepDone++;
+    } else if (nextStep === null && text) {
+      nextStep = text;
+    }
+  }
+
+  return { procedure, stepDone, stepTotal, status, nextStep };
+}
+
+/** frontmatter 抽取（极简 YAML：只解 key: value）。 */
+interface SimpleFrontmatter {
+  procedure?: string;
+  status?: string;
+}
+function extractFrontmatter(content: string): SimpleFrontmatter | null {
+  const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+  if (!m?.[1]) return null;
+  const out: SimpleFrontmatter = {};
+  for (const line of m[1].split(/\r?\n/)) {
+    const kv = line.match(/^([a-zA-Z_-]+)\s*:\s*(.*)$/);
+    if (!kv?.[1]) continue;
+    const key = kv[1];
+    const value = (kv[2] ?? "").trim();
+    if (key === "procedure") out.procedure = value;
+    else if (key === "status") out.status = value;
+  }
+  return out;
+}
+
+/** widget 渲染：3 行 string[]，给 `ui.setWidget("pt-manual", lines, { placement: "aboveEditor" })` 用。
+ *  - 第 1 行：`pt ▶ <procedure>  step <done>/<total>  (<status>)`（completed 加 ` ✓ done`）
+ *  - 第 2 行：`  next: <nextStep 文本>`（无 nextStep 时该行省略）
+ *  - 第 3 行：`  file: <filePath>`
+ *  status === completed 时仍显示，但 footer 后缀改 done；widget 撤掉由 caller 决定（见 index.ts refreshManualWidget）。 */
+export function renderManualWidgetLines(filePath: string, p: ManualProgress): string[] {
+  const statusText = p.status === "completed" ? "✓ done" : `(${p.status})`;
+  const lines: string[] = [];
+  lines.push(`pt ▶ ${p.procedure}  step ${p.stepDone}/${p.stepTotal}  ${statusText}`);
+  if (p.nextStep && p.status !== "completed") {
+    lines.push(`  next: ${p.nextStep}`);
+  }
+  lines.push(`  file: ${filePath}`);
+  return lines;
+}
+
+/** footer 后缀：有 activeManual 时追加。
+ *  - in-progress → `· manual: <procedure> <done>/<total>`
+ *  - completed   → `· manual: <procedure> done` */
+export function renderManualFooterSuffix(p: ManualProgress): string {
+  if (p.status === "completed") {
+    return `· manual: ${p.procedure} done`;
+  }
+  return `· manual: ${p.procedure} ${p.stepDone}/${p.stepTotal}`;
+}
+
+/** 文件存在 + status !== completed。配合 widget/footer 决定要不要展示。
+ *  - 用 fs.access 探测存在（轻量，不读全文）
+ *  - 真的 parse status 用 parseManualProgress（一次 readFile 取齐） */
+export async function isManualActive(filePath: string): Promise<boolean> {
+  try {
+    await access(filePath);
+  } catch {
+    return false;
+  }
+  const p = await parseManualProgress(filePath);
+  return p !== null && p.status !== "completed";
+}