@brainervirus/workit-core 2.1.4 → 2.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainervirus/workit-core",
-  "version": "2.1.4",
+  "version": "2.2.0",
   "private": false,
   "description": "Workit shared core — task, policy, evidence, review, decision, worker, and writer state for agentic coding workflows",
   "keywords": [
@@ -36,6 +36,7 @@
   "type": "module",
   "main": "./src/core.ts",
   "exports": {
+    "./hooks": "./src/hooks/index.ts",
     "./src/*.ts": "./src/*.ts",
     "./src/*": "./src/*.ts",
     "./package.json": "./package.json"
@@ -48,7 +49,7 @@
   },
   "dependencies": {
     "@openclaw/fs-safe": "0.8.1",
-    "zod": "4.5.4"
+    "zod": "4.6.5"
   },
   "engines": {
     "node": ">=24"

package/scripts/analyze-release-scope.ts

@@ -26,11 +26,11 @@ const g = (root: string, args: string[]): string =>
 const SEMVER_TAG = /^v\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/;
 
 export function latestTag(root = process.cwd()): string | null {
-  const out = g(root, ["tag", "--list", "v*", "--sort=-v:refname"])
+  const tag = g(root, ["tag", "--list", "v*", "--sort=-v:refname"])
     .split("\n")
     .map((l) => l.trim())
-    .filter((l) => SEMVER_TAG.test(l));
-  return out[0] ?? null;
+    .find((l) => SEMVER_TAG.test(l));
+  return tag ?? null;
 }
 
 type Level = "major" | "minor" | "patch";

package/scripts/doctor-check.ts

@@ -11,8 +11,7 @@
 import { runDoctor } from "../src/core/doctor";
 
 const hostArg = process.argv[2];
-const host =
-  hostArg === "cursor" ? "cursor" : hostArg === "cli" ? "cli" : "opencode";
+const host = hostArg === "cursor" ? "cursor" : hostArg === "cli" ? "cli" : "opencode";
 const staleOnly = process.argv.includes("--stale");
 const report = runDoctor({ host, installer: true });
 

package/scripts/sync-release-manifests.ts

@@ -31,7 +31,8 @@ export type ManifestSyncResult = { version: string; changed: string[] };
  * are left byte-untouched and omitted from `changed`. Throws on a value that
  * is not a plain release version (`latest`, branches, ranges).
  */
-export function syncManifests(root: string, tagOrVersion: string): ManifestSyncResult {  const match = /^v?(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)$/.exec(tagOrVersion.trim());
+export function syncManifests(root: string, tagOrVersion: string): ManifestSyncResult {
+  const match = /^v?(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)$/.exec(tagOrVersion.trim());
   if (!match) throw new Error(`invalid version tag: ${JSON.stringify(tagOrVersion)}`);
   const version = match[1];
   const changed: string[] = [];
@@ -48,15 +49,14 @@ export function syncManifests(root: string, tagOrVersion: string): ManifestSyncR
 
 /** The newest `v*` tag by descending semver refname order (empty repo throws). */
 function latestReleaseTag(cwd?: string): string {
-  const out = execFileSync("git", ["tag", "--list", "v*", "--sort=-v:refname"], {
+  const tag = execFileSync("git", ["tag", "--list", "v*", "--sort=-v:refname"], {
     cwd,
     encoding: "utf8",
     stdio: ["pipe", "pipe", "pipe"],
   })
     .split("\n")
     .map((line) => line.trim())
-    .filter(Boolean);
-  const tag = out[0];
+    .find(Boolean);
   if (!tag) throw new Error("no v* release tag found — run after the first semantic-release");
   return tag;
 }

package/src/core/authority.ts

@@ -641,7 +641,7 @@ const validateAction = (
   if (input.binding && canonicalJson(input.binding) !== canonicalJson(decision.binding))
     return failure("permission_denied", "action binding does not match the approved decision");
   const content = verifyContentRefs(store, decision.binding);
-  if (!content.ok) return content as Result<never>;
+  if (!content.ok) return content;
   const requestedSteps = parseSteps(decision.binding.approvedContent);
   if (requestedSteps === null)
     return failure("invalid_input", "bounded action steps must be a unique non-empty array");
@@ -679,7 +679,7 @@ export function reserveAction(input: ReserveActionInput): Result<ActionReservati
     input.expectedRevision,
     (current, mutation) => {
       const workspace = input.store.readWorkspace();
-      if (!workspace.ok) return workspace as Result<never>;
+      if (!workspace.ok) return workspace;
       if (!workspace.data) return failure("not_found", "workspace not found");
       if (workspace.data.revision !== input.expectedWorkspaceRevision)
         return failure("revision_conflict", "workspace revision does not match", {
@@ -687,7 +687,7 @@ export function reserveAction(input: ReserveActionInput): Result<ActionReservati
           actualWorkspaceRevision: workspace.data.revision,
         });
       const valid = validateAction(input.store, current, workspace.data.id, input, authority);
-      if (!valid.ok) return valid as Result<never>;
+      if (!valid.ok) return valid;
       const { entry, workflow } = valid.data;
       const existing = entry.data.consumption;
       if (existing?.state === "uncertain")
@@ -736,7 +736,7 @@ export function reserveAction(input: ReserveActionInput): Result<ActionReservati
     },
     input.native?.now,
   );
-  if (!changed.ok) return changed as Result<never>;
+  if (!changed.ok) return changed;
   const workspace = input.store.readWorkspace();
   if (!workspace.ok || !workspace.data)
     return failure("recovery_required", "workspace disappeared after reservation");
@@ -793,7 +793,7 @@ export function settleAction(input: SettleActionInput): Result<Entry<Decision>>
     input.taskRevision,
     (current, mutation) => {
       const workspace = input.store.readWorkspace();
-      if (!workspace.ok) return workspace as Result<never>;
+      if (!workspace.ok) return workspace;
       if (!workspace.data) return failure("not_found", "workspace not found");
       if (
         !authorityMatches(authority, {
@@ -909,7 +909,7 @@ export function settleAction(input: SettleActionInput): Result<Entry<Decision>>
     },
     input.native?.now,
   );
-  if (!changed.ok) return changed as Result<never>;
+  if (!changed.ok) return changed;
   const entry = changed.data.decisions.find((candidate) => candidate.id === input.decisionId);
   if (!entry) return failure("recovery_required", "settled decision disappeared");
   if (outcomeResult) return outcomeResult;
@@ -943,7 +943,7 @@ export function reconcileAction(input: ReconcileActionInput): Result<Entry<Decis
     input.taskRevision,
     (current, mutation) => {
       const workspace = input.store.readWorkspace();
-      if (!workspace.ok) return workspace as Result<never>;
+      if (!workspace.ok) return workspace;
       if (!workspace.data) return failure("not_found", "workspace not found");
       if (authority.workspaceId !== workspace.data.id)
         return failure("permission_denied", "native reconciliation workspace does not match");
@@ -1022,7 +1022,7 @@ export function reconcileAction(input: ReconcileActionInput): Result<Entry<Decis
     },
     input.native?.now,
   );
-  if (!changed.ok) return changed as Result<never>;
+  if (!changed.ok) return changed;
   const entry = changed.data.decisions.find((candidate) => candidate.id === input.decisionId);
   return entry
     ? success(changed.data.revision, input.workspaceRevision, entry)

package/src/core/auto-approval.ts

@@ -172,7 +172,7 @@ export const verifyStandingApproval = (
   if (task.status !== "active")
     return failure("invalid_transition", "only active tasks can authorize actions");
   const workspace = new TaskStore(root).readWorkspace();
-  if (!workspace.ok) return workspace as Result<never>;
+  if (!workspace.ok) return workspace;
   if (!workspace.data || !currentWriterOwnsTask(task, workspace.data, caller))
     return failure("permission_denied", "standing approval requires the current writer session");
   const standing = binding.standing;
@@ -200,8 +200,8 @@ export const verifyStandingApproval = (
   )
     return failure("permission_denied", "standing auto-approval is not live for this operation");
   if (cls === "push") {
-    const workspace = resolveWorkspaceFrom(target, configDir());
-    const provider = workspace?.vcs?.provider;
+    const targetWorkspace = resolveWorkspaceFrom(target, configDir());
+    const provider = targetWorkspace?.vcs?.provider;
     const account = resolved.account;
     if (!provider || !account)
       return failure(
@@ -217,7 +217,7 @@ export const verifyStandingApproval = (
     session: { kind: "host", host: caller.host, handle: caller.actor },
     workerId: null,
     receipts: [standingReceiptFor(target, standing.workspace, cls)],
-  } as Provenance);
+  });
 };
 
 export type StandingAutoBinding = {
@@ -259,8 +259,8 @@ export const standingAutoApplies = (
   const listed = store.listTasks();
   const workspace = store.readWorkspace();
   if (!listed.ok || !workspace.ok || !workspace.data) return null;
-  const task = listed.data.find((task) =>
-    currentWriterOwnsTask(task, workspace.data!, { host, actor }),
+  const task = listed.data.find((entry) =>
+    currentWriterOwnsTask(entry, workspace.data!, { host, actor }),
   );
   if (!task) return null;
   const resolved = resolveAutoApproval(target);

package/src/core/branch.ts

@@ -132,8 +132,8 @@ export const branchPolicySnapshotFor = (workspaceRoot: string) => {
   const source = resolved.provenance.branchPolicy;
   const allowed = branchPolicy.allowed
     .map((pattern) => `${pattern.source}/${pattern.flags}`)
-    .sort();
-  const protectedRefs = [...branchPolicy.protected].map((name) => name.toLowerCase()).sort();
+    .toSorted();
+  const protectedRefs = [...branchPolicy.protected].map((name) => name.toLowerCase()).toSorted();
   const fingerprint = createHash("sha256")
     .update(JSON.stringify({ allowed, protectedRefs, source }))
     .digest("hex");
@@ -675,8 +675,8 @@ export const branchSetup = ({
     targetExists = false;
   }
   if (!targetExists) {
-    const policy = validateBranchNameFor(cwd, target);
-    if (!policy.ok) return { error: policy.error, phase: "preflight" };
+    const namePolicy = validateBranchNameFor(cwd, target);
+    if (!namePolicy.ok) return { error: namePolicy.error, phase: "preflight" };
   }
   if (!targetExists) {
     const baseResolved = baseBranch(cwd);

package/src/core/config-conversion.ts

@@ -70,7 +70,7 @@ export function previewConversion(input: ConversionInput): ConversionPreview {
         allowed?: string[];
         protected?: string[];
       };
-      const preset = (bp.preset ?? "gitflow") as BranchPreset;
+      const preset = bp.preset ?? "gitflow";
       const merged = mergePreset(
         preset,
         {

package/src/core/config.ts

@@ -297,7 +297,7 @@ export const resolveBranchPolicy = (
   integration: "pr" | "merge";
   defaultTargetBranch: string;
 } => {
-  const wp = (workspace?.branchPolicy ?? {}) as Record<string, any>;
+  const wp = workspace?.branchPolicy ?? {};
   // An invalid workspace preset (e.g. a typo) falls back to the global preset,
   // preserving resolution order workspace > global > preset, instead of
   // crashing on PRESETS[preset] (mirrors parseConfigResult's Object.hasOwn).
@@ -345,12 +345,12 @@ export const resolveCommitPolicy = (
   config: ToolkitConfig,
   workspace?: { commitPolicy?: Record<string, any> } | null,
 ): { preset: CommitFlavorPreset; pattern?: string } => {
-  const wp = (workspace?.commitPolicy ?? {}) as Record<string, any>;
+  const wp = workspace?.commitPolicy ?? {};
   if (COMMIT_PRESETS.includes(String(wp.preset ?? ""))) {
     return {
       preset: wp.preset as CommitFlavorPreset,
       ...(typeof wp.pattern === "string" ? { pattern: wp.pattern } : {}),
     };
   }
-  return config.commitPolicy ?? ({ preset: "conventional" } as ToolkitConfig["commitPolicy"]);
+  return config.commitPolicy ?? { preset: "conventional" };
 };

package/src/core/cutover.ts

@@ -217,8 +217,8 @@ const readDirNamesBounded = (
   try {
     for (;;) {
       const entry = handle.readSync();
-      if (!entry) return { names: names.sort(), truncated: false };
-      if (names.length === limit) return { names: names.sort(), truncated: true };
+      if (!entry) return { names: names.toSorted(), truncated: false };
+      if (names.length === limit) return { names: names.toSorted(), truncated: true };
       names.push(entry.name);
     }
   } finally {
@@ -596,8 +596,8 @@ const cutoverInventoryScopes = (
     category: "project-state",
     disposition: "preserve",
   },
-  ...legacyFlowInventoryTargets(paths.workspace, issues).map((path) => ({
-    path,
+  ...legacyFlowInventoryTargets(paths.workspace, issues).map((target) => ({
+    path: target,
     category: "project-history" as const,
     disposition: "preserve" as const,
   })),
@@ -743,7 +743,7 @@ const buildCutoverInventory = (paths: ReturnType<typeof resolvePaths>): CutoverI
     }
     hash.update(`${entry.path}\0${entry.kind}\0${entry.bytes}\0${entry.digest ?? ""}\n`);
   }
-  const issueList = [...issues].sort();
+  const issueList = [...issues].toSorted();
   for (const issue of issueList) hash.update(`!${issue}\n`);
   return {
     complete: issueList.length === 0,
@@ -936,7 +936,7 @@ const readBackupFiles = (
       issues.push(`backup content failed verification: ${entry.path}`);
       continue;
     }
-    files.set(entry.path, { digest: digest as Digest, storagePath });
+    files.set(entry.path, { digest: digest, storagePath });
   }
   return { files, issues };
 };

package/src/core/doctor.ts

@@ -19,6 +19,7 @@ import {
 import os from "node:os";
 import path from "node:path";
 import { SUPPORT_MATRIX } from "./support-matrix";
+import { inspectMetadataLock } from "./store-lock";
 import { bundleHashOfFile, isEphemeralCachePath } from "./runtime-identity";
 import { EVENT } from "./boundary";
 import { getDiagnosticLogger, isConfigObject } from "./config";
@@ -61,6 +62,7 @@ export type DoctorCheckId =
   | "duplicate_registration"
   | "malformed_config"
   | "workspace_mismatch"
+  | "workspace_lock"
   | "credential_metadata"
   | "github_identity"
   | "gitlab_identity"
@@ -110,6 +112,8 @@ export type DoctorOptions = {
   /** Checkout containing packages/ (monorepo or share clone). */
   dev?: string;
   cwd?: string;
+  /** Workit store root for the lock check (default: WORKFLOW_WORKSPACE_ROOT, then cwd). */
+  workspaceRoot?: string;
   opencodeConfig?: string;
   /** OpenCode npm `@latest` package cache root (test seam). */
   opencodePackageCacheDir?: string;
@@ -129,6 +133,7 @@ type Resolved = {
   configDir: string;
   stateDir: string;
   cwd: string;
+  workspaceRoot: string;
   dev: string | null;
   opencodeConfig: string;
   opencodePackageCacheDir: string;
@@ -179,6 +184,7 @@ const resolve = (options: DoctorOptions): Resolved => {
     configDir,
     stateDir,
     cwd,
+    workspaceRoot: options.workspaceRoot ?? env.WORKFLOW_WORKSPACE_ROOT ?? cwd,
     dev,
     opencodeConfig:
       options.opencodeConfig ?? path.join(home, ".config", "opencode", "opencode.json"),
@@ -559,7 +565,8 @@ const registeredCursorLauncher = (res: Resolved): CursorLauncher | null | "inval
 // no version abstraction.
 const canonicalCursorHook = cursorHooksEntry("").command;
 
-const registeredCursorHook = (res: Resolved): string | null | "invalid" => {
+// Returns the registered hook command, null when absent, or "invalid".
+const registeredCursorHook = (res: Resolved): string | null => {
   const hooksFile = path.join(res.cursorPluginDir, "hooks", "hooks-cursor.json");
   if (!existsSync(hooksFile)) return "invalid";
   const config = readJson(hooksFile);
@@ -866,7 +873,7 @@ const checkOpenCodePackageCache = (res: Resolved): DoctorCheck & { registryProbe
       detail: "no workit opencode pin — package cache not inspected",
     };
   }
-  const pin = entries[0]!;
+  const pin = entries[0];
   if (pin.startsWith("file:") || pin.startsWith("git+file:")) {
     return {
       id: "stale_install",
@@ -1318,7 +1325,7 @@ const providerIdentityFinding = (
   provider: "github" | "gitlab",
   surfaces: IdentitySurface[],
 ): DoctorCheck => {
-  const id = `${provider}_identity` as "github_identity" | "gitlab_identity";
+  const id: "github_identity" | "gitlab_identity" = `${provider}_identity`;
   const label = provider === "github" ? "GitHub" : "GitLab";
   const resolved = surfaces.filter(
     (entry): entry is { surface: string; login: string } => typeof entry.login === "string",
@@ -1692,6 +1699,44 @@ const checkManagedContentConflict = (res: Resolved): DoctorCheck => {
   };
 };
 
+// The checkout's `.workit/metadata.lock`. Writes reclaim a stale lock by
+// themselves, so a stale lock is a warning with an explicit cleanup command.
+const BLOCKING_LOCK_WARN_MS = 30_000;
+const checkWorkspaceLock = (res: Resolved): DoctorCheck => {
+  const lock = inspectMetadataLock(res.workspaceRoot);
+  const fix = "workit doctor --fix-lock";
+  if (lock.guard === "abandoned")
+    return {
+      id: "workspace_lock",
+      status: "warn",
+      detail: `abandoned lock reclaim guard at ${lock.path}.reclaim`,
+      fix,
+    };
+  if (lock.state === "absent")
+    return { id: "workspace_lock", status: "pass", detail: "no metadata lock held" };
+  if (lock.state === "stale")
+    return {
+      id: "workspace_lock",
+      status: "warn",
+      detail: `stale metadata lock at ${lock.path}: ${lock.reason}`,
+      fix,
+    };
+  // An unverifiable owner (other host, pid namespace, or an older Workit's
+  // lock) that has blocked writes this long needs an explicit decision.
+  if (lock.state === "unknown" && (lock.ageMs ?? 0) > BLOCKING_LOCK_WARN_MS)
+    return {
+      id: "workspace_lock",
+      status: "warn",
+      detail: `metadata lock at ${lock.path} has blocked writes for ${Math.round((lock.ageMs ?? 0) / 1000)}s and its owner cannot be verified: ${lock.reason}`,
+      fix: "workit doctor --fix-lock --force --yes",
+    };
+  return {
+    id: "workspace_lock",
+    status: "pass",
+    detail: `metadata lock ${lock.reason} (writes retry, then report busy)`,
+  };
+};
+
 const RUN_CHECKS: Array<(res: Resolved) => DoctorCheck> = [
   checkRuntime,
   checkVersions,
@@ -1704,6 +1749,7 @@ const RUN_CHECKS: Array<(res: Resolved) => DoctorCheck> = [
   checkDuplicateRegistration,
   checkMalformedConfig,
   checkWorkspaceMismatch,
+  checkWorkspaceLock,
   checkCredentialMetadata,
   checkGithubIdentity,
   checkGitLabIdentity,

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

@@ -86,9 +86,9 @@ const stagedPaths = (root: string): string[] | null => {
     const rename = /^(?:R|C)\d{3}$/.test(status);
     const count = rename ? 2 : 1;
     for (let offset = 0; offset < count; offset += 1) {
-      const path = tokens[index++];
-      if (!path) return null;
-      paths.push(path);
+      const filePath = tokens[index++];
+      if (!filePath) return null;
+      paths.push(filePath);
     }
   }
   return [...new Set(paths)];
@@ -258,8 +258,8 @@ export const assertLocalExternalActionWriter = (
   const store = new TaskStore(root);
   const listed = store.listTasks();
   const workspace = store.readWorkspace();
-  if (!listed.ok) return listed as Result<never>;
-  if (!workspace.ok) return workspace as Result<never>;
+  if (!listed.ok) return listed;
+  if (!workspace.ok) return workspace;
   if (!workspace.data) return failure("not_found", "workspace not found");
   if (
     expectedWorkspaceRevision !== undefined &&
@@ -317,7 +317,7 @@ const branchCreationBaseline = (
     };
   const remote = run(root, ["ls-remote", "origin", `refs/heads/${base}`]);
   const sha = remote.exitCode === 0 ? remote.stdout.trim().split(/\s+/)[0] : "";
-  const remoteBase = /^[0-9a-f]{40}$/.test(sha ?? "") ? (sha as string) : null;
+  const remoteBase = /^[0-9a-f]{40}$/.test(sha ?? "") ? sha : null;
   return {
     base_branch: base,
     target_exists: false,
@@ -717,7 +717,7 @@ const mergedBranch = (root: string, branch: string): Result<Record<string, strin
       },
     );
   const live = remoteBranchTip(root, provider, auth.host, repo, branch);
-  if (!live.ok) return live as Result<never>;
+  if (!live.ok) return live;
   const tip = live.data;
   if (!tip)
     return failure("invalid_input", "remote branch is absent or could not be read", {
@@ -978,8 +978,8 @@ export const readYouTrackAction = async (
     const creds = youTrackToken();
     if ("error" in creds || creds.base !== baseUrl) return unknownHostingEvidence(operation);
     const bounded = "&$top=100&$skip=0";
-    const read = async (path: string): Promise<unknown[] | null> => {
-      const result = await youTrackRequest(`${baseUrl}${path}${bounded}`, {
+    const read = async (endpoint: string): Promise<unknown[] | null> => {
+      const result = await youTrackRequest(`${baseUrl}${endpoint}${bounded}`, {
         method: "GET",
         token: creds.token,
       });
@@ -1670,7 +1670,7 @@ const resolveExternalActionAtRoot = (
               request,
               descriptorPayload: { ...request.payload, resolved: checked.data },
             })
-          : (checked as Result<never>);
+          : checked;
       }
       case "changelog.apply": {
         const preview = changelogApplyPreview({ ...request.payload, workspace_root: root });
@@ -1707,7 +1707,7 @@ const resolveExternalActionAtRoot = (
           return failure("invalid_input", "youtrack.time requires an explicit dateMs");
         {
           const available = youTrackWritePreflight();
-          if (!available.ok) return available as Result<ResolvedExternalAction>;
+          if (!available.ok) return available;
           const baseUrl = youTrackBase();
           const date = youTrackWorkDateMs(String(request.payload.dateMs));
           if (!baseUrl)
@@ -1741,7 +1741,7 @@ const resolveExternalActionAtRoot = (
       case "youtrack.update":
       case "youtrack.meeting": {
         const available = youTrackWritePreflight();
-        if (!available.ok) return available as Result<ResolvedExternalAction>;
+        if (!available.ok) return available;
         const baseUrl = youTrackBase();
         const date = youTrackWorkDateMs(
           preservedDateMs === undefined ? "auto" : String(preservedDateMs),
@@ -1787,7 +1787,7 @@ const resolveExternalActionAtRoot = (
       }
       default:
         return success(null, null, {
-          request: request as never,
+          request: request,
           descriptorPayload: (request as unknown as { payload: unknown }).payload,
         });
     }
@@ -1802,7 +1802,7 @@ export const resolveExternalActionRequest = (
   preservedDateMs?: number,
 ): Result<ResolvedExternalAction> => {
   const target = actionRoot(taskRoot, request);
-  if (!target.ok) return target as Result<never>;
+  if (!target.ok) return target;
   const bindTarget = bindsActionTarget(request.operation);
   const normalized = bindTarget
     ? ({ ...request, payload: { ...request.payload, cwd: target.data } } as ExternalActionRequest)
@@ -1909,7 +1909,7 @@ export const executeConcreteExternalAction = async (
       );
     if (!sameDirectoryIdentity(root, coordinationRoot)) {
       const targetWorkspace = new TaskStore(root).readWorkspace();
-      if (!targetWorkspace.ok) return targetWorkspace as Result<never>;
+      if (!targetWorkspace.ok) return targetWorkspace;
       const owner = targetWorkspace.data?.writer?.owner;
       if (
         owner &&

package/src/core/external-action.ts

@@ -210,11 +210,10 @@ export const externalActionSchema = z.discriminatedUnion("operation", [
 export type ExternalActionRequest = z.infer<typeof externalActionSchema>;
 
 /** The complete external-action contract for hosts that register native tools. */
-export const externalActionJsonSchema = (): z.core.JSONSchema.BaseSchema =>
-  ({
-    type: "object",
-    ...z.toJSONSchema(externalActionSchema, { target: "draft-2020-12" }),
-  }) as z.core.JSONSchema.BaseSchema;
+export const externalActionJsonSchema = (): z.core.JSONSchema.BaseSchema => ({
+  type: "object",
+  ...z.toJSONSchema(externalActionSchema, { target: "draft-2020-12" }),
+});
 
 export type ExternalActionOperation = ExternalActionRequest["operation"];
 
@@ -639,7 +638,7 @@ export const chainStepBinding = (
     typeof descriptor.payload?.target_branch === "string"
       ? {
           operation: "git.branch_setup",
-          target: descriptor.payload.target_branch as string,
+          target: descriptor.payload.target_branch,
           cwd: targetRoot,
         }
       : descriptor.operation === "hosting.pull_request"
@@ -947,7 +946,7 @@ export const createAuthorizedExternalActionRunner =
     let latest: ExternalActionResult<T> | undefined;
     for (const step of sequence) {
       const binding = bind(operation);
-      if ("ok" in binding) return binding as ExternalActionResult<T>;
+      if ("ok" in binding) return binding;
       const targetRoot = externalActionTargetRoot(operation, coordinationRoot);
       if (targetRoot === null)
         return failure("capability_unavailable", "external action target could not be locked", {
@@ -960,7 +959,7 @@ export const createAuthorizedExternalActionRunner =
         ? (run) => new TaskStore(targetRoot).withExternalActionLock(run, true)
         : undefined;
       const result = await runAuthorizedExternalAction(
-        { core, ...(binding as Omit<AuthorizedActionInput, "core">), ...(step ? { step } : {}) },
+        { core, ...binding, ...(step ? { step } : {}) },
         (reservation) => effect(step, reservation),
         withActionLock,
       );
@@ -1039,12 +1038,10 @@ export const readNativeExternalActionObservation = (
     actionRef: candidate.actionRef as Ref,
     outcome: candidate.outcome as NativeExternalActionObservation["outcome"],
     ...(candidate.callId === undefined ? {} : { callId: candidate.callId }),
-    ...(candidate.taskRevision === undefined
-      ? {}
-      : { taskRevision: candidate.taskRevision as Revision }),
+    ...(candidate.taskRevision === undefined ? {} : { taskRevision: candidate.taskRevision }),
     ...(candidate.workspaceRevision === undefined
       ? {}
-      : { workspaceRevision: candidate.workspaceRevision as Revision }),
+      : { workspaceRevision: candidate.workspaceRevision }),
   };
 };
 
@@ -1100,7 +1097,7 @@ export async function runAuthorizedExternalAction<T>(
     ...(input.step ? { step: input.step } : {}),
     observation: input.reserveObservation,
   });
-  if (!reserved.ok) return reserved as ExternalActionResult<T>;
+  if (!reserved.ok) return reserved;
 
   const settle = (
     outcome: "succeeded" | "not_started" | "unknown",
@@ -1149,7 +1146,7 @@ export async function runAuthorizedExternalAction<T>(
       effectValue = await effect(reserved.data);
     } catch {
       const settled = settleWithRefresh("unknown", settle("unknown"));
-      if (!settled.ok) return settled as ExternalActionResult<T>;
+      if (!settled.ok) return settled;
       return failure("external_outcome_unknown", "external action outcome is unknown", {
         operation: "external_action",
         outcome: "unknown",
@@ -1161,7 +1158,7 @@ export async function runAuthorizedExternalAction<T>(
       "ok" in effectValue &&
       typeof (effectValue as { ok?: unknown }).ok === "boolean"
     ) {
-      const contract = effectValue as Result<T>;
+      const contract = effectValue;
       if (!contract.ok) {
         const preflight =
           typeof contract.details === "object" &&
@@ -1169,13 +1166,13 @@ export async function runAuthorizedExternalAction<T>(
           (contract.details as Record<string, unknown>).outcome === "not_started";
         const outcome = input.failureOutcome ?? (preflight ? "not_started" : "unknown");
         const settled = settleWithRefresh(outcome, settle(outcome));
-        if (!settled.ok) return settled as ExternalActionResult<T>;
+        if (!settled.ok) return settled;
         return contract;
       }
       effectValue = contract.data;
     }
     const settled = settleWithRefresh("succeeded", settle("succeeded"));
-    if (!settled.ok) return settled as ExternalActionResult<T>;
+    if (!settled.ok) return settled;
     return {
       ok: true,
       schemaVersion: 1,
@@ -1194,14 +1191,14 @@ export async function runAuthorizedExternalAction<T>(
         outcome: "unknown",
       });
     const settled = settleWithRefresh("not_started", settle("not_started"));
-    if (!settled.ok) return settled as ExternalActionResult<T>;
+    if (!settled.ok) return settled;
     return failure("writer_conflict", "target checkout was unavailable before the effect", {
       outcome: "not_started",
     });
   }
   if (!effectStarted) {
     const settled = settleWithRefresh("not_started", settle("not_started"));
-    if (!settled.ok) return settled as ExternalActionResult<T>;
+    if (!settled.ok) return settled;
   }
   return result;
 }

package/src/core/logger.ts

@@ -216,8 +216,8 @@ const pruneOldFiles = (dir: string): void => {
   try {
     const files = readdirSync(dir)
       .filter((name) => DAY_FILE.test(name))
-      .sort()
-      .reverse();
+      .toSorted()
+      .toReversed();
     for (const file of files.slice(RETAINED_DAYS)) {
       try {
         unlinkSync(path.join(dir, file));

package/src/core/methods.ts

@@ -110,6 +110,11 @@ Start a record once for an explicit tracked objective; assess or reassess only
 when policy selection or changed evidence/constraints requires it. Omitted
 expectedRevision and expectedWorkspaceRevision use current values; explicit
 values are still concurrency-checked, so never copy revisions between calls.
+A busy result means another live Workit call holds the checkout lock: retry the
+same call; it is not a recovery condition. A lock left by a dead process is
+reclaimed on the next write, and \`workit doctor --fix-lock\` clears it on demand.
+A revision_conflict on a call that omitted expectedRevision is contention too:
+re-read the record and retry the call.
 A solo edit does not need writer acquisition; use it when concurrent checkout
 writers need coordination. Record only observed facts and checks. Evidence can
 become stale when its bound candidate changes; reconcile findings against the