@brainervirus/workit-core 1.0.11 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainervirus/workit-core",
-  "version": "1.0.11",
+  "version": "1.1.0",
   "private": false,
   "description": "Workit shared core — task, policy, evidence, review, decision, worker, and writer state for agentic coding workflows",
   "keywords": [

package/src/core/authority.ts

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import path from "node:path";
+import { operationAutoClass, standingApprovalLive } from "./auto-approval";
 import {
   canonicalJson,
   decisionDigest,
@@ -181,12 +182,57 @@ export type ReconcileActionInput = {
 
 type Workflow = { steps: string[]; completed: string[] };
 
+/** One typed step of a chain reservation. Plain strings are commit
+ * messages (the historical plan_steps shape); branch and pr steps carry
+ * their match key. Keys are the canonical consumption alphabet. */
+export type ChainStep =
+  | { kind: "commit"; message: string }
+  | { kind: "branch"; target: string }
+  | { kind: "pr" };
+
+export const chainStepKey = (step: ChainStep): string =>
+  step.kind === "commit" ? step.message : step.kind === "branch" ? `branch:${step.target}` : "pr";
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+/** Normalize mixed plan steps to typed entries. Returns null for empty,
+ * over-long, malformed, or key-colliding lists (a commit message that
+ * spells exactly like a typed key is rejected rather than misrouted). */
+export const normalizeChainSteps = (steps: unknown): ChainStep[] | null => {
+  if (!Array.isArray(steps) || steps.length === 0 || steps.length > 32) return null;
+  const normalized: ChainStep[] = [];
+  for (const step of steps) {
+    if (typeof step === "string") {
+      if (!step.trim()) return null;
+      normalized.push({ kind: "commit", message: step });
+      continue;
+    }
+    if (!isRecord(step)) return null;
+    if (typeof step.branch === "string" && step.branch.trim() && Object.keys(step).length === 1) {
+      normalized.push({ kind: "branch", target: step.branch });
+      continue;
+    }
+    if (step.pr === true && Object.keys(step).length === 1) {
+      normalized.push({ kind: "pr" });
+      continue;
+    }
+    return null;
+  }
+  const keys = normalized.map(chainStepKey);
+  if (new Set(keys).size !== keys.length) return null;
+  return normalized;
+};
+
 const scopeEqual = (
   left: Decision["binding"]["scope"],
   right: Decision["binding"]["scope"],
 ): boolean => canonicalJson(left) === canonicalJson(right);
 
-const parseSteps = (content: string): string[] | null => {
+/** Parse the durable approved text into typed chain steps. Single commits
+ * and branch/PR operations carry no step list (empty, not an invalid
+ * chain); an invalid list is null and rejected by callers. */
+const parseSteps = (content: string): ChainStep[] | null => {
   let value: unknown;
   try {
     value = JSON.parse(content) as unknown;
@@ -195,7 +241,9 @@ const parseSteps = (content: string): string[] | null => {
   }
   if (typeof value !== "object" || value === null || !("steps" in value)) return [];
   const steps = (value as { steps?: unknown }).steps;
-  return Array.isArray(steps) && steps.every((step) => typeof step === "string") ? steps : null;
+  if (!Array.isArray(steps)) return null;
+  const normalized = normalizeChainSteps(steps);
+  return normalized;
 };
 
 const decisionMatches = (
@@ -532,6 +580,36 @@ const validateAction = (
     !provenanceMatches(entry.provenance, authority.provenance)
   )
     return failure("permission_denied", "action approval lacks native receipt assurance");
+  // Standing auto-approval receipts carry no live question. They authorize
+  // only while the referenced workspace rule still covers the operation —
+  // verified here, at reserve time, against current config. Question-backed
+  // approvals (host-kind receipts) skip this; anything else was already
+  // denied above.
+  const receipts = entry.provenance.receipts as unknown[];
+  const standing = receipts.filter(
+    (receipt) =>
+      typeof receipt === "object" &&
+      receipt !== null &&
+      (receipt as { kind?: unknown }).kind === "standing",
+  );
+  const questionBacked = receipts.some(
+    (receipt) =>
+      typeof receipt === "object" &&
+      receipt !== null &&
+      (receipt as { kind?: unknown }).kind === "host",
+  );
+  if (!questionBacked && standing.length > 0) {
+    let operation: unknown;
+    try {
+      operation = (JSON.parse(decision.binding.approvedContent) as { operation?: unknown })
+        .operation;
+    } catch {
+      operation = null;
+    }
+    const cls = operationAutoClass(operation);
+    if (!cls || !standing.some((receipt) => standingApprovalLive(store.root, receipt, cls)))
+      return failure("permission_denied", "standing auto-approval is not live for this operation");
+  }
   if (decision.revoked) return failure("permission_denied", "decision is revoked");
   if (decision.digest !== decisionDigest(decision))
     return failure("permission_denied", "decision binding is invalid");
@@ -543,22 +621,17 @@ const validateAction = (
   if (!content.ok) return content as Result<never>;
   const requestedSteps = parseSteps(decision.binding.approvedContent);
   if (requestedSteps === null)
-    return failure("invalid_input", "bounded action steps must be a string array");
-  if (input.steps && canonicalJson(input.steps) !== canonicalJson(requestedSteps))
+    return failure("invalid_input", "bounded action steps must be a unique non-empty array");
+  if (input.steps && canonicalJson(input.steps) !== canonicalJson(requestedSteps.map(chainStepKey)))
     return failure("permission_denied", "bounded action steps do not match approved content");
-  if (
-    requestedSteps.some((step) => !step || typeof step !== "string") ||
-    new Set(requestedSteps).size !== requestedSteps.length
-  )
-    return failure("invalid_input", "bounded action steps must be unique and non-empty");
   const stored = task.actionProgress?.find((item) => item.decisionId === input.decisionId);
   const workflow = stored
     ? { steps: stored.steps, completed: stored.completedSteps }
-    : { steps: requestedSteps, completed: [] };
+    : { steps: requestedSteps.map(chainStepKey), completed: [] };
   if (
     workflow.steps.length &&
     requestedSteps.length &&
-    canonicalJson(workflow.steps) !== canonicalJson(requestedSteps)
+    canonicalJson(workflow.steps) !== canonicalJson(requestedSteps.map(chainStepKey))
   )
     return failure("permission_denied", "bounded action scope changed");
   return success(null, null, { entry, workflow });

package/src/core/auto-approval.ts

@@ -0,0 +1,326 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { resolveWorkspaceFrom, type WorkspaceConfig } from "./workspaces";
+import { configDir } from "./config";
+import { verifyPushIdentity } from "./branch";
+import {
+  failure,
+  success,
+  type Caller,
+  type Id,
+  type Provenance,
+  type Result,
+  type Revision,
+  type TaskRecord,
+} from "./task-contract";
+import type { TaskStore } from "./task-store";
+import type { WorkitCore } from "./task-engine";
+import type { Decision } from "./task-contract";
+
+/** Action classes auto-approval can cover. Unknown classes never match. */
+export const AUTO_CLASSES = ["branch", "commit", "push", "pr", "merge"] as const;
+export type AutoClass = (typeof AUTO_CLASSES)[number];
+
+export type AutoApproval =
+  | { status: "off" }
+  | {
+      status: "on";
+      workspace: string;
+      classes: AutoClass[];
+      account: string | null;
+      configDigest: string | null;
+    };
+
+export type StandingReceipt = {
+  kind: "standing";
+  workspace: string;
+  class: string;
+  configDigest: string | null;
+};
+
+const OPERATION_CLASS: Record<string, AutoClass> = {
+  "git.branch_setup": "branch",
+  "git.commit": "commit",
+  "git.push": "push",
+  "hosting.pull_request": "pr",
+  "hosting.merge": "merge",
+};
+
+/** Map an external-action operation to its auto-approval class, if any. */
+export const operationAutoClass = (operation: unknown): AutoClass | null =>
+  typeof operation === "string" ? (OPERATION_CLASS[operation] ?? null) : null;
+
+const digestOf = (configDirPath: string): string | null => {
+  try {
+    const raw = readFileSync(`${configDirPath}/workspaces.json`, "utf8");
+    return createHash("sha256").update(raw).digest("hex");
+  } catch {
+    return null;
+  }
+};
+
+const normalizeClasses = (value: unknown): AutoClass[] => {
+  if (value === true) return [...AUTO_CLASSES];
+  if (!Array.isArray(value)) return [];
+  const seen = new Set<AutoClass>();
+  for (const item of value) {
+    if (typeof item === "string" && (AUTO_CLASSES as readonly string[]).includes(item))
+      seen.add(item as AutoClass);
+  }
+  return [...seen];
+};
+
+/** Resolve the auto-approval rule for a checkout root (live read, never cached). */
+export const resolveAutoApproval = (root: string, dir: string = configDir()): AutoApproval => {
+  let match: WorkspaceConfig | null;
+  try {
+    match = resolveWorkspaceFrom(root, dir);
+  } catch {
+    return { status: "off" };
+  }
+  if (!match) return { status: "off" };
+  const classes = normalizeClasses(match.autoApprove);
+  if (classes.length === 0) return { status: "off" };
+  return {
+    status: "on",
+    workspace: match.name,
+    classes,
+    account: typeof match.vcs?.account === "string" && match.vcs.account ? match.vcs.account : null,
+    configDigest: digestOf(dir),
+  };
+};
+
+/** True when the workspace rule covers the class right now. */
+export const autoApproves = (root: string, cls: unknown, dir?: string): boolean => {
+  if (typeof cls !== "string" || !(AUTO_CLASSES as readonly string[]).includes(cls)) return false;
+  const resolved = resolveAutoApproval(root, dir);
+  return resolved.status === "on" && resolved.classes.includes(cls as AutoClass);
+};
+
+const isStandingReceipt = (value: unknown): value is StandingReceipt =>
+  typeof value === "object" && value !== null && (value as { kind?: unknown }).kind === "standing";
+
+/**
+ * A standing receipt authorizes only while the referenced workspace rule
+ * still covers the class. Removing the flag (or narrowing the list) fails
+ * closed on the very next reserve — no revocation step needed.
+ */
+export const standingApprovalLive = (
+  root: string,
+  receipt: unknown,
+  cls: unknown,
+  dir?: string,
+): boolean => {
+  if (!isStandingReceipt(receipt)) return false;
+  if (typeof cls !== "string" || !(AUTO_CLASSES as readonly string[]).includes(cls)) return false;
+  if (receipt.class !== cls) return false;
+  const resolved = resolveAutoApproval(root, dir);
+  if (resolved.status !== "on") return false;
+  if (resolved.workspace !== receipt.workspace) return false;
+  return resolved.classes.includes(cls as AutoClass);
+};
+
+/** Build the receipt an auto-recorded decision carries (current digest). */
+export const standingReceiptFor = (
+  root: string,
+  workspace: string,
+  cls: AutoClass,
+  dir?: string,
+): StandingReceipt => {
+  const resolved = resolveAutoApproval(root, dir);
+  return {
+    kind: "standing",
+    workspace,
+    class: cls,
+    configDigest:
+      resolved.status === "on" && resolved.workspace === workspace ? resolved.configDigest : null,
+  };
+};
+
+/**
+ * Verify a standing approval record request: active task, lead session
+ * match (helpers never auto-approve), operation class equals the claimed
+ * class, rule live right now, push identity enforced for push.
+ * Returns the host-observed provenance the entry carries on success.
+ */
+export const verifyStandingApproval = (
+  root: string,
+  task: TaskRecord,
+  caller: Caller,
+  binding: {
+    standing?: { workspace?: unknown; class?: unknown };
+    approvedContent?: unknown;
+  },
+): Result<Provenance> => {
+  if (task.status !== "active")
+    return failure("invalid_transition", "only active tasks can authorize actions");
+  const session = task.intent?.provenance?.session;
+  if (
+    !session ||
+    session.kind !== "host" ||
+    session.host !== caller.host ||
+    session.handle !== caller.actor
+  )
+    return failure("permission_denied", "standing approval requires the lead session");
+  const standing = binding.standing;
+  if (!standing || typeof standing.workspace !== "string" || typeof standing.class !== "string")
+    return failure("invalid_input", "standing approval needs a workspace and class");
+  let operation: unknown;
+  try {
+    operation =
+      typeof binding.approvedContent === "string"
+        ? (JSON.parse(binding.approvedContent) as { operation?: unknown }).operation
+        : null;
+  } catch {
+    operation = null;
+  }
+  const cls = operationAutoClass(operation);
+  if (!cls || cls !== standing.class)
+    return failure("permission_denied", "standing approval does not cover this operation");
+  const resolved = resolveAutoApproval(root);
+  if (
+    resolved.status !== "on" ||
+    resolved.workspace !== standing.workspace ||
+    !resolved.classes.includes(cls)
+  )
+    return failure("permission_denied", "standing auto-approval is not live for this operation");
+  if (cls === "push") {
+    const workspace = resolveWorkspaceFrom(root, configDir());
+    const provider = workspace?.vcs?.provider;
+    const account = resolved.account;
+    if (!provider || !account)
+      return failure(
+        "permission_denied",
+        "auto-push requires a workspace provider and area account",
+      );
+    const identity = verifyPushIdentity(root, provider, account);
+    if (!identity.ok) return failure("permission_denied", identity.error);
+  }
+  return success(null, null, {
+    kind: "host_observed",
+    host: caller.host,
+    session: { kind: "host", host: caller.host, handle: caller.actor },
+    workerId: null,
+    receipts: [standingReceiptFor(root, standing.workspace, cls)],
+  } as Provenance);
+};
+
+export type StandingAutoBinding = {
+  taskId: Id;
+  decisionId: Id;
+  binding: Decision["binding"];
+  expectedRevision: Revision;
+  expectedWorkspaceRevision: Revision;
+  step?: string;
+};
+
+type StandingMatch = {
+  task: TaskRecord;
+  workspaceId: Id;
+  workspaceRevision: Revision;
+  cls: AutoClass;
+  workspaceName: string;
+};
+
+/**
+ * Dry-run half of standingAutoBinding: same matching, no recording. Tool
+ * gates use this to decide between executing and asking; the runner records.
+ */
+export const standingAutoApplies = (
+  store: TaskStore,
+  host: string,
+  actor: string,
+  operation: string,
+): StandingMatch | null => {
+  let descriptor: { operation?: unknown };
+  try {
+    descriptor = JSON.parse(operation) as { operation?: unknown };
+  } catch {
+    return null;
+  }
+  const cls = operationAutoClass(descriptor.operation);
+  if (!cls || !autoApproves(store.root, cls)) return null;
+  const listed = store.listTasks();
+  const workspace = store.readWorkspace();
+  if (!listed.ok || !workspace.ok || !workspace.data) return null;
+  const matches = listed.data.filter(
+    (task) =>
+      task.status === "active" &&
+      task.workspaceId === workspace.data!.id &&
+      task.intent?.provenance?.session?.kind === "host" &&
+      (task.intent.provenance.session as { host?: unknown; handle?: unknown }).host === host &&
+      (task.intent.provenance.session as { host?: unknown; handle?: unknown }).handle === actor,
+  );
+  if (matches.length !== 1) return null;
+  const resolved = resolveAutoApproval(store.root);
+  if (resolved.status !== "on") return null;
+  return {
+    task: matches[0],
+    workspaceId: workspace.data.id,
+    workspaceRevision: workspace.data.revision,
+    cls,
+    workspaceName: resolved.workspace,
+  };
+};
+
+/**
+ * Shared adapter path: resolve one gated operation under the workspace
+ * standing rule without asking. Returns the exact binding the runner needs
+ * for reserve/settle, or null when anything is uncovered, ambiguous, or
+ * unresolvable — callers fall through to the question proposal.
+ *
+ * Single active task per session (ambiguity asks), plan-before-mutation
+ * (no task asks), guardrails enforced at record time, revocation instant.
+ */
+export const standingAutoBinding = (
+  core: WorkitCore,
+  store: TaskStore,
+  host: string,
+  actor: string,
+  operation: string,
+): StandingAutoBinding | null => {
+  let descriptor: { operation?: unknown };
+  try {
+    descriptor = JSON.parse(operation) as { operation?: unknown };
+  } catch {
+    return null;
+  }
+  const cls = operationAutoClass(descriptor.operation);
+  if (!cls || !autoApproves(store.root, cls)) return null;
+  const applies = standingAutoApplies(store, host, actor, operation);
+  if (!applies) return null;
+  const { task } = applies;
+  const resolved = resolveAutoApproval(store.root);
+  if (resolved.status !== "on") return null;
+  const presented =
+    `Workit decision: action — auto-approved ${String(descriptor.operation)} ` +
+    `under workspace rule "${resolved.workspace}" (no question asked).`;
+  const recorded = core.observeStandingDecision({
+    schemaVersion: 1,
+    action: "record",
+    taskId: task.id,
+    expectedRevision: task.revision,
+    purpose: "action",
+    binding: {
+      taskId: task.id,
+      workspaceId: applies.workspaceId,
+      scope: task.intent.data.scope,
+      presented,
+      approvedContent: operation,
+      contentRefs: [],
+      standing: { workspace: resolved.workspace, class: cls },
+    },
+    response: "approved",
+    requirementIds: [],
+  });
+  if (!recorded.ok) return null;
+  const fresh = store.readTask(task.id);
+  if (!fresh.ok) return null;
+  return {
+    taskId: task.id,
+    decisionId: recorded.data.id,
+    binding: recorded.data.data.binding,
+    expectedRevision: fresh.data.revision,
+    expectedWorkspaceRevision: applies.workspaceRevision,
+  };
+};

package/src/core/branch.ts

@@ -18,6 +18,50 @@ const policy = (root: string) => resolveBranchPolicyFor(root);
 const allowedBranch = (root: string, name: string) =>
   policy(root).allowed.some((r) => r.test(name));
 const isProtected = (root: string, name: string) => policy(root).protected.has(name.toLowerCase());
+
+/** Public guardrail: protected refs fail closed anywhere, never ask. */
+export const isProtectedTarget = (root: string, name: string): boolean => {
+  try {
+    return isProtected(root, name);
+  } catch {
+    return true;
+  }
+};
+
+/**
+ * Push identity check as code: the credential actually used must belong to
+ * the workspace area account. Anything unresolvable fails closed — an
+ * unreachable host never reads as a match.
+ */
+export const verifyPushIdentity = (
+  root: string,
+  provider: string,
+  account: string,
+): { ok: true } | { ok: false; error: string } => {
+  if (!account || typeof account !== "string")
+    return { ok: false, error: "push identity requires a configured area account" };
+  const probe =
+    provider === "gitlab"
+      ? (["api", "user", "--jq", ".username"] as const)
+      : (["api", "user", "--jq", ".login"] as const);
+  const bin = provider === "gitlab" ? "glab" : "gh";
+  let login: string;
+  try {
+    login = execFileSync(bin, [...probe], {
+      cwd: root,
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+  } catch {
+    return { ok: false, error: `${bin} identity could not be resolved` };
+  }
+  if (!login || login.toLowerCase() !== account.toLowerCase())
+    return {
+      ok: false,
+      error: `push identity ${login || "(unknown)"} does not match area account ${account}`,
+    };
+  return { ok: true };
+};
 // RL-01: malformed vcs.json blocks branch resolution with an exact-path error.
 const baseBranch = (cwd: string): { base: string } | { error: string } => {
   const resolved = vcsConfig("resolve", cwd);
@@ -281,6 +325,43 @@ export type BranchSetupResult =
   | { error: string; phase: "preflight" | "post_mutation" };
 
 // Port of scripts/branch/setup-branch.sh
+export type BranchDirt = "clean" | "carry" | "stash-required";
+
+/**
+ * Classify working-tree dirt for branch setup. Untracked files ride along
+ * (`git switch -c` never touches them), and tracked modifications confined
+ * to `docs/` are branch-owned by construction in this workflow — both
+ * auto-carry with no stash question. Anything else keeps the stash-bound
+ * proposal, since the base-checkout sequence could disturb it. Any
+ * inspection failure reads as clean so a broken git surfaces at its own
+ * error instead of inventing a stash demand.
+ */
+export const classifyBranchDirt = (workspaceRoot: string): BranchDirt => {
+  let raw: string;
+  try {
+    raw = execFileSync("git", ["status", "--porcelain=v1"], {
+      cwd: path.resolve(workspaceRoot),
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+  } catch {
+    return "clean";
+  }
+  let dirty = false;
+  for (const line of raw.split("\n")) {
+    if (!line.trim()) continue;
+    dirty = true;
+    const code = line.slice(0, 2);
+    if (code === "??") continue;
+    let entry = line.slice(3);
+    const arrow = entry.indexOf(" -> ");
+    if (arrow >= 0) entry = entry.slice(arrow + 4);
+    const unquoted = entry.startsWith('"') && entry.endsWith('"') ? entry.slice(1, -1) : entry;
+    if (unquoted !== "docs" && !unquoted.startsWith("docs/")) return "stash-required";
+  }
+  return dirty ? "carry" : "clean";
+};
+
 export const branchSetup = ({
   action,
   sdd_dir,
@@ -398,7 +479,7 @@ export const branchSetup = ({
   };
   if (current !== target) {
     const dirty = Boolean(gitContext(cwd).status_short.trim());
-    if (dirty && stash !== "yes") {
+    if (classifyBranchDirt(cwd) === "stash-required" && stash !== "yes") {
       return {
         error:
           "dirty working tree — ask with native question, then call workit_branch_setup with stash=yes",
@@ -416,7 +497,7 @@ export const branchSetup = ({
         return { error: ready.error ?? "ensure-base-branch failed", phase: "preflight" };
       validatedBase = base;
     }
-    if (dirty) {
+    if (dirty && stash === "yes") {
       try {
         exec(["stash", "push", "-u", "-m", `workit: pre-checkout ${target}`]);
       } catch (error) {

package/src/core/doctor.ts

@@ -22,6 +22,7 @@ import {
 import os from "node:os";
 import path from "node:path";
 import { SUPPORT_MATRIX } from "./support-matrix";
+import { bundleHashOfFile, isEphemeralCachePath } from "./runtime-identity";
 import { EVENT } from "./boundary";
 import { getDiagnosticLogger, isConfigObject } from "./config";
 import { packageRoot } from "./package-root";
@@ -682,12 +683,7 @@ const checkUtility = (res: Resolved): DoctorCheck => {
 const isFragileCachePin = (entry: string): boolean => {
   const n = entry.replaceAll("\\", "/").toLowerCase();
   if (!n.startsWith("file:")) return false;
-  return (
-    n.includes("/caches/pnpm/dlx/") ||
-    n.includes("/_npx/") ||
-    n.includes("/.pacquet/") ||
-    n.includes("/library/caches/pnpm/")
-  );
+  return isEphemeralCachePath(entry);
 };
 
 const staleEntry = (entry: string): "ok" | "stale" | "missing-file" | "fragile-cache" => {
@@ -936,12 +932,7 @@ const checkStaleInstall = (res: Resolved): DoctorCheck & { registryProbed?: bool
     } catch {
       target = "(unreadable)";
     }
-    const n = target.replaceAll("\\", "/").toLowerCase();
-    const fragile =
-      n.includes("/caches/pnpm/dlx/") ||
-      n.includes("/_npx/") ||
-      n.includes("/.pacquet/") ||
-      n.includes("/library/caches/pnpm/");
+    const fragile = isEphemeralCachePath(target);
     return {
       id: "stale_install",
       status: "fail",
@@ -1013,6 +1004,28 @@ const checkStaleInstall = (res: Resolved): DoctorCheck & { registryProbed?: bool
       fix: "Re-run install-cursor-plugin.sh — it refreshes the plugin directory and rewrites the workit MCP/hook entries",
     };
   }
+  // Same version, different bytes: the install was hand-edited or built from
+  // a dirty tree. Version strings cannot see that; the bundle hash can. The
+  // dev dist is byte-deterministic, so a mismatch heals with reinstall.
+  if (localDist && installed !== null && source !== null && res.dev) {
+    const entry = /^node\s+(.+)$/.exec((hookCmd ?? "").trim())?.[1]?.trim() ?? "";
+    const sourceBundle =
+      entry && path.isAbsolute(entry)
+        ? path.join(res.dev, "packages", "workit-cursor", "dist", path.basename(entry))
+        : "";
+    if (entry && sourceBundle) {
+      const installedHash = bundleHashOfFile(entry);
+      const sourceHash = bundleHashOfFile(sourceBundle);
+      if (installedHash !== null && sourceHash !== null && installedHash !== sourceHash) {
+        return {
+          id: "stale_install",
+          status: "fail",
+          detail: `stale_install: installed workit-cursor ${installed} runs different bytes than the current runtime build (${path.basename(entry)} hash mismatch)`,
+          fix: "Re-run install-cursor-plugin.sh — it refreshes the plugin directory with the current build",
+        };
+      }
+    }
+  }
   if (installed !== null && localDist) {
     const expected = registryLatestVersion(res);
     if (expected === null) {