@brainervirus/workit-core 1.0.10 → 1.0.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainervirus/workit-core",
-  "version": "1.0.10",
+  "version": "1.0.12",
   "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

@@ -181,12 +181,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 +240,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 = (
@@ -543,22 +590,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/branch.ts

@@ -281,6 +281,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 +435,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 +453,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) {

package/src/core/external-action-effects.ts

@@ -1,4 +1,9 @@
-import { branchSetup, resolveBranchPolicyFor, resolveCommitPolicyFor } from "./branch";
+import {
+  branchSetup,
+  classifyBranchDirt,
+  resolveBranchPolicyFor,
+  resolveCommitPolicyFor,
+} from "./branch";
 import { hostingCliAvailable, prCreate } from "./pr-create";
 import {
   changelogContext,
@@ -24,6 +29,7 @@ import { failure, success, sha256, type Caller, type Result, type Ref } from "./
 import { changelogApply, changelogApplyPreview } from "./changelog";
 import type { ExternalActionRequest } from "./external-action";
 import { externalActionDescriptor, externalActionRequest } from "./external-action";
+import { normalizeChainSteps } from "./authority";
 import { resolveInside, run as coreRun } from "../core";
 import { vcsConfig } from "./vcs-config";
 import { detectCommitFlavor, matchCommitFlavor, type CommitFlavor } from "./commit-flavors";
@@ -271,10 +277,33 @@ export const actionProposalQuestion = (
   const resolved = (payload.resolved ?? {}) as Record<string, unknown>;
   const payloadTarget = String(payload.target_branch ?? "");
   if (request.operation === "git.commit" && Array.isArray(payload.plan_steps)) {
-    const steps = payload.plan_steps as string[];
+    const steps = payload.plan_steps as unknown[];
+    const chain = normalizeChainSteps(steps);
+    if (!chain)
+      return {
+        presented: `Workit decision: action — Approve committing the plan's listed tasks?`,
+        approvedText: `Approve the listed plan commits.`,
+      };
+    const kinds = chain.map((step) => step.kind);
+    if (kinds.every((kind) => kind === "commit"))
+      return {
+        presented: `Workit decision: action — Approve committing the plan's ${steps.length} listed tasks on \`${String(payload.plan_branch ?? "")}\`?`,
+        approvedText: `Approve the ${steps.length} listed plan commits.`,
+      };
+    const summary = [
+      kinds.filter((kind) => kind === "branch").length
+        ? `${kinds.filter((kind) => kind === "branch").length} branch`
+        : null,
+      kinds.filter((kind) => kind === "commit").length
+        ? `${kinds.filter((kind) => kind === "commit").length} commits`
+        : null,
+      kinds.includes("pr") ? "PR" : null,
+    ]
+      .filter(Boolean)
+      .join(", ");
     return {
-      presented: `Workit decision: action — Approve committing the plan's ${steps.length} listed tasks on \`${String(payload.plan_branch ?? "")}\`?`,
-      approvedText: `Approve the ${steps.length} listed plan commits.`,
+      presented: `Workit decision: action — Approve the ${steps.length}-step chain on \`${String(payload.plan_branch ?? "")}\` (${summary})?`,
+      approvedText: `Approve the ${steps.length}-step chain (${summary}).`,
     };
   }
   switch (request.operation) {
@@ -286,16 +315,29 @@ export const actionProposalQuestion = (
           approvedText: "Reapply the recorded stash.",
         };
       const target = String(payload.target_branch ?? "");
+      // A dirty tree binds stash: the approval carries the stash through,
+      // so the question names it instead of failing later at preflight.
+      const stashes = payload.stash === "yes" && resolved.dirty === true;
       if (resolved.target_exists === true)
-        return {
-          presented: `Workit decision: action — Switch to branch \`${target}\`?`,
-          approvedText: `Switch to \`${target}\`.`,
-        };
+        return stashes
+          ? {
+              presented: `Workit decision: action — Stash the dirty working tree and switch to branch \`${target}\`?`,
+              approvedText: `Stash and switch to \`${target}\`.`,
+            }
+          : {
+              presented: `Workit decision: action — Switch to branch \`${target}\`?`,
+              approvedText: `Switch to \`${target}\`.`,
+            };
       const base = String(resolved.base_branch ?? "the base branch");
-      return {
-        presented: `Workit decision: action — Create branch \`${target}\` from \`${base}\` (currently ${shortSha(resolved.remote_base)})?`,
-        approvedText: `Create \`${target}\` from \`${base}\` at ${shortSha(resolved.remote_base)}.`,
-      };
+      return stashes
+        ? {
+            presented: `Workit decision: action — Stash the dirty working tree and create branch \`${target}\` from \`${base}\` (currently ${shortSha(resolved.remote_base)})?`,
+            approvedText: `Stash and create \`${target}\` from \`${base}\` at ${shortSha(resolved.remote_base)}.`,
+          }
+        : {
+            presented: `Workit decision: action — Create branch \`${target}\` from \`${base}\` (currently ${shortSha(resolved.remote_base)})?`,
+            approvedText: `Create \`${target}\` from \`${base}\` at ${shortSha(resolved.remote_base)}.`,
+          };
     }
     case "git.commit": {
       const paths = Array.isArray(resolved.paths) ? (resolved.paths as string[]) : [];
@@ -793,6 +835,32 @@ const youTrackWritePreflight = (): Result<null> => {
   return success(null, null, null);
 };
 
+/**
+ * A dirty tree binds stash up front so the proposal names it and one
+ * approval carries the whole effect instead of failing at preflight.
+ * Carry-class dirt (untracked or docs-confined) rides along silently.
+ * Returns the original resolution untouched unless an upgrade applies.
+ */
+export const upgradeBranchSetupForStash = (
+  root: string,
+  parsed: ExternalActionRequest,
+  resolved: Result<ResolvedExternalAction>,
+): Result<ResolvedExternalAction> => {
+  if (!resolved.ok || resolved.data.request.operation !== "git.branch_setup") return resolved;
+  if (
+    (resolved.data.descriptorPayload as { resolved?: { dirty?: unknown } }).resolved?.dirty !==
+      true ||
+    (resolved.data.descriptorPayload as { stash?: unknown }).stash === "yes" ||
+    classifyBranchDirt(root) !== "stash-required"
+  )
+    return resolved;
+  const upgraded = resolveExternalActionRequest(root, {
+    ...parsed,
+    payload: { ...(parsed.payload as Record<string, unknown>), stash: "yes" },
+  } as typeof parsed);
+  return upgraded.ok ? upgraded : resolved;
+};
+
 export const resolveExternalActionRequest = (
   root: string,
   request: ExternalActionRequest,
@@ -859,26 +927,41 @@ export const resolveExternalActionRequest = (
         if (!head) return failure("storage_error", "Git state could not be resolved");
         const branch = gitValue(root, ["branch", "--show-current"]);
         if (planSteps !== undefined || planBranch !== undefined) {
-          if (
-            !Array.isArray(planSteps) ||
-            planSteps.some((step) => typeof step !== "string" || !step.trim()) ||
-            new Set(planSteps).size !== planSteps.length ||
-            planSteps.length === 0 ||
-            planSteps.length > 32
-          )
+          const chain = Array.isArray(planSteps) ? normalizeChainSteps(planSteps) : null;
+          if (!chain)
             return failure(
               "invalid_input",
-              "plan_steps must be 1-32 unique non-empty commit messages",
+              "plan_steps must be 1-32 unique non-empty commit messages, branch targets, or pull_request markers",
               {
                 outcome: "not_started",
-                fields: [{ path: "plan_steps", reason: "unique strings" }],
+                fields: [{ path: "plan_steps", reason: "unique steps" }],
               },
             );
-          if (typeof planBranch !== "string" || !planBranch.trim() || planBranch !== branch)
-            return failure("invalid_input", "plan_branch must name the current working branch", {
+          if (typeof planBranch !== "string" || !planBranch.trim())
+            return failure("invalid_input", "plan_branch must name the working branch", {
               outcome: "not_started",
-              fields: [{ path: "plan_branch", reason: "current branch" }],
+              fields: [{ path: "plan_branch", reason: "required" }],
             });
+          // A chain that creates its own branch names that branch; otherwise
+          // the plan runs on the branch already checked out.
+          const first = chain[0];
+          const createsBranch = first?.kind === "branch";
+          if (createsBranch ? planBranch !== first.target : planBranch !== branch)
+            return failure(
+              "invalid_input",
+              createsBranch
+                ? "plan_branch must name the branch the chain creates"
+                : "plan_branch must name the current working branch",
+              {
+                outcome: "not_started",
+                fields: [
+                  {
+                    path: "plan_branch",
+                    reason: createsBranch ? "chain branch" : "current branch",
+                  },
+                ],
+              },
+            );
           if (isProtectedBranch(root, planBranch))
             return failure("invalid_input", "plan_branch must not be a protected branch", {
               outcome: "not_started",