@abelxiaoxing/cadence 1.5.2 → 1.6.0

package/README.md

@@ -95,6 +95,37 @@ Design 同任务续轮重新收紧允许的工具集合，预检失败或暂停
 Implement 只暴露 `start`、`status`、`resume`、`rebind`、`cancel` 和 `discard` 控制命令。
 `status` 完全本地可用；相同 operation id 幂等重放，进程、会话或 Worker 更换后仍从 durable checkpoint 继续。
 Design 从第一步起统一使用 `action: "design"`：新需求通过 `start(requirement)` 进入，已有 change 通过 `start(change)` 进入，后续只携带返回的 `runId`。
+
+### 升级后的私有状态重置
+
+包服务首次打开当前工作区时，比较数据库记录的包版本与当前 `package.json.version`。
+升级或旧库没有包版本标记时，自动将该工作区整个私有状态目录（SQLite/WAL、`run-data/` 下的候选工作区、产物和事务记录）移入同工作区专属备份目录，然后创建新库。
+控制库损坏导致版本不可读、版本标记无效，或控制库缺失但仍有旧资源时，也整体备份并重新初始化，不尝试修复或解释旧运行。
+可读有效版本标记与当前版本一致时保留状态；同版本号下替换代码不会触发重置，也不自动诊断其他表的损坏。
+能读取有效旧版本时，降级拒绝打开，不自动清库；旧版本不可读时不声称能够判断升降级。
+当前包版本仅接受当前发布使用的 `major.minor.patch` 格式。
+安装包时不扫描用户目录，其他工作区各自在首次打开时处理；只读 `doctor` / `runs` 不触发重置。
+
+**升级意味着旧运行不再可续用：运行、审批证明、进度、检查点和预算不继承到新库。**
+仓库代码、未提交改动及 OpenSpec 文件不变，但旧交付缺少原私有证明，不能直接视为有效交付；需要重新建立可信交付。
+备份不自动恢复或删除。
+服务响应的 `packageStateReset` 显示原因、前后版本及备份路径（不可读旧版本为 `null`），并明确 `oldRunsAbandoned: true`、`workspaceRestored: false` 和风险提示，不输出数据库内容、环境变量值或凭据。
+备份位于 `<roots>/<workspace-hash>.package-state/backup-<uuid>`，该目录中的 `lock.sqlite3` 和 `reset.json` 是协调与中断恢复记录，不应手工修改。
+
+**重置前必须退出所有旧宿主及其执行进程；数据库记录为 running 或租约未过期，不等于进程仍存活，也不再作为结算门槛。**
+新包使用工作区专属 SQLite 写锁，在整个服务生命周期内互斥；并发宿主或版本读取实际遇到 SQLite 锁时返回 `package-state-in-use`。
+该锁不能约束不认识它的旧版本或自行脱离的后代进程，重置不代表已经终止这些进程。
+旧任务、操作、租约以及缺失／损坏／未结算的事务记录一律随旧目录备份，不再要求先恢复或结算，也不由新库管理。
+**重置不会回滚主工作区：此前 apply 中断可能留下部分改动，请先检查 Git diff，再开始新工作。**
+真实权限、I/O 或备份发布失败仍报错；不能因想清库就绕过文件系统安全边界。
+状态根、控制库路径及协调路径的符号链接仍拒绝；嵌套资源链接随目录重命名保留，不跟随其目标或删除目标内容。
+备份不依赖读取旧的每运行事务数据库，包括 `run-data/<runId>/transactions/apply.sqlite3`。
+可识别的降级返回 `package-state-downgrade-blocked`。
+中断后同版本重试按持久化意图继续，不重复备份；未完成重置时不允许换另一个目标版本。
+目录刷新沿用下文 Windows 能力边界，不声称 Windows 断电场景具备 POSIX 目录持久化保证。
+
+底层 `RunStore` 仍保留经结构校验的旧 `schema_meta` v2/v4 原子迁移，供原版本恢复和独立存储调用使用；包服务的上述重置策略优先执行。
+v2 迁移只补齐可空凭证字段且保持 `NULL`，不伪造审批；损坏或部分升级仍拒绝打开，迁移失败整体回滚。
 需求、决策合同与 Gate A 合同由控制面规范化并计算哈希，调用方无需 SHA-256 工具；Gate B 自动绑定当前已编译 canonical plan，原始瞬时文本不会写入 durable journal。
 `validate-plan-draft` 可在 `compile-plan` 前只读运行同一套编译检查，并以结构化 `taskId` / phase / field / verification 诊断定位问题；Design finalization 的安全诊断码也会进入错误详情与可展开 TUI，而不再只显示统一失败标题。
 随包提供的 [单任务计划示例](config/plan-draft.example.json) 展示精简 PlanDraft 和结构化 Gate A 合同；按实际仓库替换示例中的路径、证据与验证命令。
