paseo-req-kit 1.13.0 → 1.14.0-beta.1

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 每个版本分为"使用者会看到的变化"和"升级须知"。升级步骤见 [docs/guide/安装与升级.md](docs/guide/安装与升级.md)。
 
+## 1.14.0-beta.1
+
+### 使用者会看到的变化
+
+- **修复：自动新建工作区后只有需求说明、没有代码。** 以前新建工作区只等 2 分钟，超时（大仓库在 Windows 上常见）或建好后启动前的检查没通过，启动命令就退出了，留下一个只有需求说明提交的分支；再启动又报"分支已存在"。现在工作区一建好就记下来，再次启动会在这个工作区里接着开始；最多等 15 分钟。以前版本留下的这种工作区，也会由 Paseo 接手接着做。
+- **访谈改过的术语表（`GLOSSARY.md`）和设计决定（`docs/adr/`）随需求说明一起带到新工作区**，在需求自己的分支上提交。
+- **修复：需求说明可能被提交到主分支。** 写需求说明的说明和"新需求"手册对是否提交说法不一致，现在统一为：要自动新建工作区的，确认后不提交，由流水线在新工作区里提交。需求说明已经提交在主分支上、本地主分支比远端落后、主目录还有别的未提交改动时，启动结果里会写明。
+- **需求从开始谈就出现在插件里**（"对齐中"）：建好功能目录后 `/req` 会登记它（`start-pipeline --feature <功能目录> --track`）；没登记的，插件也会在本机用过的项目里找到。
+- **确认了却没开始开发的需求进"等你处理"**：需求说明确认超过 30 分钟还没开始，或者上次启动没成功，插件里显示"还没开始开发"，点"开始开发"即可：在项目主目录中会新建（或接着用）需求自己的工作区，进展发回谈需求的那个对话。
+
+### 升级须知
+
+- `req api list --all` 也会列出对齐中的需求（没有运行状态）；`attention` 新增 `not_started`，`waiting` 新增 `canStart`；`req api run` 新增 `start`；需求索引新增可选的 `chatAgentId`；新增 `~/.req-kit/worktrees/` 记录。
+- 更新后请在 Paseo 中重新加载插件（`req upgrade` 会自动做）。
+
 ## 1.13.0
 
 稳定版：内网能装能用、在 Paseo 网页端审查原型、不靠看图检查界面、看得见 token 花在哪。内容包括 1.13.0-beta.1 至 beta.5（详见下面各条）和下面新增的三项，设计决定见 ADR 0032、0033。

package/contracts/cli-json.md

@@ -22,12 +22,12 @@
 | --- | --- |
 | `req api version` | `{ kitVersion, kitRoot, apiSchema, paseo, featuresDir }`：`paseo` 是这个版本支持的 Paseo 范围 |
 | `req api list [--repo <目录>]` | 这个仓库所有工作区中的需求，数组，每项见下面的"需求" |
-| `req api list --all` | 本机记录过的所有需求（[需求索引](usage-record.md)），同上；目录已不在的 `present: false` |
+| `req api list --all` | 本机记录过的所有需求（[需求索引](usage-record.md)），同上；目录已不在的 `present: false`。1.14 起还包括：用 `--track` 登记、还在对齐中的需求（`stage` 为"对齐中"，没有 `spec.md` 时 `title` 取自 `alignment.md`），以及索引里出现过的项目中没登记的需求 |
 | `req api status <需求> [--repo <目录>]` | 一个需求的详情，见下面的"详情" |
 | `req api file <需求> <文件> [--repo <目录>]` | `{ featureDir, file, size, truncated, content }`；只能读取功能目录中的文档（见下），最多 512 KB |
 | `req api stats [--since 30d] [--month 2026-10]` | `req stats --json` 的内容，见 [使用记录](usage-record.md) |
 | `req api index [--rebuild <目录>…] [--prune]` | 不带选项：索引的全部条目；`--rebuild`：`{ scanned, registered, pruned, total }` |
-| `req api run <approve\|stop\|resume\|verify\|sync\|reply> <需求> [--repo <目录>] [选项]` | `{ command, featureDir, ok, exitCode, message }`。在 `--repo`（默认当前目录）中执行与 `req <命令> <需求>` 完全相同的操作；`ok` 为 false 时退出码为 1 |
+| `req api run <approve\|stop\|resume\|verify\|sync\|reply\|start> <需求> [--repo <目录>] [选项]` | `{ command, featureDir, ok, exitCode, message }`。在 `--repo`（默认当前目录）中执行与 `req <命令> <需求>` 完全相同的操作；`ok` 为 false 时退出码为 1。`start`（1.14）：在项目主目录中自动加 `--worktree`（上次已建好工作区的接着用），并把进展发回登记时的对话 |
 | `req api models` | 1.12 起。`{ current, choices, recommended }`：本机配置中现在的 `agents`；daemon 上能无人值守运行的选择（`{ id, label, provider, profile }`，Paseo profile 在前）；按推荐的 `agents`。连不上 daemon 时报错 |
 | `req api config [--repo <目录>] [--machine]` | 1.12 起。`{ sources, ignored, error, repo, groups }`：`sources` 是生效的配置文件（`layer` 为 `machine` / `team` / `project`，按叠加顺序）；`groups` 按主题分组，每项 `{ key, label, description, display, value, setBy, scope, changed }`：`display` 是用大白话写的值，`value` 中看起来像密钥的值和个人账号替换为 `••••`，`setBy` 是写了它的文件，`changed` 表示与默认值不同。配置有错误时 `error` 写明原因，值按各文件所写。`--machine` 不看项目配置 |
 | `req api set-agents --json <设置>` | 1.12 起。`{ ok, message }`。`<设置>` 是 `{ builder, reviewer, fallback }`（`fallback` 可以为 null），检查后写入本机配置的 `agents`，原文件备份 |
@@ -52,8 +52,8 @@
 | `status` | 状态文件的 `status`；还没运行过为 null |
 | `running` | 后台进程是否在运行 |
 | `phase` | `develop` / `verify` |
-| `attention` | 需要人处理的事：`approval`（确认方案）、`business`（需求方决定）、`permission`（1.13，步骤在等权限批准；`waiting.questions` 是要批准的操作，`waiting.agentId` 是那个 agent）、`interrupted`（中断，可以继续）、`not_completed`（结束但未完成）；没有为 null |
-| `waiting` | 1.12 起。`attention` 不为 null 时：`since`（从什么时候开始等）、`questions`（需求方要回答的问题）、`reason`（停止原因）、`card`（`{ system, id, url, requester }`，从卡片开始的需求）、`canReply`（能否用 `req api run reply <需求> <回复>` 把回复转给需求的对话）；否则为 null |
+| `attention` | 需要人处理的事：`approval`（确认方案）、`business`（需求方决定）、`permission`（1.13，步骤在等权限批准；`waiting.questions` 是要批准的操作，`waiting.agentId` 是那个 agent）、`interrupted`（中断，可以继续）、`not_completed`（结束但未完成）、`not_started`（1.14，需求说明已确认超过 30 分钟、或已为它建好工作区，但流水线没有运行过）；没有为 null |
+| `waiting` | 1.12 起。`attention` 不为 null 时：`since`（从什么时候开始等）、`questions`（需求方要回答的问题）、`reason`（停止原因）、`card`（`{ system, id, url, requester }`，从卡片开始的需求）、`canReply`（能否用 `req api run reply <需求> <回复>` 把回复转给需求的对话）、`canStart`（1.14，`not_started` 时为 true：可以用 `req api run start <需求>` 开始开发）；否则为 null |
 | `current` | 正在运行的步骤 `[{ key, title, agentId }]` |
 | `updatedAt` | 最近一次变化的时间 |
 | `usage` | `{ steps, agentMinutes, inputTokens, outputTokens, costUsd }`；没运行过为 null |

package/contracts/usage-record.md

@@ -19,7 +19,11 @@
 }
 ```
 
-`key` 由对话所在的目录（没有自己的工作区时即 `repo`）和功能目录算出。`req index --rebuild` 为 1.9 之前运行过的需求补登，`req index --prune` 移除目录已不在的。
+`key` 由对话所在的目录（没有自己的工作区时即 `repo`）和功能目录算出。1.14 起：开始谈需求时（`start-pipeline --feature <功能目录> --track`）就登记，此时多一个可选字段 `chatAgentId`（谈需求的对话），之后的登记保留它；新建需求自己的工作区时，条目改为指向那个工作区。目录里有 `spec.md`、`alignment.md` 或 `.pipeline/` 下的状态或登记标记时算作存在。
+
+## 新建工作区的记录 `worktrees/<key>.json`（1.14）
+
+用 `--worktree` 启动时，工作区一建好就写下：`{ schema, sourceRepo, featureDir, repo, workspaceId, branch, baseRef, createdAt, originAgentId }`。之后的启动失败了，再次启动时在这个工作区里接着做，不再新建；插件据此把"工作区已建、开发没开始"的需求列进"等你处理"。`req index --rebuild` 为 1.9 之前运行过的需求补登，`req index --prune` 移除目录已不在的。
 
 ## 使用记录 `usage/runs.jsonl`
 

package/docs/guide//344/275/277/347/224/250/350/200/205/346/214/207/345/215/227.md

@@ -62,6 +62,8 @@ req-kit 帮你把一个需求从"我想要……"做到"可以验收"：你在 P
 
 装了 req-kit 插件的话（见 [安装与升级](安装与升级.md) 第 13 节），在 Paseo 侧边栏点"需求"：本机所有项目的需求一页看完，"需要你处理"的排在最前；点开一个需求能看到每一步的进度和用时、读需求说明、方案、确认预览和完成报告，也可以直接确认方案、停止、继续或开始测试验证。网页端、桌面版和手机上都能用。
 
+1.14 起，需求从开始谈的时候就出现在插件里（状态"对齐中"）；需求说明确认了却还没开始开发（超过 30 分钟），或者上次启动没成功的，会出现在"等你处理"里，点"开始开发"就能开始，进展照常发回谈需求的那个对话。
+
 1.12 起，首页最上面是"等你处理"：所有等你确认方案、回答问题、中断了的需求，等得最久的在前，每条写明要做什么、等了多久。方案可以直接确认，也可以写修改意见；方案审核的问题可以直接写回答，插件会转给这个需求的对话，效果和在对话里回答一样。首页的"配置"列出 req-kit 的全部设置：每一项是什么、现在的值、来自本机、团队还是项目的配置文件，可以按项目查看、搜索、只看改过的。
 
 **在原型上提意见（1.13 起）。** 界面改动的需求，在请你确认方案时会有一份界面原型。在插件首页的"等你处理"或需求页面最上面，点**"审查原型并确认方案"**按钮（终端里是 `req review <需求>`），原型审查页就在 Paseo 里打开（手机上会在浏览器中打开；嫌窗口小时点右上角"在新窗口打开"）：

package/docs/guide//351/241/271/347/233/256/345/256/232/345/210/266/344/270/216/350/277/220/350/241/214/350/247/204/345/210/231.md

@@ -285,6 +285,11 @@ Paseo 自带的 `/paseo-advisor`、`/paseo-committee` 等编排 skill 也可以
 
 在项目主目录、主分支上发起的需求，可以用 `--worktree` 启动（`/req` 中的"启动（自动新建工作区）"）：流水线从当前分支切出 `feature/<功能目录名>`，在 Paseo 中新建 worktree 工作区，把需求说明移过去并提交，之后的步骤都在那个工作区中运行，仍然挂在发起的对话下。对话的工作目录不变，查看进度、暂停、继续都在原对话中进行；读写需求文件用通知中给出的完整路径。只能在第一次启动时选择。见 ADR 0018。
 
+1.14 起：
+- **启动没成功也能接着做。** 工作区一建好就记下来（`~/.req-kit/worktrees/`）。之后不管哪一步失败（建工作区慢、启动前的检查没通过），再次执行启动命令都会在这个工作区里接着开始，不会报"分支已存在"，也不会留下只有需求说明的分支。新建工作区最多等 15 分钟（以前是 2 分钟，大仓库在 Windows 上常常不够）。以前版本留下的"分支和工作区都在、开发没开始"的，也会由 Paseo 接手那个目录接着做。
+- **访谈改过的 `GLOSSARY.md`、`docs/adr/` 一起带过去**，和需求说明在需求自己的分支上一起提交；主目录里的这些未提交改动保留不动（可能和别的改动在一起），确认后可以撤销。
+- **如实提示起点的问题**：需求说明已经提交在主分支上、本地主分支比远端落后、主目录里还有别的未提交改动时，启动结果里会写明。流水线不改动主分支。
+
 ## 调度：预约、提醒、自动继续、排队
 
 需要"以后再做"的事，流水线用 Paseo 的定时任务把一条写明步骤的消息发回发起的对话，由对话 agent 执行（机器或 daemon 重启后仍然有效，在 Paseo 的 Schedules 中可以看到）。暂停命令会取消这些预约。

package/engine/src/api.ts

@@ -26,6 +26,7 @@ import { FEATURES_DIR, findWorktreeRun, listFeatures, resolveFeatureArg, summari
 import { defaultConfigPath, KIT_ROOT, kitVersion } from "./locations.js";
 import { configView } from "./config-view.js";
 import { pruneIndex, readIndex, registerRequirement, requirementKey } from "./records.js";
+import { listWorktreeRecords } from "./worktree.js";
 import { isAlive, type PipelineState, readState, statePath, type StepRecord } from "./state.js";
 import { parsePeriod, summarizeRuns } from "./stats.js";
 import { readRuns, runsFile } from "./records.js";
@@ -68,7 +69,7 @@ export const READABLE_FILES = [
 
 const MAX_FILE_BYTES = 512 * 1024;
 
-export type Attention = "approval" | "business" | "permission" | "interrupted" | "not_completed" | null;
+export type Attention = "approval" | "business" | "permission" | "interrupted" | "not_completed" | "not_started" | null;
 
 /** What a person needs to do about a requirement, if anything. */
 export function attentionOf(state: Pick<PipelineState, "status" | "pid" | "outcome" | "waitingPermission"> | null): Attention {
@@ -139,14 +140,57 @@ export interface ListItem {
     canReply: boolean;
     /** 1.13, attention "permission": the step agent that waits for an approval. */
     agentId?: string;
+    /** 1.14, attention "not_started": the plugin can start development (req api run start). */
+    canStart?: boolean;
   } | null;
 }
 
+/** 1.14: a confirmed spec with no run gets attention after this long (the chat may still be starting it). */
+export const NOT_STARTED_AFTER_MS = 30 * 60_000;
+
+function recordFor(repo: string, featureDir: string) {
+  let real = repo;
+  try {
+    real = fs.realpathSync(repo);
+  } catch {
+    // As given.
+  }
+  return listWorktreeRecords().find((r) => r.repo === real && r.featureDir === featureDir) ?? null;
+}
+
+/** A confirmed requirement nobody started: its own worktree already made (a start that failed), or just confirmed. */
+function notStartedOf(repo: string, featureDir: string, confirmed: boolean, updatedAt: string, now = Date.now()): NonNullable<ListItem["waiting"]> | null {
+  if (!confirmed) return null;
+  const real = (() => {
+    try {
+      return fs.realpathSync(repo);
+    } catch {
+      return repo;
+    }
+  })();
+  const made = recordFor(real, featureDir);
+  if (!made && now - new Date(updatedAt).getTime() < NOT_STARTED_AFTER_MS) return null;
+  return {
+    since: made?.createdAt ?? updatedAt,
+    questions: [],
+    reason: made ? "新工作区已经建好，但开发没有开始（上次启动没有完成）。点\"开始开发\"会在这个工作区里接着开始。" : "需求说明已经确认，但开发还没有开始。",
+    card: null,
+    canReply: false,
+    canStart: true,
+  };
+}
+
 function item(repo: string, branch: string | null, featureDir: string, extra: { sourceRepo: string | null; workspaceId: string | null; project: string }): ListItem | null {
   const name = path.basename(featureDir);
   const summary = summarize({ path: repo, branch }, name);
   if (!summary) return null;
   const state = readStateSafe(repo, featureDir);
+  const notStarted = state ? null : notStartedOf(repo, summary.featureDir, summary.confirmed, summary.updatedAt);
+  // 1.14: a worktree made for it before the pipeline ran: it still belongs to the chat's checkout.
+  if (!state && !extra.sourceRepo) {
+    const made = recordFor(repo, summary.featureDir);
+    if (made) extra = { ...extra, sourceRepo: made.sourceRepo, workspaceId: extra.workspaceId ?? made.workspaceId, project: path.basename(made.sourceRepo) };
+  }
   return {
     key: requirementKey(extra.sourceRepo ?? repo, featureDir),
     project: extra.project,
@@ -163,12 +207,12 @@ function item(repo: string, branch: string | null, featureDir: string, extra: {
     status: state?.status ?? null,
     running: !!state && state.status === "running" && isAlive(state.pid),
     phase: state?.phase ?? null,
-    attention: attentionOf(state),
+    attention: attentionOf(state) ?? (notStarted ? "not_started" : null),
     current: currentSteps(state),
     updatedAt: summary.updatedAt,
     usage: usageOf(state),
     present: true,
-    waiting: waitingOf(repo, featureDir, state),
+    waiting: waitingOf(repo, featureDir, state) ?? notStarted,
     hasPrototype: fs.existsSync(path.join(repo, featureDir, "prototype")),
   };
 }
@@ -206,7 +250,8 @@ export function apiList(input: { repo: string; all: boolean }): ListItem[] {
       .filter((x): x is ListItem => x !== null);
   }
   const out: ListItem[] = [];
-  for (const e of readIndex()) {
+  const index = readIndex();
+  for (const e of index) {
     const found = e.present ? item(e.repo, null, e.featureDir, { sourceRepo: e.sourceRepo, workspaceId: e.workspaceId, project: e.project }) : null;
     out.push(
       found ?? {
@@ -234,9 +279,38 @@ export function apiList(input: { repo: string; all: boolean }): ListItem[] {
       },
     );
   }
+  // 1.14: requirements in projects this machine knows that were never registered (the chat did not
+  // run --track, or an older version): found in the projects' feature directories.
+  const seen = new Set(out.map((x) => x.key));
+  const projects = new Set(index.filter((e) => e.present).map((e) => e.sourceRepo ?? e.repo));
+  for (const dir of projects) {
+    let found: ReturnType<typeof listFeatures> = [];
+    try {
+      found = listFeatures(dir);
+    } catch {
+      continue;
+    }
+    for (const f of found) {
+      const state = readStateSafe(f.worktree, f.featureDir);
+      const source = state?.worktree?.sourceRepo ?? (samePathSafe(f.worktree, dir) ? null : dir);
+      const x = item(f.worktree, f.branch, f.featureDir, { sourceRepo: source, workspaceId: state?.worktree?.workspaceId ?? null, project: path.basename(dir) });
+      if (x && !seen.has(x.key)) {
+        seen.add(x.key);
+        out.push(x);
+      }
+    }
+  }
   return out.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
 }
 
+function samePathSafe(a: string, b: string): boolean {
+  try {
+    return fs.realpathSync(a) === fs.realpathSync(b);
+  } catch {
+    return a === b;
+  }
+}
+
 /** The repository and feature directory a requirement argument names, as `req status` resolves it. */
 export function locate(repoArg: string, feature: string): { repo: string; featureDir: string; sourceRepo: string | null } {
   if (!fs.existsSync(repoArg)) throw new ApiError("not_found", `目录不存在：${repoArg}`);
@@ -346,9 +420,35 @@ export function apiIndex(input: { rebuild: string[]; prune: boolean }) {
   return { scanned: [...dirs], registered, pruned, total: readIndex().length };
 }
 
-const RUNNABLE = ["approve", "stop", "resume", "verify", "sync", "reply"] as const;
+const RUNNABLE = ["approve", "stop", "resume", "verify", "sync", "reply", "start"] as const;
 
 /** Runs `req <command> <需求>` where people would, and reports what it said. */
+/**
+ * 1.14, starting from the plugin: like the chat would. In a project's main checkout the
+ * requirement gets its own worktree (or continues in the one an earlier start made); the
+ * pipeline reports to the chat the requirement was aligned in.
+ */
+export function startOptions(cwd: string, feature: string): string[] {
+  const out: string[] = [];
+  const git = (...a: string[]) => spawnSync("git", a, { cwd, encoding: "utf8", windowsHide: true });
+  const dirs = git("rev-parse", "--git-dir", "--git-common-dir");
+  if (dirs.status === 0) {
+    const [own, common] = dirs.stdout.trim().split(/\r?\n/).map((d) => path.resolve(cwd, d.trim()));
+    const branch = git("branch", "--show-current").stdout.trim();
+    // In the main checkout, unless the requirement's own branch is checked out here ("develop here").
+    if (own === common && branch !== `feature/${path.basename(feature)}`) out.push("--worktree");
+  }
+  let featureDir = feature;
+  try {
+    featureDir = resolveFeatureArg(cwd, feature);
+  } catch {
+    // The launcher reports it.
+  }
+  const chat = readIndex().find((e) => e.key === requirementKey(cwd, featureDir))?.chatAgentId;
+  if (chat) out.push("--origin-agent", chat);
+  return out;
+}
+
 export function apiRun(command: string, repoArg: string, feature: string, extra: string[]) {
   if (!(RUNNABLE as readonly string[]).includes(command)) throw new ApiError("not_allowed", `只能执行：${RUNNABLE.join("、")}`);
   if (!fs.existsSync(repoArg)) throw new ApiError("not_found", `目录不存在：${repoArg}`);
@@ -357,6 +457,7 @@ export function apiRun(command: string, repoArg: string, feature: string, extra:
   const env = { ...process.env };
   delete env.PASEO_AGENT_ID;
   delete env.PASEO_AGENT_CWD;
+  if (command === "start") extra = [...extra, ...startOptions(cwd, feature)];
   const r = spawnSync(process.execPath, [path.join(KIT_ROOT, "bin", "req.mjs"), command, feature, ...extra], {
     cwd,
     env,

package/engine/src/cli-args.ts

@@ -11,6 +11,7 @@ export const USAGE = `用法：
   start-pipeline [--feature <功能目录>] --status   查看进度（不写 --feature 时：工作区里只有一个需求运行过就看它）
   start-pipeline --feature <功能目录> --stop       停止（之后可用 --resume 继续）
   start-pipeline --list                           列出这个项目所有工作区中的需求
+  start-pipeline --feature <功能目录> --track     开始谈需求时登记它，Paseo 插件里从"对齐中"就能看到（1.14）
   start-pipeline --card-fields                    团队对接了外部系统时，确认需求说明时要一并确认的卡片字段
   start-pipeline --feature <功能目录> --spec-review  确认前请另一个模型独立审阅需求说明草稿（后台进行，结果发回对话）
   start-pipeline --feature <功能目录> --worktree     为这个需求新建 Paseo worktree 工作区并在那里开发（对话目录不变）
@@ -54,6 +55,7 @@ export function parseLaunchArgs(argv: string[]): LaunchArgs {
       stop: { type: "boolean", default: false },
       list: { type: "boolean", default: false },
       "card-fields": { type: "boolean", default: false },
+      track: { type: "boolean", default: false },
       "spec-review": { type: "boolean", default: false },
       worktree: { type: "boolean", default: false },
       "source-repo": { type: "string" },
@@ -124,6 +126,7 @@ export function parseLaunchArgs(argv: string[]): LaunchArgs {
     stop: values.stop ?? false,
     list: values.list ?? false,
     cardFields: values["card-fields"] ?? false,
+    track: values.track ?? false,
     specReview: values["spec-review"] ?? false,
     worktree: values.worktree ?? false,
     sourceRepo: values["source-repo"] ? path.resolve(values["source-repo"]) : null,

package/engine/src/features.ts

@@ -114,7 +114,27 @@ function mtime(file: string): number {
 export function summarize(worktree: Worktree, name: string): FeatureSummary | null {
   const dir = path.join(worktree.path, FEATURES_DIR, name);
   const specFile = path.join(dir, "spec.md");
-  if (!fs.existsSync(specFile)) return null;
+  const alignmentFile = path.join(dir, "alignment.md");
+  if (!fs.existsSync(specFile)) {
+    // 1.14: still in the interview (registered with --track, or the notes have begun).
+    if (!fs.existsSync(alignmentFile) && !fs.existsSync(path.join(dir, ".pipeline", "tracked.json"))) return null;
+    const notes = fs.existsSync(alignmentFile) ? fs.readFileSync(alignmentFile, "utf8") : "";
+    const updated = Math.max(mtime(alignmentFile), mtime(path.join(dir, ".pipeline", "tracked.json")), mtime(dir));
+    return {
+      name,
+      featureDir: `${FEATURES_DIR.split(path.sep).join("/")}/${name}`,
+      worktree: worktree.path,
+      branch: worktree.branch,
+      title: (/^#\s+(.+)$/m.exec(notes)?.[1] ?? name).replace(/^(访谈记录|需求对齐|对齐记录)[:：\s]*/, "").trim() || name,
+      type: null,
+      specVersion: null,
+      confirmed: false,
+      profile: null,
+      stage: "对齐中",
+      updatedAt: new Date(updated || Date.now()).toISOString(),
+      usage: null,
+    };
+  }
   const spec = fs.readFileSync(specFile, "utf8");
   const stateFile = path.join(dir, ".pipeline", "state.json");
   let state: RawState | null = null;

package/engine/src/launch.ts

@@ -16,6 +16,7 @@ import { loadConfig, PHASE_MODE_LABELS, type PipelineConfig, PROFILE_LABELS } fr
 import { cardFieldsText } from "./integrations.js";
 import { defaultConfigPath, ENGINE_DIR } from "./locations.js";
 import { describeLiveActivity, describeStatus, stopPipeline } from "./control.js";
+import { trackRequirement } from "./records.js";
 import { describeFeatures, featuresWithRuns, findWorktreeRun, listFeatures, resolveFeatureArg } from "./features.js";
 import { checkChatCwd, normalizeFeatureDir, preflight, type PreflightResult, specProfile, verifyPhaseProblem } from "./preflight.js";
 import { loadRuntimeFactory } from "./runtime-loader.js";
@@ -92,6 +93,22 @@ if (args.cardFields) {
   }
 }
 
+if (args.track) {
+  // 1.14: the requirement shows in the plugin from the start of the interview, with its chat.
+  try {
+    const repo = fs.realpathSync(args.repo);
+    const featureDir = normalizeFeatureDir(repo, args.featureDir);
+    const dir = path.join(repo, featureDir);
+    if (!fs.existsSync(dir)) throw new Error(`功能目录不存在：${featureDir}`);
+    trackRequirement(repo, featureDir, args.originAgentId);
+    console.log(`已登记需求：${featureDir}（Paseo 的 req-kit 插件里能看到它，状态"对齐中"${args.originAgentId ? "，关联这个对话" : ""}）`);
+    process.exit(0);
+  } catch (error) {
+    console.error(`没能登记需求：${(error as Error).message}`);
+    process.exit(2);
+  }
+}
+
 if (args.list) {
   console.log(describeFeatures(listFeatures(args.repo), args.repo));
   process.exit(0);
@@ -344,7 +361,9 @@ if (args.worktree) {
   try {
     ownWorktree = await Promise.race([
       create(),
-      new Promise<never>((_, reject) => setTimeout(() => reject(new Error("连接 Paseo 新建工作区超过 2 分钟没有完成")), 120_000).unref()),
+      // 1.14: big repositories (Windows especially) can take minutes to check out. Giving up early
+      // left a branch with only the spec on it; now it waits, and a later start continues there.
+      new Promise<never>((_, reject) => setTimeout(() => reject(new Error("连接 Paseo 新建工作区超过 15 分钟没有完成。工作区可能稍后才建好：再执行一次启动命令，会在已建好的工作区里接着开始")), 15 * 60_000).unref()),
     ]);
   } catch (error) {
     fail(`没能为这个需求新建工作区：${(error as Error).message}`);
@@ -356,7 +375,7 @@ if (args.worktree) {
   try {
     checked = preflight(args, hashFile);
   } catch (error) {
-    fail(`新工作区 ${ownWorktree.repo} 已建好，但无法在那里启动：${(error as Error).message}`);
+    fail(`新工作区 ${ownWorktree.repo} 已建好，但无法在那里启动：${(error as Error).message}\n问题解决后再执行一次启动命令，会在这个工作区里接着开始（不会再新建）。`);
   }
 }
 
@@ -403,8 +422,10 @@ console.log(
         ? "只做研发：写好提测说明和研发报告后结束，测试由人完成。"
         : null,
     ownWorktree
-      ? `已为这个需求新建工作区：${ownWorktree.repo}（分支 ${ownWorktree.branch}，在 Paseo 侧边栏中可以看到）。开发在那里进行，步骤仍挂在这个对话下；这个对话的工作目录不变。` +
-        `需求文件已移到 ${path.join(ownWorktree.repo, checked.featureDir)}${ownWorktree.removedSource ? "" : "（这里原有的已提交版本保留不动）"}，之后读写需求文件请用这个路径。`
+      ? `${ownWorktree.reused ? "在上次已建好的工作区中开始" : "已为这个需求新建工作区"}：${ownWorktree.repo}（分支 ${ownWorktree.branch}，在 Paseo 侧边栏中可以看到）。开发在那里进行，步骤仍挂在这个对话下；这个对话的工作目录不变。` +
+        `需求文件已移到 ${path.join(ownWorktree.repo, checked.featureDir)}${ownWorktree.removedSource ? "" : "（这里原有的已提交版本保留不动）"}，之后读写需求文件请用这个路径。` +
+        (ownWorktree.carried.length ? `\n访谈中改过的 ${ownWorktree.carried.join("、")} 也一起带过去提交了；这里的未提交改动保留不动，确认无误后可以撤销。` : "") +
+        ownWorktree.warnings.map((w) => `\n注意：${w}`).join("")
       : args.sourceRepo
         ? `这个需求在为它新建的工作区中开发：${checked.repo}`
         : null,

package/engine/src/paseo-runtime.ts

@@ -307,6 +307,11 @@ export function createRuntimeWithClient(
       if (!directory) throw new Error("Paseo 没有返回新工作区的目录");
       return { workspaceId: workspace.id, directory };
     },
+    async openWorkspace(directory) {
+      if (!client.workspaces) throw new Error("这个 Paseo 版本不支持接手已有的工作区目录");
+      const handle = await client.workspaces.open({ cwd: directory });
+      return { workspaceId: handle.id };
+    },
     async waitForWorkspaceSetup(workspaceId, timeoutMs) {
       const api = await getScripts();
       if (!api) return { status: "none", error: null };

package/engine/src/preflight.ts

@@ -31,6 +31,8 @@ export interface LaunchArgs {
   list: boolean;
   /** --card-fields: what /req confirms with the spec for the external systems (card.json). */
   cardFields?: boolean;
+  /** 1.14 --track: register a requirement being aligned, before the pipeline runs (shown in the plugin). */
+  track?: boolean;
   /** --spec-review: independent review of the draft spec, before confirmation. */
   specReview: boolean;
   /** --worktree: create a Paseo worktree workspace for this requirement and develop there. */

package/engine/src/records.ts

@@ -47,6 +47,8 @@ export interface IndexEntry {
   /** Name of the project: the source checkout's directory name. */
   project: string;
   registeredAt: string;
+  /** 1.14: the chat the requirement is being aligned in (registered before the pipeline ran). */
+  chatAgentId?: string | null;
 }
 
 export function indexDir(env: NodeJS.ProcessEnv = process.env): string {
@@ -59,7 +61,7 @@ export function requirementKey(sourceOrRepo: string, featureDir: string): string
 }
 
 /** Records where this requirement lives, if it is not recorded that way already. Never throws. */
-export function registerRequirement(state: Pick<PipelineState, "repo" | "featureDir" | "worktree">, env: NodeJS.ProcessEnv = process.env): void {
+export function registerRequirement(state: Pick<PipelineState, "repo" | "featureDir" | "worktree">, env: NodeJS.ProcessEnv = process.env, chatAgentId: string | null = null): void {
   if (recordingOff(env)) return;
   try {
     const source = state.worktree?.sourceRepo ?? null;
@@ -75,6 +77,7 @@ export function registerRequirement(state: Pick<PipelineState, "repo" | "feature
       workspaceId: state.worktree?.workspaceId ?? null,
       project: path.basename(real(source ?? state.repo)),
       registeredAt: existing?.registeredAt ?? new Date().toISOString(),
+      ...(chatAgentId ?? existing?.chatAgentId ? { chatAgentId: chatAgentId ?? existing?.chatAgentId ?? null } : {}),
     };
     if (existing && JSON.stringify(existing) === JSON.stringify(entry)) return;
     fs.mkdirSync(path.dirname(file), { recursive: true });
@@ -86,6 +89,24 @@ export function registerRequirement(state: Pick<PipelineState, "repo" | "feature
   }
 }
 
+/**
+ * 1.14: a requirement whose interview has started: marked in its feature directory
+ * (.pipeline/tracked.json, not committed) and registered with its chat, so the plugin lists it
+ * before the pipeline ever runs.
+ */
+export function trackRequirement(repo: string, featureDir: string, chatAgentId: string | null, env: NodeJS.ProcessEnv = process.env): void {
+  const marker = path.join(repo, featureDir, ".pipeline", "tracked.json");
+  fs.mkdirSync(path.dirname(marker), { recursive: true });
+  let since = new Date().toISOString();
+  try {
+    since = (JSON.parse(fs.readFileSync(marker, "utf8")) as { since?: string }).since ?? since;
+  } catch {
+    // First time.
+  }
+  fs.writeFileSync(marker, `${JSON.stringify({ since, chatAgentId }, null, 2)}\n`);
+  registerRequirement({ repo, featureDir, worktree: null }, env, chatAgentId);
+}
+
 function readEntry(file: string): IndexEntry | null {
   try {
     const raw = JSON.parse(fs.readFileSync(file, "utf8")) as IndexEntry;
@@ -104,7 +125,8 @@ export function readIndex(env: NodeJS.ProcessEnv = process.env): Array<IndexEntr
     .filter((n) => n.endsWith(".json"))
     .map((n) => readEntry(path.join(dir, n)))
     .filter((e): e is IndexEntry => e !== null)
-    .map((e) => ({ ...e, present: fs.existsSync(path.join(e.repo, e.featureDir, ".pipeline", "state.json")) }));
+    // 1.14: a requirement still in its interview has no state yet, only its notes.
+    .map((e) => ({ ...e, present: ["spec.md", "alignment.md", ".pipeline/state.json", ".pipeline/tracked.json"].some((f) => fs.existsSync(path.join(e.repo, e.featureDir, f))) }));
 }
 
 /** Removes the entries whose requirement is gone. Returns how many. */

package/engine/src/runtime.ts

@@ -135,6 +135,8 @@ export interface AgentRuntime {
   stopServices(target: ServiceTarget, names: string[]): Promise<void>;
   /** Creates a Paseo worktree workspace (paseo.json setup runs in the background). */
   createWorktree(request: WorktreeRequest): Promise<{ workspaceId: string; directory: string }>;
+  /** 1.14: the Paseo workspace of an existing directory (opened as one if it is not yet). */
+  openWorkspace?(directory: string): Promise<{ workspaceId: string }>;
   /** Waits for the workspace's paseo.json setup; "none" when there is nothing to wait for or it cannot be read. */
   waitForWorkspaceSetup(workspaceId: string, timeoutMs: number): Promise<{ status: "completed" | "failed" | "none" | "timeout"; error: string | null }>;
   /** Subscription windows of the given providers; null when Paseo has no usage data. */