cowork-flow 0.0.52 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 1.0.0 - 2026-08-26
+
+首个稳定主线发布：核心流程契约、会话模型与宿主矩阵在此版本冻结，后续改动进入语义化版本约束。
+
+### 稳定性声明
+
+- **宿主矩阵冻结**：`codex` / `opencode` / `claude-code` / `dsh` / `zcode` 五宿主经 host-assets 注册、adapter 一致性校验与 doctor 全链路覆盖；zcode 插件资产与工作区流程资产均为单源分发（`.zcode/` 走插件市场，技能落盘 `.cowork-flow/skills/` 供内核解析且不进入提示层）。
+- **状态注入协议冻结**：`<workflow-state>` 块 + contract-digest（SessionStart 全量 / 逐消息指纹行）+ 生命周期快照（`.runtime/state-snapshot.json`，与状态转换同单元原子提交）构成宿主 hook 的标准输入；`build_hook_context` 共享协议具备直接单测覆盖。
+- **会话模型冻结**：按会话身份（host session id / 显式 context id / hook sessionId）绑定；显式身份无绑定时判 `no_task` 并列可改绑任务，无身份请求才走全局最新有效兜底；进程级 fallback 绑定不再自动跟随。
+
+### 自 0.0.52 以来的变更
+
+- 会话绑定安全加固：进程 fallback 会话键（`ZCODE_PROCESS_LABEL`）带 provenance 标记，导航、`--run` 派发、review/complete 目标解析与命令行收尾拒绝自动跟随 fallback 绑定，要求显式任务目录；trusted 身份（显式 env、宿主 session env、hook sessionId）保持完整绑定语义。
+- 对抗性审查修正批次：显式 `COWORK_FLOW_CONTEXT_ID` 按裸键解析与 CLI 对齐；PostToolUse 刷新过滤支持 `cd` + 裸 `run` 与 Windows `run.cmd` 命令形态；legacy cursor 宿主保留完整 contract-digest；改绑提示排除已完成的终态任务；doctor 会话卫生检查对无时区时间戳降级为告警而非崩溃。
+- 交互式平台选择器与平台检测断言随五宿主矩阵更新。
+- release.sh 容错：`--version` 精确模式在版本文件已全部就位（干净工作树）时，`git commit` 的 no-op 空提交不再中止脚本，继续 tag 与 publish；其余 commit 失败仍立即中止。新增回归测试覆盖两条路径。
+- release.sh 容错：目标发布 tag 已存在且指向当前 HEAD 时跳过创建并继续 publish（上次运行 tag 后 publish 未完成的重跑场景）；指向其它提交则中止报错。新增回归测试覆盖两条路径。
+
 ## 0.0.52 - 2026-08-26
 
 ### ZCode 宿主与 hook 体验

package/README.md

@@ -314,6 +314,7 @@ npm run release:check     # 发布信心门禁；当前等价于 test:all
 ```bash
 npm run release          # patch
 npm run release -- minor # minor
+npm run release -- --version 0.1.0  # 精确发布指定版本（跳过自动 bump）
 ```
 
 **发布流程：**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-flow",