@@ -150,6 +181,58 @@ Gate 等待和可恢复暂停保持激活以接收直接后续操作。
 暂停会保留最小结构化恢复事实；完成或显式 discard 后安全清理。
 不会持久化凭据、环境值、原始 prompt、隐藏推理、完整子会话或原始模型输出。
 
+### 公共 UI 的 impactClosure 作者格式
+
+`page-state` 与 `public-html` 可以同时声明。
+以下是 **PlanDraft 任务片段**，合并到现有 `tasks[i]`，不是完整计划；其余 Gate A、阶段、产物和验证合同仍按单任务示例填写。
+路径和证据仅用于说明，必须替换为仓库真实调查结果。
+假设 Red 修改 `test/page-state.mjs`，已有 `test/public-html.mjs` 只读保留：
+
+```json
+{
+  "read": ["test/page-state.mjs", "test/public-html.mjs"],
+  "impactClosure": {
+    "changedSurfaces": ["page-state", "public-html"],
+    "searchEvidence": [
+      "检索页面状态的调用点及 test/、tests/ 中的覆盖：test/page-state.mjs 需更新状态切换断言，test/public-html.mjs 覆盖现有公开 HTML。"
+    ],
+    "relatedTests": [
+      {
+        "path": "test/page-state.mjs",
+        "evidence": "本任务 Red 更新页面状态切换回归；由阶段 write 推导为 current-task。"
+      },
+      {
+        "path": "test/public-html.mjs",
+        "evidence": "保留已有 HTML 断言并执行受影响验证；无任务写入，推导为 unaffected。"
+      }
+    ],
+    "affectedSuite": ["test/page-state.mjs", "test/public-html.mjs"]
+  }
+}
+```
+
+完整规则：
+
+- `impactClosure` 恰好包含 `changedSurfaces`、`searchEvidence`、`relatedTests`、`affectedSuite` 四个字段，不接受任意扩展字段。
+- `changedSurfaces` 是非空、无重复的合法枚举数组；`none` 不能与其他值混用。
+  不得为了通过校验将公共影响改为 `none`。
+- 存在公共影响时，后三个数组均不得为空；`searchEvidence` 每项为非空字符串，记录实际检索及结论，不是路径对象，也不是可省略的推导字段。
+- `relatedTests` 每项包含 `path` 和非空字符串 `evidence`；路径无重复，必须是 `test/` 或 `tests/` 下的仓库相对文件路径，并位于本任务各阶段合并后的 read/write 范围。
+  `src/foo.test.ts` 不满足当前测试路径规则。
+- PlanDraft 可省略 `disposition`：本任务写入则推导为 `current-task`，只有另一任务写入则为 `regression-task` 并推导 `regressionTaskId`，没有任务写入则为 `unaffected`；多个其他写入者时必须消除歧义。
+  `unaffected` 表示不修改该测试，不表示不运行该测试。
+- 显式作者格式为 `{ "path": "test/page-state.mjs", "disposition": "current-task", "evidence": "实际证据" }`；只读保留用 `unaffected`。
+  跨任务格式为 `{ "path": "test/page-state.mjs", "disposition": "regression-task", "evidence": "实际证据", "regressionTaskId": "ui-regression" }`。
+  只有 `regression-task` 携带 `regressionTaskId`；依赖、产物和阶段权限仍需按实际计划声明，不会由闭包新增。
+- `affectedSuite` 是无重复的测试路径数组，每项必须有对应的 `relatedTests` 条目；具备快照的运行时校验还要求其中至少一个是已有普通测试文件，不能全靠未来新增测试充当已有证据。
+- `affectedSuite` 是影响清单，不是验证器。
+  显式 `affectedVerification` 应实际运行这些测试，例如 Vitest 的 `testFiles` 列出二者，或使用仓库真实的测试脚本。
+  仍需声明验证输入并遵守 Gate A，不能只补清单就宣称测试已运行。
+
+`validate-plan-draft` 对三个空数组分别返回字段级 category：`search-evidence-required`、`related-tests-required`、`affected-suite-required`，并提供代码维护的 `hint`。
+测试漏列仍返回 `impactClosure.affectedSuite.<index>` / `related-test-missing` 和具体 `path`。
+空数组不足以确定应选哪些测试，因此不会虚构 `expectedPaths`；按实际证据补齐后，在同一个 Design run 重试预检。
+
 ## 内部边界与运行验证
 
 扩展入口负责宿主生命周期与服务装配，交付加载和验证适配器分别由独立模块负责。
@@ -242,6 +325,18 @@ CLI 的其他版本必须满足相同 JSON 协议；新增支持版本应加入
 
 **此矩阵不代表原生 Implement 隔离已全平台可用。**
 默认隔离后端仍为 Linux Bubblewrap；Windows/macOS 的原生隔离、ACL 与完整文件应用语义需要单独实现和验收，缺少隔离能力时保持暂停，不降级为主工作区直接执行。
+
+目录持久化在 Windows 上单独处理：仅当已打开的目录句柄执行 `fsync` 返回 `EPERM` 时，标记为不支持目录刷新屏障。
+普通文件仍须在发布前成功 `fsync`；目录打开/关闭、权限、其他 I/O 及 POSIX 目录刷新错误不会被忽略。
+内容哈希校验、原子发布、SQLite 事务意图、CAS 与回滚记录继续生效；Windows 的进程中断恢复不等于 POSIX 目录屏障提供的断电持久性保证。
+
+以下是底层同版本恢复语义，不是跨包版本保留运行的承诺；跨版本以“升级后的私有状态重置”策略为准，旧运行会被放弃而非恢复。
+若同版本运行在存储异常后停留于 `running / phase-running`，请先停止旧宿主，完整备份 owner-private state root（含 SQLite、WAL 及 artifacts/workspaces），再加载同版本修复。
+用原工作区和原 state root 查询同一 change；重新打开时会在确认无有效执行租约后将遗留运行转为 `paused / operation-interrupted`，apply 中断则进入 `recovering`。
+按本地 `status` 提供的 `resume` 继续原运行，不需要重新 Design、重新 start、discard 或手动修改数据库。
+恢复保留交付绑定、阶段检查点、验证证据和已消耗预算，不返还预算、不伪造 Red/Green 结果；下一次执行仍须满足原有环境和隔离要求。
+不要为绕过 Windows 隔离限制而直接移动状态目录或更改工作区身份。
+
 可信 Linux 项目可以显式选择上面的 `local-trusted` 候选目录执行模式。
 
 本地可用 `CADENCE_REAL_OPENSPEC=1` 启用真实 CLI 测试（Windows 可用 PowerShell 设置 `$env:CADENCE_REAL_OPENSPEC = "1"`），然后运行：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abelxiaoxing/cadence",
-  "version": "1.5.2",
+  "version": "1.6.0",
   "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",

package/src/apply-transaction.ts

@@ -23,6 +23,7 @@ import { DatabaseSync } from "node:sqlite";
 import type { ArtifactStore } from "./artifact-store.ts";
 import { compareCanonicalStrings } from "./canonical.ts";
 import { isValidRelativePath } from "./contracts.ts";
+import { syncDirectory } from "./directory-sync.ts";
 import { observeSafePath } from "./safe-path.ts";
 import { configureSqlite, ensureSqliteSchema } from "./sqlite-schema.ts";
 import { APPLY_SCHEMA } from "./storage-schema.ts";
@@ -247,15 +248,6 @@ function ensurePrivateDirectory(directory: string): void {
   chmodSync(directory, 0o700);
 }
 
-function syncDirectory(directory: string): void {
-  const descriptor = openSync(directory, constants.O_RDONLY);
-  try {
-    fsyncSync(descriptor);
-  } finally {
-    closeSync(descriptor);
-  }
-}
-
 function entryEqual(left: WorkspaceEntry, right: WorkspaceEntry): boolean {
   if (left.kind !== right.kind) return false;
   return (

package/src/artifact-store.ts

@@ -14,6 +14,7 @@ import {
   writeFileSync,
 } from "node:fs";
 import path from "node:path";
+import { syncDirectory } from "./directory-sync.ts";
 
 const SHA256 = /^[a-f0-9]{64}$/u;
 
@@ -58,15 +59,6 @@ function ensureDirectory(directory: string): void {
   chmodSync(directory, 0o700);
 }
 
-function syncDirectory(directory: string): void {
-  const descriptor = openSync(directory, constants.O_RDONLY);
-  try {
-    fsyncSync(descriptor);
-  } finally {
-    closeSync(descriptor);
-  }
-}
-
 function writeAtomic(target: string, bytes: Uint8Array): void {
   const directory = path.dirname(target);
   ensureDirectory(directory);

package/src/contracts.ts

@@ -1574,12 +1574,23 @@ function taskFieldDiagnostics(
             allowedValues: [...IMPACT_SURFACES],
           });
       }
+      const publicImpact = closure.changedSurfaces.some(
+        (surface) =>
+          surface !== "none" &&
+          (IMPACT_SURFACES as readonly unknown[]).includes(surface),
+      );
+      if (publicImpact) {
+        for (const [field, category] of [
+          ["searchEvidence", "search-evidence-required"],
+          ["relatedTests", "related-tests-required"],
+          ["affectedSuite", "affected-suite-required"],
+        ] as const) {
+          if (Array.isArray(closure[field]) && closure[field].length === 0)
+            add({ field: `impactClosure.${field}`, category });
+        }
+      }
       if (
-        closure.changedSurfaces.some(
-          (surface) =>
-            surface !== "none" &&
-            (IMPACT_SURFACES as readonly unknown[]).includes(surface),
-        ) &&
+        publicImpact &&
         Array.isArray(closure.affectedSuite) &&
         Array.isArray(closure.relatedTests)
       ) {

package/src/design-diagnostics.ts

@@ -26,6 +26,14 @@ const HINTS = new Map<string, string>(
     "duplicate-path":
       "Remove the repeated path at the indicated index; keep the existing declaration and do not widen phase permissions.",
     enum: "Use one of allowedValues at the indicated field. For public impact, choose the actual changed surface; do not substitute none to bypass closure checks.",
+    "public-impact-incomplete":
+      "Public impact requires non-empty searchEvidence, relatedTests and affectedSuite; every affectedSuite path must have a relatedTests entry. Keep the actual changedSurfaces; do not substitute none.",
+    "search-evidence-required":
+      "Add non-empty searchEvidence strings describing actual searches of changed public surfaces, callers and existing tests. Do not invent evidence or substitute none for changedSurfaces.",
+    "related-tests-required":
+      "Add relatedTests entries with path and non-empty evidence for actual tests under test/ or tests/, within the task's declared read/write scope. In PlanDraft omit disposition to derive ownership from task writes; do not widen writes or substitute none.",
+    "affected-suite-required":
+      "Add actual affected test paths under test/ or tests/ to affectedSuite and declare each in relatedTests. Bind their execution in affectedVerification; retained snapshot validation requires at least one existing test. Do not invent paths or substitute none.",
     "related-test-missing":
       "Add this affected-suite test to relatedTests with evidence and its actual owner. Do not remove public impact or widen writes to satisfy ownership.",
     "change-contract-acceptance-missing":

package/src/directory-sync.ts

@@ -0,0 +1,36 @@
+import { closeSync, constants, fstatSync, fsyncSync, openSync } from "node:fs";
+
+/**
+ * Flush a published directory entry where Node supports it. Windows rejects
+ * FlushFileBuffers on Node's read-only directory handle with EPERM. This is
+ * specifically a missing directory barrier, NOT permission to ignore file
+ * flush, open, close, rename or other I/O errors.
+ *
+ * Callers must flush file bytes before publishing and retain their integrity
+ * checks / write-ahead recovery records. On Windows this provides process-crash
+ * recovery, not a POSIX directory-fsync guarantee across sudden power loss.
+ */
+export function syncDirectory(
+  directory: string,
+): "synced" | "unsupported-directory-barrier" {
+  const descriptor = openSync(directory, constants.O_RDONLY);
+  try {
+    try {
+      fsyncSync(descriptor);
+      return "synced";
+    } catch (error) {
+      const failure = error as NodeJS.ErrnoException | null;
+      if (
+        process.platform === "win32" &&
+        failure?.code === "EPERM" &&
+        failure.syscall === "fsync" &&
+        fstatSync(descriptor).isDirectory()
+      ) {
+        return "unsupported-directory-barrier";
+      }
+      throw error;
+    }
+  } finally {
+    closeSync(descriptor);
+  }
+}

package/src/index.ts

@@ -4,6 +4,7 @@ import {
   projectDesignDiagnostic,
   type SafeDesignDiagnostic,
 } from "./design-diagnostics.ts";
+import { PackageStateError } from "./package-state.ts";
 import { openPackageWorkflowService } from "./package-workflow.ts";
 import { packageContext } from "./pi-adapter.ts";
 
@@ -457,6 +458,14 @@ function classifyDesignFailure(
   field?: string;
 } {
   const message = error instanceof Error ? error.message : "";
+  if (error instanceof PackageStateError) {
+    return {
+      code: error.code,
+      category: "storage",
+      retryable: false,
+      field: "packageVersion",
+    };
+  }
   if (error instanceof DesignControlValidationError) {
     return {
       code: "invalid-design-control-request",
@@ -1229,6 +1238,25 @@ export function registerWorkflowControl(
           if (exitingStage || !activation.isActive())
             throw new Error("stage-control-mismatch");
         } catch (error) {
+          if (error instanceof PackageStateError) {
+            const payload = {
+              stage: "abel-implement",
+              change: validation.value.change,
+              state: "paused",
+              durable: false,
+              completed: false,
+              pause: { code: error.code },
+              legalCommands: ["status", "start"],
+              tasks: [],
+              queue: [],
+            };
+            return {
+              content: [
+                { type: "text" as const, text: JSON.stringify(payload) },
+              ],
+              details: payload,
+            };
+          }
           if (!(error instanceof RunStoreFormatError)) throw error;
           const payload = runStoreUnavailableStatus(error, validation.value);
           return {

package/src/package-state.ts

@@ -0,0 +1,309 @@
+import { randomUUID } from "node:crypto";
+import {
+  closeSync,
+  existsSync,
+  fsyncSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import path from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { syncDirectory } from "./directory-sync.ts";
+import { RunStore } from "./run-store.ts";
+import { prepareStateRoot, type ResolvedStateRoot } from "./state-root.ts";
+
+export class PackageStateError extends Error {
+  readonly code: string;
+  constructor(code: string) {
+    super(code);
+    this.code = code;
+  }
+}
+export interface PackageStateNotice {
+  reason:
+    | "package-upgrade"
+    | "unversioned-store"
+    | "unreadable-store"
+    | "missing-store";
+  previousVersion: string | null;
+  currentVersion: string;
+  backupPath: string;
+  oldRunsAbandoned: true;
+  workspaceRestored: false;
+  warning: string;
+}
+interface ResetIntent
+  extends Omit<
+    PackageStateNotice,
+    "oldRunsAbandoned" | "workspaceRestored" | "warning"
+  > {
+  backupName: string;
+}
+const fail = (code: string): never => {
+  throw new PackageStateError(code);
+};
+const versionParts = (version: string): number[] => {
+  if (!/^\d+\.\d+\.\d+$/u.test(version)) fail("package-state-version-invalid");
+  const parts = version.split(".").map(Number);
+  if (parts.some((part) => !Number.isSafeInteger(part)))
+    fail("package-state-version-invalid");
+  return parts;
+};
+function compareVersions(left: string, right: string): number {
+  const a = versionParts(left),
+    b = versionParts(right);
+  for (let i = 0; i < 3; i++) if (a[i] !== b[i]) return a[i] > b[i] ? 1 : -1;
+  return 0;
+}
+function regular(file: string): boolean {
+  const stat = lstatSync(file, { throwIfNoEntry: false });
+  if (!stat) return false;
+  if (!stat.isFile() || stat.isSymbolicLink())
+    fail("package-state-path-unsafe");
+  return true;
+}
+function table(db: DatabaseSync, name: string): boolean {
+  return !!db
+    .prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?")
+    .get(name);
+}
+function storedVersion(db: DatabaseSync): string | null {
+  if (!table(db, "cadence_package_version")) return null;
+  const rows = db.prepare("SELECT version FROM cadence_package_version").all();
+  if (rows.length !== 1 || typeof rows[0].version !== "string")
+    fail("package-state-version-invalid");
+  const version = String(rows[0].version);
+  versionParts(version);
+  return version;
+}
+// Only inspect the version. Old task/lease/apply records are deliberately not
+// interpreted: this policy abandons them, including malformed or unreadable facts.
+function inspectVersion(file: string): {
+  version: string | null;
+  unreadable: boolean;
+} {
+  let db: DatabaseSync | undefined;
+  try {
+    db = new DatabaseSync(file, { readOnly: true });
+    return { version: storedVersion(db), unreadable: false };
+  } catch (error) {
+    const failure = error as { errcode?: number; code?: string };
+    // An actual SQLite lock is not a stale durable lease record. Do not move
+    // storage while an uncoordinated old opener is observably using it.
+    if (failure.errcode !== undefined && [5, 6].includes(failure.errcode & 255))
+      fail("package-state-in-use");
+    if (
+      (error instanceof PackageStateError &&
+        error.code === "package-state-version-invalid") ||
+      (failure.errcode !== undefined &&
+        [1, 11, 26].includes(failure.errcode & 255))
+    )
+      return { version: null, unreadable: true };
+    // Schema errors / SQLITE_CORRUPT / SQLITE_NOTADB mean opaque old bytes.
+    // Permissions, disk I/O, resource exhaustion and unknown errors do not.
+    return fail("package-state-reset-unavailable");
+  } finally {
+    db?.close();
+  }
+}
+
+function hasOldResources(state: ResolvedStateRoot): boolean {
+  // Cover the production run-data layout and unknown historical resources.
+  // Never descend through resource links; the whole root is renamed as-is.
+  const emptyScaffolds = new Set(["artifacts", "workspaces", "transactions"]);
+  return readdirSync(state.rootDir).some((name) => {
+    const file = path.join(state.rootDir, name);
+    const stat = lstatSync(file);
+    return (
+      !emptyScaffolds.has(name) ||
+      !stat.isDirectory() ||
+      stat.isSymbolicLink() ||
+      readdirSync(file).length > 0
+    );
+  });
+}
+
+const RESET_WARNING =
+  "Old runs and approval evidence are abandoned, not resumed. Stop all old hosts and execution processes before resetting; the lock cannot fence older versions or detached descendants. The main workspace is not restored: interrupted apply may have left partial changes. Inspect Git diff before starting new work.";
+
+function persistIntent(file: string, intent: ResetIntent): void {
+  const temp = `${file}.tmp`;
+  regular(temp);
+  const fd = openSync(temp, "w", 0o600);
+  try {
+    writeFileSync(fd, JSON.stringify(intent));
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+  renameSync(temp, file);
+  syncDirectory(path.dirname(file));
+}
+
+/** Package boundary only: low-level storage and read-only operator inspection never reset state.
+ * The external SQLite write lock is held until every service connection has closed.
+ * SQLite releases it on process death; no PID guessing or stale-lock deletion is used.
+ */
+export function acquirePackageState(
+  unresolved: ResolvedStateRoot,
+  version = String(
+    JSON.parse(
+      readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+    ).version,
+  ),
+): { notice?: PackageStateNotice; close(): void } {
+  versionParts(version);
+  const state = prepareStateRoot(unresolved);
+  for (const suffix of ["-wal", "-shm", "-journal"])
+    regular(state.databasePath + suffix);
+  const coordinator = path.join(
+    state.rootsDir,
+    `${state.consumerRootHash}.package-state`,
+  );
+  const stat = lstatSync(coordinator, { throwIfNoEntry: false });
+  if (stat && (!stat.isDirectory() || stat.isSymbolicLink()))
+    fail("package-state-path-unsafe");
+  mkdirSync(coordinator, { recursive: true, mode: 0o700 });
+  const lockFile = path.join(coordinator, "lock.sqlite3");
+  for (const suffix of ["", "-journal", "-wal", "-shm"])
+    regular(lockFile + suffix);
+  if (!existsSync(lockFile)) {
+    try {
+      closeSync(openSync(lockFile, "wx", 0o600));
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+    }
+  }
+  const lock = new DatabaseSync(lockFile);
+  let closed = false;
+  const close = () => {
+    if (!closed) {
+      closed = true;
+      lock.close();
+    }
+  };
+  try {
+    lock.exec("PRAGMA busy_timeout = 1; BEGIN IMMEDIATE");
+  } catch {
+    close();
+    fail("package-state-in-use");
+  }
+  try {
+    const intentFile = path.join(coordinator, "reset.json");
+    let intent: ResetIntent | undefined;
+    if (regular(intentFile)) {
+      intent = JSON.parse(readFileSync(intentFile, "utf8")) as ResetIntent;
+      if (
+        !intent ||
+        !/^backup-[a-f0-9-]{36}$/u.test(intent.backupName) ||
+        intent.backupPath !== path.join(coordinator, intent.backupName) ||
+        ![
+          "package-upgrade",
+          "unversioned-store",
+          "unreadable-store",
+          "missing-store",
+        ].includes(intent.reason) ||
+        (intent.previousVersion !== null &&
+          typeof intent.previousVersion !== "string")
+      )
+        fail("package-state-reset-intent-invalid");
+      if (intent.currentVersion !== version)
+        fail("package-state-reset-version-mismatch");
+    }
+    let fresh = !regular(state.databasePath);
+    if (!intent) {
+      const observed = fresh
+        ? { version: null, unreadable: false }
+        : inspectVersion(state.databasePath);
+      if (observed.version === version) return { close };
+      if (
+        observed.version !== null &&
+        compareVersions(observed.version, version) > 0
+      )
+        fail("package-state-downgrade-blocked");
+      if (!fresh || hasOldResources(state)) {
+        const backupName = `backup-${randomUUID()}`;
+        intent = {
+          backupName,
+          backupPath: path.join(coordinator, backupName),
+          previousVersion: observed.version,
+          currentVersion: version,
+          reason: fresh
+            ? "missing-store"
+            : observed.unreadable
+              ? "unreadable-store"
+              : observed.version === null
+                ? "unversioned-store"
+                : "package-upgrade",
+        };
+        persistIntent(intentFile, intent);
+      }
+    }
+    if (intent) {
+      const backup = lstatSync(intent.backupPath, { throwIfNoEntry: false });
+      if (backup && (!backup.isDirectory() || backup.isSymbolicLink()))
+        fail("package-state-path-unsafe");
+      if (!backup) {
+        // Abandon the old namespace as opaque bytes, including run-data and
+        // SQLite sidecars. No transaction replay or main-workspace rollback.
+        renameSync(state.rootDir, intent.backupPath);
+        syncDirectory(coordinator);
+        syncDirectory(state.rootsDir);
+      }
+      prepareStateRoot(state);
+      fresh = true;
+    }
+    if (fresh) {
+      RunStore.open(state).close();
+      const db = new DatabaseSync(state.databasePath);
+      try {
+        db.exec(
+          "PRAGMA synchronous = FULL; BEGIN IMMEDIATE; CREATE TABLE IF NOT EXISTS cadence_package_version (version TEXT NOT NULL) STRICT",
+        );
+        const existing = db
+          .prepare("SELECT version FROM cadence_package_version")
+          .all();
+        if (existing.length === 0)
+          db.prepare("INSERT INTO cadence_package_version VALUES (?)").run(
+            version,
+          );
+        else if (existing.length !== 1 || existing[0].version !== version)
+          fail("package-state-reset-version-mismatch");
+        db.exec("COMMIT");
+      } finally {
+        db.close();
+      }
+      syncDirectory(state.rootDir);
+    }
+    if (intent) {
+      unlinkSync(intentFile);
+      syncDirectory(coordinator);
+    }
+    return {
+      close,
+      ...(intent
+        ? {
+            notice: {
+              reason: intent.reason,
+              previousVersion: intent.previousVersion,
+              currentVersion: version,
+              backupPath: intent.backupPath,
+              oldRunsAbandoned: true,
+              workspaceRestored: false,
+              warning: RESET_WARNING,
+            },
+          }
+        : {}),
+    };
+  } catch (error) {
+    close();
+    if (error instanceof PackageStateError) throw error;
+    throw new PackageStateError("package-state-reset-unavailable");
+  }
+}