-  "version": "0.0.52",
+  "version": "1.0.0",
   "description": "CLI for installing and maintaining cowork-flow collaboration templates.",
   "type": "module",
   "bin": {

package/template/.cowork-flow/.version

@@ -1 +1 @@
-0.0.52
+1.0.0

package/template/.cowork-flow/scripts/adapters/cli/task_lifecycle_commands.py

@@ -26,7 +26,11 @@ from infra.paths import (
     FILE_TASK_JSON,
     get_repo_root,
 )
-from runtime.session_state import clear_active_task, get_active_task
+from runtime.session_state import (
+    PROVENANCE_PROCESS_FALLBACK,
+    clear_active_task,
+    get_active_task,
+)
 
 
 def _report_check_block(title: str, blockers: tuple[str, ...]) -> int:
@@ -71,6 +75,19 @@ def _resolve_status_task_dir(
                 file=sys.stderr,
             )
             return None
+        if (
+            active.task_path
+            and active.provenance == PROVENANCE_PROCESS_FALLBACK
+        ):
+            print(
+                colored(
+                    "Error: Session binding is process-fallback (shared); "
+                    "pass a task dir explicitly.",
+                    Colors.RED,
+                ),
+                file=sys.stderr,
+            )
+            return None
         if not active.task_path:
             print(
                 colored(
@@ -342,6 +359,16 @@ def cmd_finish(args: argparse.Namespace) -> int:
     """Clear the active task for this session."""
     repo_root = get_repo_root()
     active = get_active_task(repo_root)
+    if active.task_path and active.provenance == PROVENANCE_PROCESS_FALLBACK:
+        print(
+            colored(
+                "Error: Refusing to clear a session binding resolved from "
+                "process-fallback identity; archive the task to clear it.",
+                Colors.RED,
+            ),
+            file=sys.stderr,
+        )
+        return 1
     if not active.task_path:
         print(
             colored(

package/template/.cowork-flow/scripts/adapters/cli/task_navigation.py

@@ -10,7 +10,11 @@ from services.task_context import TaskContextService
 from adapters.cli.task_support import resolve_task_dir
 from adapters.cli.execution_context_args import execution_context_from_namespace
 from infra.paths import get_repo_root
-from runtime.session_state import get_active_task
+from runtime.session_state import (
+    FALLBACK_BINDING_BLOCKER,
+    PROVENANCE_PROCESS_FALLBACK,
+    get_active_task,
+)
 from services.readiness import task_readiness_blockers
 from services.task_repository import TaskRepository, TaskRepositoryError
 
@@ -359,13 +363,20 @@ def _navigation_target(args, repo_root: Path, structured: bool):
 
     active = get_active_task(repo_root)
     source = f"{active.source}:{active.context_key or '-'}"
-    if active.task_path:
+    # 进程标签回退身份是同实例所有会话共享的；其绑定只作 advisory，
+    # 不得自动定位任务（否则他会话绑定的任务会被当作本会话任务）。
+    untrusted_binding = (
+        bool(active.task_path)
+        and active.provenance == PROVENANCE_PROCESS_FALLBACK
+    )
+    if active.task_path and not untrusted_binding:
         return repo_root / active.task_path, active.task_path, source, True
+    blockers = [FALLBACK_BINDING_BLOCKER] if untrusted_binding else []
     if structured:
         payload = build_navigation_payload(
             args=args,
             status="no_task",
-            blockers=[],
+            blockers=blockers,
             active_target=False,
             task_path=None,
             repo_root=repo_root,
@@ -379,7 +390,7 @@ def _navigation_target(args, repo_root: Path, structured: bool):
             args=args,
             status="no_task",
             task_path=None,
-            blockers=[],
+            blockers=blockers,
             active_target=False,
             repo_root=repo_root,
         )

package/template/.cowork-flow/scripts/adapters/cli/task_next_runner.py

@@ -12,7 +12,11 @@ from typing import Callable
 from adapters.cli import task_navigation
 from adapters.cli.task_support import Colors, colored, resolve_task_dir
 from infra.paths import get_repo_root
-from runtime.session_state import get_active_task
+from runtime.session_state import (
+    FALLBACK_BINDING_BLOCKER,
+    PROVENANCE_PROCESS_FALLBACK,
+    get_active_task,
+)
 from services.plan_binding import PlanBindingError, bind_task_plan
 
 
@@ -48,19 +52,32 @@ def _next_target_for_run(args: argparse.Namespace, repo_root: Path):
         return task_dir, _display_task_path(repo_root, task_dir), False
 
     active = get_active_task(repo_root)
-    if active.task_path:
+    # 进程标签回退身份是共享的，绑定只作 advisory，不自动定位任务。
+    if active.task_path and active.provenance != PROVENANCE_PROCESS_FALLBACK:
         task_dir = repo_root / active.task_path
         return task_dir, active.task_path, True
     return None, None, False
 
 
+def _fallback_binding_blockers(
+    args: argparse.Namespace,
+    repo_root: Path,
+) -> list[str]:
+    if getattr(args, "dir", None):
+        return []
+    active = get_active_task(repo_root)
+    if active.task_path and active.provenance == PROVENANCE_PROCESS_FALLBACK:
+        return [FALLBACK_BINDING_BLOCKER]
+    return []
+
+
 def _next_payload_for_run(args: argparse.Namespace, repo_root: Path) -> dict[str, object]:
     task_dir, task_path, active_target = _next_target_for_run(args, repo_root)
     if task_dir is None or task_path is None:
         return task_navigation.build_navigation_payload(
             args=args,
             status="no_task",
-            blockers=[],
+            blockers=_fallback_binding_blockers(args, repo_root),
             active_target=False,
             task_path=None,
         )

package/template/.cowork-flow/scripts/runtime/session_state.py

@@ -17,8 +17,17 @@ DIR_SUBAGENTS = "subagents"
 FIELD_ACTIVE_TASK_PATH = "active_task_path"
 FIELD_RUNTIME_CONTEXT_ID = "runtime_context_id"
 FIELD_SCOPE = "scope"
+FIELD_IDENTITY_PROVENANCE = "identity_provenance"
 SCOPE_MAIN = "main"
 SCOPE_SUBAGENT = "subagent"
+PROVENANCE_EXPLICIT = "explicit"
+PROVENANCE_HOST_SESSION = "host_session"
+PROVENANCE_PROCESS_FALLBACK = "process_fallback"
+PROVENANCE_MISSING = "missing"
+FALLBACK_BINDING_BLOCKER = (
+    "session identity is process-fallback (shared); pass <task-dir> explicitly "
+    "or set COWORK_FLOW_CONTEXT_ID to a trusted session id"
+)
 RUNTIME_CONTEXT_PROMPT_RE = re.compile(
     r"(?im)^\s*cowork_runtime_context_id\s*:\s*([A-Za-z0-9._-]+)\s*$"
 )
@@ -32,6 +41,7 @@ class ActiveTask:
     task_path: str | None
     context_key: str | None
     source: str
+    provenance: str = PROVENANCE_MISSING
 
 
 def _sanitize(raw: str) -> str:
@@ -54,15 +64,28 @@ def _first_prompt_value(values: Mapping[str, object] | None) -> str | None:
 
 
 def resolve_context_key(values: Mapping[str, object] | None = None) -> str | None:
-    context_key = _resolve_env_context_key() or _resolve_input_context_key(values)
+    return resolve_context_key_with_provenance(values)[0]
+
+
+def resolve_context_key_with_provenance(
+    values: Mapping[str, object] | None = None,
+) -> tuple[str | None, str]:
+    context_key, provenance = _resolve_env_context_key_with_provenance()
+    if context_key:
+        return context_key, provenance
+    context_key = _resolve_input_context_key(values)
     if context_key:
-        return context_key
+        return context_key, PROVENANCE_HOST_SESSION
     # zcode 主会话（Bash CLI）无任何 host session id：用进程标签兜底，
     # 保证 task start / session 解析一次成功，不再回落到其它 host。
+    # 该身份是进程级共享的，消费方必须按 PROVENANCE_PROCESS_FALLBACK 降级处理。
     process_label = os.environ.get("ZCODE_PROCESS_LABEL")
     if process_label and process_label.strip():
-        return _prefixed_context_key("zcode", process_label)
-    return None
+        return (
+            _prefixed_context_key("zcode", process_label),
+            PROVENANCE_PROCESS_FALLBACK,
+        )
+    return None, PROVENANCE_MISSING
 
 
 def _prefixed_context_key(prefix: str, raw: str | None) -> str | None:
@@ -71,10 +94,10 @@ def _prefixed_context_key(prefix: str, raw: str | None) -> str | None:
     return None
 
 
-def _resolve_env_context_key() -> str | None:
+def _resolve_env_context_key_with_provenance() -> tuple[str | None, str]:
     explicit = os.environ.get("COWORK_FLOW_CONTEXT_ID")
     if explicit and explicit.strip():
-        return _sanitize(explicit)
+        return _sanitize(explicit), PROVENANCE_EXPLICIT
 
     for prefix, env_name in (
         ("zcode", "ZCODE_SESSION_ID"),
@@ -87,8 +110,12 @@ def _resolve_env_context_key() -> str | None:
     ):
         context_key = _prefixed_context_key(prefix, os.environ.get(env_name))
         if context_key:
-            return context_key
-    return None
+            return context_key, PROVENANCE_HOST_SESSION
+    return None, PROVENANCE_MISSING
+
+
+def _resolve_env_context_key() -> str | None:
+    return _resolve_env_context_key_with_provenance()[0]
 
 
 def _resolve_input_context_key(values: Mapping[str, object] | None) -> str | None:
@@ -262,23 +289,25 @@ def build_active_task_session(
     task_path: str,
 ) -> tuple[Path, dict, ActiveTask] | None:
     """Build the session state needed to activate a task."""
-    context_key = resolve_context_key()
+    context_key, provenance = resolve_context_key_with_provenance()
     if not context_key:
         return None
     normalized = task_path.replace("\\", "/")
     target = repo_root / normalized
     if not target.is_dir():
         return None
-    data = {
+    data: dict[str, object] = {
         FIELD_ACTIVE_TASK_PATH: normalized,
         FIELD_SCOPE: SCOPE_MAIN,
         "platform": platform_from_context_key(context_key),
         "last_seen_at": _now(),
     }
+    if provenance == PROVENANCE_PROCESS_FALLBACK:
+        data[FIELD_IDENTITY_PROVENANCE] = PROVENANCE_PROCESS_FALLBACK
     return (
         _session_path(repo_root, context_key),
         data,
-        ActiveTask(normalized, context_key, "session"),
+        ActiveTask(normalized, context_key, "session", provenance=provenance),
     )
 
 
@@ -292,14 +321,14 @@ def set_active_task(repo_root: Path, task_path: str) -> ActiveTask | None:
 
 
 def get_active_task(repo_root: Path, values: Mapping[str, object] | None = None) -> ActiveTask:
-    context_key = resolve_context_key(values)
+    context_key, provenance = resolve_context_key_with_provenance(values)
     if not context_key:
-        return ActiveTask(None, None, "missing-context")
+        return ActiveTask(None, None, "missing-context", provenance=provenance)
     data = _read_json(_session_path(repo_root, context_key))
     task_path = data.get(FIELD_ACTIVE_TASK_PATH)
     if isinstance(task_path, str) and task_path.strip():
-        return ActiveTask(task_path.strip(), context_key, "session")
-    return ActiveTask(None, context_key, "empty-session")
+        return ActiveTask(task_path.strip(), context_key, "session", provenance=provenance)
+    return ActiveTask(None, context_key, "empty-session", provenance=provenance)
 
 
 def is_main_session(repo_root: Path, values: Mapping[str, object] | None = None) -> bool:

package/template/.cowork-flow/scripts/services/task_lifecycle.py

@@ -526,7 +526,13 @@ class TaskLifecycleService:
         return None
 
     def _state_snapshot(self, stage: LifecycleStage, task_dir: Path) -> dict:
-        """Host-hook breadcrumb facts recorded atomically with the transition."""
+        """Host-hook breadcrumb facts recorded atomically with the transition.
+
+        breadcrumbKey intentionally equals target_status today: every current
+        stage maps one status to one breadcrumb tag. The field exists so a
+        future stage can diverge the two without changing hook consumers,
+        which trust this key over their own status-derived convention.
+        """
         return {
             "schemaVersion": 1,
             "generatedAt": (

package/template/.zcode/.zcode-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-flow",
-  "version": "0.0.51",
+  "version": "1.0.0",
   "description": "AI 协作工作流引擎：任务生命周期、子代理调度、门禁与状态注入。将 cowork-flow 的完整工作流带入 ZCode。",
   "author": {
     "name": "fisklikewater"

package/template/.zcode/hooks/inject-context.js

@@ -97,9 +97,14 @@ function sanitizeContextKey(raw) {
 }
 
 function resolveSessionKey(input) {
+  // Python session_state resolves an explicit COWORK_FLOW_CONTEXT_ID as the
+  // raw context key - it must not gain a host prefix here either.
   const explicit = process.env.COWORK_FLOW_CONTEXT_ID;
+  if (typeof explicit === "string" && explicit.trim()) {
+    const key = sanitizeContextKey(explicit);
+    if (key) return key;
+  }
   const candidates = [
-    explicit,
     process.env.ZCODE_SESSION_ID,
     input?.zcode_session_id,
     input?.ZCODE_SESSION_ID,
@@ -143,8 +148,8 @@ function toActiveTask(data) {
   };
 }
 
-// One-level scan of non-archived tasks for rebind hints; tasks/archive lives
-// two levels deeper so a plain readdir already excludes it.
+// One-level scan of bindable tasks for rebind hints; tasks/archive lives two
+// levels deeper so a plain readdir already excludes it.
 function listActiveTasks(repoRoot) {
   const tasksDir = join(repoRoot, DIR_WORKFLOW, "tasks");
   const out = [];
@@ -152,7 +157,7 @@ function listActiveTasks(repoRoot) {
     for (const name of readdirSync(tasksDir)) {
       const relative = `${DIR_WORKFLOW}/tasks/${name}`;
       const { status, missing } = readTaskStatus(repoRoot, relative);
-      if (!missing) out.push(`${relative} (${status})`);
+      if (!missing && status !== "completed") out.push(`${relative} (${status})`);
     }
   } catch {
     // tasks dir unreadable
@@ -445,8 +450,13 @@ function main() {
     typeof input?.hook_event_name === "string" &&
     input.hook_event_name.trim() === "PostToolUse"
   ) {
-    const command = String(input?.tool_input?.command || "");
-    if (!command.includes(".cowork-flow/run task")) {
+    // Normalize separators so Windows run.cmd invocations still match; the
+    // bare-run fallback covers `cd .cowork-flow && ./run task ...` forms.
+    const command = String(input?.tool_input?.command || "").replaceAll("\\", "/");
+    if (
+      !command.includes(".cowork-flow/run") &&
+      !/\brun(?:\.cmd)?\s+task\b/.test(command)
+    ) {
       process.exit(0);
     }
   }
@@ -487,10 +497,10 @@ Source: cowork-flow-plugin
   // so long sessions don't pay for the full listing on every message.
   const rootForDigest = effectiveRoot || envDir || input.cwd;
   if (rootForDigest) {
-    if (
-      typeof input?.hook_event_name === "string" &&
-      input.hook_event_name.trim() === "SessionStart"
-    ) {
+    // Use the normalized event so legacy hosts whose only signal is the
+    // plugin-root env (detectEventName guesses SessionStart) keep receiving
+    // the full block they got before slimming.
+    if (event === "SessionStart") {
       context = `${buildContractDigest(rootForDigest)}\n\n${context}`;
     } else {
       const contracts = loadContractRegistry(rootForDigest);

package/template/.zcode/hooks/inject-context.selfcheck.mjs

@@ -480,6 +480,59 @@ try {
     assert.match(parsedFor(), /活动任务正在执行/, "missing snapshot falls back cleanly");
   });
 
+  test("explicit COWORK_FLOW_CONTEXT_ID resolves its raw key like the CLI", () => {
+    ensureTask("07-02-test-task");
+    resetSessions({
+      "main-session.json": { active_task_path: ".cowork-flow/tasks/07-02-test-task", scope: "main", platform: "zcode", last_seen_at: "2026-07-02T13:00:00Z" },
+    });
+    const result = runHook(
+      { ZCODE_PROJECT_DIR: tmpRoot, COWORK_FLOW_CONTEXT_ID: "main-session" },
+      JSON.stringify({ hook_event_name: "UserPromptSubmit" })
+    );
+    const ctx = JSON.parse(result).hookSpecificOutput.additionalContext;
+    assert.match(ctx, /Task: \.cowork-flow\/tasks\/07-02-test-task/, "raw explicit key must hit the same file as the CLI");
+  });
+
+  test("PostToolUse refreshes for cd-and-bare-run command forms", () => {
+    ensureTask("07-02-test-task");
+    resetSessions({
+      "claude_abc.json": { active_task_path: ".cowork-flow/tasks/07-02-test-task", scope: "main", platform: "claude", last_seen_at: "2026-07-02T13:00:00Z" },
+    });
+    for (const command of [
+      "cd .cowork-flow && ./run task next --run",
+      ".\\run.cmd task next .cowork-flow/tasks/x",
+    ]) {
+      const result = runHook(
+        { ZCODE_PROJECT_DIR: tmpRoot },
+        JSON.stringify({ hook_event_name: "PostToolUse", tool_input: { command } })
+      );
+      const ctx = JSON.parse(result).hookSpecificOutput.additionalContext;
+      assert.match(ctx, /Status: in_progress/, `refresh expected for: ${command}`);
+    }
+  });
+
+  test("rebind hints exclude terminal completed tasks", () => {
+    ensureTask("07-02-test-task");
+    ensureTask("07-01-done", "completed");
+    resetSessions({
+      "zcode_stale.json": { active_task_path: ".cowork-flow/tasks/06-21-deleted", scope: "main", platform: "zcode", last_seen_at: "2026-08-01T09:00:00Z" },
+    });
+    const result = runHook(
+      { ZCODE_PROJECT_DIR: tmpRoot },
+      JSON.stringify({ hook_event_name: "UserPromptSubmit", session_id: "stale" })
+    );
+    const m = JSON.parse(result).hookSpecificOutput.additionalContext.match(/<workflow-state>([\s\S]*?)<\/workflow-state>/);
+    assert.ok(m);
+    assert.match(m[1], /07-02-test-task/);
+    assert.doesNotMatch(m[1], /07-01-done/, "completed tasks are not bindable candidates");
+  });
+
+  test("cursor legacy format keeps receiving the full contract digest", () => {
+    const result = runHook({ ZCODE_PROJECT_DIR: tmpRoot, CURSOR_PLUGIN_ROOT: "/x" });
+    const ctx = JSON.parse(result).additional_context;
+    assert.match(ctx, /<contract-digest fingerprint="[a-f0-9]+">/, "legacy cursor hosts get the full block as before slimming");
+  });
+
 } finally {
   cleanup();
 }

package/template/skills/runtime-health/scripts/doctor.py

@@ -380,6 +380,10 @@ def check_session_hygiene(repo_root: Path) -> list[dict[str, str]]:
         if seen_at is None and raw_seen_at:
             reasons.append(f"unparsable last_seen_at: {raw_seen_at}")
             aged = True
+        elif seen_at is not None and seen_at.tzinfo is None:
+            # Naive timestamps cannot be compared against aware now().
+            reasons.append(f"last_seen_at without timezone: {raw_seen_at}")
+            aged = True
         elif seen_at is not None:
             age_days = (now - seen_at).days
             if age_days > SESSION_STALE_MAX_AGE_DAYS: