@brainervirus/workit-core 2.1.4 → 2.2.0

package/src/core/policy-resolver.ts

@@ -76,10 +76,13 @@ const compareCodeUnits = (left: string, right: string): number => {
   return left.length - right.length;
 };
 
-const stableUnique = (values: string[]): string[] => [...new Set(values)].sort(compareCodeUnits);
+const stableUnique = (values: string[]): string[] =>
+  [...new Set(values)].toSorted(compareCodeUnits);
 
 const stableList = <T>(values: T[]): T[] =>
-  [...values].sort((left, right) => compareCodeUnits(canonicalJson(left), canonicalJson(right)));
+  [...values].toSorted((left, right) =>
+    compareCodeUnits(canonicalJson(left), canonicalJson(right)),
+  );
 
 const normalizedScope = (scope: Scope): Scope => ({
   description: scope.description,
@@ -463,10 +466,10 @@ export function diffPolicy(
   if (!policySchema.safeParse(previous).success && previous !== null)
     throw new TypeError("previous policy is invalid");
   if (!policySchema.safeParse(next).success) throw new TypeError("next policy is invalid");
-  const oldIds = new Set(previous?.requirements.map((requirement) => requirement.id) ?? []);
-  const newIds = new Set(next.requirements.map((requirement) => requirement.id));
-  const added = [...newIds].filter((id) => !oldIds.has(id)).sort(compareCodeUnits);
-  const retired = [...oldIds].filter((id) => !newIds.has(id)).sort(compareCodeUnits);
+  const oldIds = new Set(previous?.requirements.map((item) => item.id) ?? []);
+  const newIds = new Set(next.requirements.map((item) => item.id));
+  const added = [...newIds].filter((id) => !oldIds.has(id)).toSorted(compareCodeUnits);
+  const retired = [...oldIds].filter((id) => !newIds.has(id)).toSorted(compareCodeUnits);
   if (added.length === 0 && retired.length === 0) return null;
   const normalizedReason = reason.trim();
   const changeReason = retired.length

package/src/core/registration.ts

@@ -138,9 +138,7 @@ export function mergeCursorMcp(
   server: Record<string, unknown>,
 ): MergeResult<Record<string, unknown>> {
   const base = isRecord(mcp) ? { ...mcp } : {};
-  const servers = isRecord(base.mcpServers)
-    ? { ...(base.mcpServers as Record<string, unknown>) }
-    : {};
+  const servers = isRecord(base.mcpServers) ? { ...base.mcpServers } : {};
   delete servers["workflow-toolkit"]; // legacy duplicate registration
   servers[serverName] = server;
   const changed = JSON.stringify(servers) !== JSON.stringify(base.mcpServers) ? ["mcpServers"] : [];
@@ -157,7 +155,7 @@ export function mergeCursorHooks(
   sessionStartEntry: Record<string, unknown>,
 ): MergeResult<Record<string, unknown>> {
   const base: Record<string, unknown> = isRecord(hooks) ? { ...hooks } : { version: 1 };
-  const hooksMap = isRecord(base.hooks) ? { ...(base.hooks as Record<string, unknown>) } : {};
+  const hooksMap = isRecord(base.hooks) ? { ...base.hooks } : {};
   const changed: string[] = [];
   const list = Array.isArray(hooksMap.sessionStart) ? hooksMap.sessionStart : [];
   const same =
@@ -223,7 +221,7 @@ const canonicalHookEntry = (
  */
 export function cursorHookDrift(installed: unknown): string[] {
   if (!isRecord(installed) || !isRecord(installed.hooks)) return ["hooks file is not a hook map"];
-  const hooks = installed.hooks as Record<string, unknown>;
+  const hooks = installed.hooks;
   const drift: string[] = [];
   for (const event of ["preToolUse", "beforeShellExecution"] as const) {
     const list = hooks[event];

package/src/core/repo-context.ts

@@ -258,7 +258,7 @@ export const documentationFiles = (cwd: string): string[] => {
     }
   };
   walk(cwd, 1);
-  return matches.sort().slice(0, 200);
+  return matches.toSorted().slice(0, 200);
 };
 
 const readTrimmed = (file: string, maxLines: number): string => {

package/src/core/setup.ts

@@ -506,13 +506,13 @@ type ResolvedApply = {
 // the same options (defaulting both from env) — tests pass `home` explicitly.
 const resolveSetupPaths = (
   options: ApplySetupOptions,
-  configDir: string,
+  resolvedConfigDir: string,
 ): Omit<ResolvedApply, "dev"> => {
   const env = options.env ?? process.env;
   const home = options.home ?? env.HOME ?? os.homedir();
   return {
     home,
-    configDir,
+    configDir: resolvedConfigDir,
     cwd: options.cwd ?? process.cwd(),
     env,
     opencodeConfig:

package/src/core/skill-manifests.ts

@@ -41,7 +41,7 @@ export const skillManifestNames = (root: string): string[] =>
   existsSync(root)
     ? readdirSync(root)
         .filter((name) => existsSync(path.join(root, name, "SKILL.md")))
-        .sort()
+        .toSorted()
     : [];
 
 export const validateSkillManifests = (

package/src/core/store-lock.ts

@@ -0,0 +1,301 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import { hostname } from "node:os";
+import path from "node:path";
+import * as z from "zod";
+import { canonicalJson } from "./task-contract";
+
+/**
+ * Ownership rules for a checkout's `.workit/metadata.lock`.
+ *
+ * The lock is a short mutex around one store mutation (or one managed effect).
+ * A lock whose owner is gone is reclaimed automatically; a lock whose owner is
+ * alive is contention, which callers report as retryable `busy`.
+ */
+
+export type MetadataLock = {
+  pid: number;
+  processStart: string | null;
+  host: string;
+  nonce: string;
+  externalAction?: true;
+};
+
+const metadataLockSchema = z
+  .object({
+    pid: z.number().int().nonnegative().safe(),
+    processStart: z.string().nullable(),
+    host: z.string().min(1),
+    nonce: z.string().min(1),
+    externalAction: z.literal(true).optional(),
+  })
+  .strict();
+
+/** A lock from another host cannot be checked for liveness; trust it this long. */
+export const FOREIGN_LOCK_TTL_MS = 10 * 60_000;
+/** An empty or unparseable lock is a writer mid-create; after this it is debris. */
+export const UNREADABLE_LOCK_TTL_MS = 30_000;
+/** A reclaim guard lives for microseconds; one older than this was abandoned. */
+export const RECLAIM_GUARD_TTL_MS = 30_000;
+/**
+ * Total time a mutation waits for a live holder before returning `busy`. The
+ * wait blocks the calling thread, so in-process hosts (OpenCode, MCP, Pi) keep
+ * the short default; the CLI raises it for its own process.
+ */
+let defaultLockTimeoutMs = 250;
+export const defaultLockTimeout = (): number => defaultLockTimeoutMs;
+export const setDefaultLockTimeout = (ms: number): void => {
+  defaultLockTimeoutMs = ms;
+};
+
+export const parseMetadataLock = (raw: string): MetadataLock => {
+  let value: unknown;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    throw Object.assign(new Error("metadata lock is invalid"), { code: "metadata_lock_invalid" });
+  }
+  const parsed = metadataLockSchema.safeParse(value);
+  if (!parsed.success)
+    throw Object.assign(new Error("metadata lock is invalid"), { code: "metadata_lock_invalid" });
+  return parsed.data;
+};
+
+/** Lenient variant for the acquire loop: an unreadable lock is classified by age. */
+export const parseMetadataLockOrNull = (raw: string): MetadataLock | null => {
+  try {
+    return parseMetadataLock(raw);
+  } catch {
+    return null;
+  }
+};
+
+export const sameMetadataLock = (left: unknown, right: MetadataLock): boolean => {
+  const parsed = metadataLockSchema.safeParse(left);
+  return parsed.success && canonicalJson(parsed.data) === canonicalJson(right);
+};
+
+/** Field 22 (starttime) of /proc/<pid>/stat; parsed after the last ")" so a comm with spaces cannot shift it. */
+export const parseProcStatStart = (stat: string): string | null => {
+  const close = stat.lastIndexOf(")");
+  if (close < 0) return null;
+  // After ")": field 3 (state) is index 0, so field 22 is index 19.
+  return (
+    stat
+      .slice(close + 1)
+      .trim()
+      .split(/\s+/)[19] ?? null
+  );
+};
+
+export const processStartOf = (pid: number): string | null => {
+  if (process.platform === "linux") {
+    try {
+      return parseProcStatStart(fs.readFileSync(`/proc/${pid}/stat`, "utf8"));
+    } catch {
+      return null;
+    }
+  }
+  if (process.platform === "darwin" || process.platform === "freebsd") {
+    try {
+      const run = spawnSync("ps", ["-o", "lstart=", "-p", String(pid)], {
+        encoding: "utf8",
+        timeout: 1_000,
+      });
+      const value = run.status === 0 ? run.stdout.trim() : "";
+      return value || null;
+    } catch {
+      return null;
+    }
+  }
+  return null;
+};
+
+const readTrimmed = (file: string): string | null => {
+  try {
+    return fs.readFileSync(file, "utf8").trim() || null;
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Identity of the pid space this process lives in: hostname plus, on Linux,
+ * the pid-namespace inode and boot id. Containers that share the hostname
+ * (`--network host`) but not the pid namespace get a different identity, so
+ * their pids are never checked against this process table. Folded into the
+ * existing `host` string so older Workit versions still parse the lock.
+ */
+let cachedLockHost: string | null = null;
+export const localLockHost = (): string => {
+  if (cachedLockHost !== null) return cachedLockHost;
+  let pidns: string | null = null;
+  try {
+    pidns = /\[(\d+)\]/.exec(fs.readlinkSync("/proc/self/ns/pid"))?.[1] ?? null;
+  } catch {}
+  const boot = readTrimmed("/proc/sys/kernel/random/boot_id");
+  cachedLockHost = pidns || boot ? `${hostname()}#${pidns ?? "?"}:${boot ?? "?"}` : hostname();
+  return cachedLockHost;
+};
+
+const pidAlive = (pid: number): boolean => {
+  if (!Number.isSafeInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    // EPERM: the process exists but belongs to another user.
+    return (error as { code?: unknown }).code === "EPERM";
+  }
+};
+
+export type LockOwnerState = {
+  /** live: wait. stale: reclaim. unknown: wait (cannot prove the owner is gone). */
+  state: "live" | "stale" | "unknown";
+  reason: string;
+};
+
+export const classifyLockOwner = (
+  payload: unknown,
+  ageMs: number | null,
+  localHost: string = localLockHost(),
+): LockOwnerState => {
+  const lock = metadataLockSchema.safeParse(payload);
+  if (!lock.success)
+    return ageMs !== null && ageMs > UNREADABLE_LOCK_TTL_MS
+      ? { state: "stale", reason: "unreadable lock left behind" }
+      : { state: "unknown", reason: "lock is being written" };
+  const { pid, processStart, host } = lock.data;
+  // Same host and pid namespace but another boot: the machine rebooted since
+  // the lock was taken, so its owner cannot still be running.
+  const [lockName, lockSpace] = host.split("#");
+  const [localName, localSpace] = localHost.split("#");
+  if (lockSpace && localSpace && lockName === localName) {
+    const [lockNs, lockBoot] = lockSpace.split(":");
+    const [localNs, localBoot] = localSpace.split(":");
+    if (lockNs === localNs && lockNs !== "?" && lockBoot !== "?" && lockBoot !== localBoot)
+      return { state: "stale", reason: "lock was taken before this machine rebooted" };
+  }
+  // Another host, another pid namespace, or a lock written by an older Workit
+  // without namespace identity: its pid cannot be checked here.
+  if (host !== localHost)
+    return ageMs !== null && ageMs > FOREIGN_LOCK_TTL_MS
+      ? { state: "stale", reason: `lock from ${host} is older than its TTL` }
+      : { state: "unknown", reason: `lock is held from ${host}; its pid cannot be checked here` };
+  if (!pidAlive(pid)) return { state: "stale", reason: `pid ${pid} is not running` };
+  const currentStart = processStartOf(pid);
+  if (processStart !== null && currentStart !== null && processStart !== currentStart)
+    return { state: "stale", reason: `pid ${pid} now belongs to a different process` };
+  return { state: "live", reason: `held by running pid ${pid}` };
+};
+
+const ageOf = (file: string, nowMs: number): number | null => {
+  try {
+    return nowMs - fs.lstatSync(file).mtimeMs;
+  } catch {
+    return null;
+  }
+};
+
+export const lockPathFor = (root: string) => path.join(root, ".workit", "metadata.lock");
+
+/** Remove a reclaim guard abandoned by a crashed reclaimer. Returns true when removed. */
+export const clearAbandonedReclaimGuard = (lockPath: string, nowMs = Date.now()): boolean => {
+  const guard = `${lockPath}.reclaim`;
+  const age = ageOf(guard, nowMs);
+  if (age === null || age <= RECLAIM_GUARD_TTL_MS) return false;
+  try {
+    fs.rmdirSync(guard);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+export type MetadataLockStatus = {
+  path: string;
+  present: boolean;
+  owner: MetadataLock | null;
+  state: LockOwnerState["state"] | "absent";
+  reason: string;
+  guard: "absent" | "fresh" | "abandoned";
+  /** Exact lock bytes that were classified (for compare-before-remove). */
+  raw?: string;
+  /** Age of the lock file in milliseconds, when present. */
+  ageMs?: number | null;
+};
+
+/** Read-only inspection of a checkout's metadata lock (doctor surface). */
+export const inspectMetadataLock = (root: string, nowMs = Date.now()): MetadataLockStatus => {
+  const lockPath = lockPathFor(root);
+  const guardAge = ageOf(`${lockPath}.reclaim`, nowMs);
+  const guard =
+    guardAge === null ? "absent" : guardAge > RECLAIM_GUARD_TTL_MS ? "abandoned" : "fresh";
+  let raw: string;
+  try {
+    raw = fs.readFileSync(lockPath, "utf8");
+  } catch {
+    return {
+      path: lockPath,
+      present: false,
+      owner: null,
+      state: "absent",
+      reason: "no lock",
+      guard,
+    };
+  }
+  const owner = parseMetadataLockOrNull(raw);
+  const ageMs = ageOf(lockPath, nowMs);
+  const verdict = classifyLockOwner(owner, ageMs);
+  return { path: lockPath, present: true, owner, ...verdict, guard, raw, ageMs };
+};
+
+export type ClearLockOutcome = MetadataLockStatus & {
+  cleared: boolean;
+  guardCleared: boolean;
+  /** Why the lock was kept, when it was present and not cleared. */
+  skipped?: string;
+};
+
+/**
+ * Clear a stale metadata lock (or, with `force`, any lock) and an abandoned
+ * reclaim guard. Removal holds the same `.reclaim` guard that writers take
+ * before reclaiming, so no writer can replace the lock between the final
+ * byte check and the unlink; a fresh guard means a reclaim is already in
+ * progress and the lock is left alone.
+ */
+export const clearStaleMetadataLock = (
+  root: string,
+  options: { force?: boolean; nowMs?: number } = {},
+): ClearLockOutcome => {
+  const nowMs = options.nowMs ?? Date.now();
+  const status = inspectMetadataLock(root, nowMs);
+  const guardCleared = status.guard === "abandoned" && clearAbandonedReclaimGuard(status.path);
+  const outcome = { ...status, cleared: false, guardCleared };
+  if (!status.present) return outcome;
+  if (status.state !== "stale" && !options.force) return { ...outcome, skipped: status.reason };
+  const guard = `${status.path}.reclaim`;
+  try {
+    fs.mkdirSync(guard);
+  } catch {
+    return { ...outcome, skipped: "a reclaim is in progress" };
+  }
+  try {
+    const before = fs.readFileSync(status.path, "utf8");
+    if (before !== status.raw) return { ...outcome, skipped: "the lock changed" };
+    if (!options.force) {
+      const verdict = classifyLockOwner(parseMetadataLockOrNull(before), ageOf(status.path, nowMs));
+      if (verdict.state !== "stale") return { ...outcome, skipped: verdict.reason };
+    }
+    if (fs.readFileSync(status.path, "utf8") !== before)
+      return { ...outcome, skipped: "the lock changed" };
+    fs.rmSync(status.path);
+    return { ...outcome, cleared: true };
+  } catch (error) {
+    return { ...outcome, skipped: `could not clear: ${String(error)}` };
+  } finally {
+    try {
+      fs.rmdirSync(guard);
+    } catch {}
+  }
+};

package/src/core/support-matrix.ts

@@ -10,7 +10,7 @@ export const SUPPORT_MATRIX = {
   // The object-form dual entry (server() + setup()) only loads from
   // 1.18.29+; the supported floor is 1.18.30 so no host can pass doctor while
   // being unable to load the entry shape.
-  opencode: { minimum: "1.18.30", current: "1.18.30" },
+  opencode: { minimum: "1.18.30", current: "1.18.34" },
   // Codex is a qualification host, not a runtime dependency: the CLI version
   // below is the one live qualification evidence covers. The doctor warns when
   // an installed CLI drifts ahead so a fresh install never silently outruns

package/src/core/task-context.ts

@@ -38,7 +38,7 @@ export function reconcileResume(
   if (observations.length > 0)
     return failure("permission_denied", "worker observations require native host verification");
   const candidate = captureCandidate(view.workspace.root, view.task.intent.data.scope, []);
-  if (!candidate.ok) return candidate as Result<never>;
+  if (!candidate.ok) return candidate;
   const staleEvidenceIds = evaluateEvidence(view.task, candidate.data)
     .filter((entry) => entry.status === "stale")
     .map((entry) => entry.evidenceId);
@@ -127,7 +127,7 @@ const compactReference = (ref: Ref): CompactReference => {
 export function compactTaskContext(view: TaskView): string {
   const decisions: CompactDecision[] = view.task.decisions
     .slice()
-    .sort((left, right) => {
+    .toSorted((left, right) => {
       const leftAt = compactTimestamp(left.recordedAt);
       const rightAt = compactTimestamp(right.recordedAt);
       if (leftAt !== rightAt) return leftAt > rightAt ? -1 : 1;
@@ -162,7 +162,7 @@ export function compactTaskContext(view: TaskView): string {
       ...view.task.progress.blockers.map((entry) => entry.reason),
     ]),
   )
-    .sort()
+    .toSorted()
     .slice(0, COMPACT_MAX_ITEMS)
     .map((gap) => compactText(gap, COMPACT_TEXT_BYTES)!);
   const context: CompactTaskContext = {

package/src/core/task-contract.ts

@@ -84,6 +84,7 @@ export const hostSchema = z.enum([
   "codex_desktop",
   "pi",
   "workit_cli",
+  "claude_code",
 ]);
 export type Host = z.infer<typeof hostSchema>;
 export const assuranceSchema = z.enum(["enforced", "agent_guided", "unavailable"]);
@@ -746,9 +747,111 @@ export const taskRecordSchema = z
     actionProgress: actionProgressListSchema.optional(),
     findings: z.array(entrySchema(findingSchema)),
     workers: z.array(entrySchema(workerSchema)),
+    /** Paths a reader must understand; see parseStoredRecord. */
+    critical: z.array(nonEmpty).optional(),
   })
   .strict();
 export type TaskRecord = z.infer<typeof taskRecordSchema>;
+
+type Strip = { path: PropertyKey[]; keys: string[] };
+const stripCount = (strips: Strip[]) => strips.reduce((sum, strip) => sum + strip.keys.length, 0);
+/** Unknown-key issues only, flattened; null when any issue is a real schema
+ * violation. For a union, the branch that strips the fewest keys wins, so a
+ * key one branch knows is never dropped in favor of a narrower branch. */
+const strippable = (
+  issues: readonly z.core.$ZodIssue[],
+  prefix: PropertyKey[] = [],
+): Strip[] | null => {
+  const strips: Strip[] = [];
+  for (const issue of issues) {
+    if (issue.code === "unrecognized_keys") {
+      strips.push({ path: [...prefix, ...issue.path], keys: issue.keys });
+      continue;
+    }
+    if (issue.code !== "invalid_union") return null;
+    const branch = issue.errors
+      .map((errors) => strippable(errors, [...prefix, ...issue.path]))
+      .filter((found): found is Strip[] => found !== null && found.length > 0)
+      .reduce<Strip[] | null>(
+        (best, found) => (best === null || stripCount(found) < stripCount(best) ? found : best),
+        null,
+      );
+    if (!branch) return null;
+    strips.push(...branch);
+  }
+  return strips;
+};
+
+/** A dotted record path with array indices as `*`, e.g. `evidence.*.data.observer`. */
+const recordPath = (path: PropertyKey[]): string =>
+  path.map((key) => (typeof key === "number" ? "*" : String(key))).join(".");
+const overlaps = (left: string, right: string) =>
+  left === right || left.startsWith(`${right}.`) || right.startsWith(`${left}.`);
+
+export type StoredRecordParse<T> =
+  | { success: true; data: T; stripped: string[] }
+  | { success: false; error: z.ZodError; critical: string[] };
+
+/**
+ * Reader tolerance for stored records (D17). A record written by a newer
+ * runtime may carry keys this reader does not know; exactly the keys zod
+ * reports as unrecognized are dropped and the value is parsed again, and
+ * every other violation still fails. Writes keep parsing strictly.
+ *
+ * The rule for new record fields: a field must be safe for an older reader
+ * to ignore (and to lose when that reader rewrites the record), or the writer
+ * must list its path in the record's top-level `critical` array. A reader
+ * that would strip a critical path fails closed instead (`critical` names the
+ * paths), so it neither acts on nor rewrites a record it cannot represent.
+ */
+export const parseStoredRecord = <S extends z.ZodType>(
+  schema: S,
+  value: unknown,
+): StoredRecordParse<z.output<S>> => {
+  let parsed = schema.safeParse(value);
+  if (parsed.success) return { success: true, data: parsed.data, stripped: [] };
+  const first = { success: false as const, error: parsed.error, critical: [] as string[] };
+  const declared =
+    typeof value === "object" &&
+    value !== null &&
+    Array.isArray((value as { critical?: unknown }).critical)
+      ? (value as { critical: unknown[] }).critical
+          .filter((item): item is string => typeof item === "string")
+          // An array index in a declaration means any element, like `*`.
+          .map((item) =>
+            item
+              .split(".")
+              .map((key) => (/^\d+$/.test(key) ? "*" : key))
+              .join("."),
+          )
+      : [];
+  const stripped: string[] = [];
+  let current: unknown = structuredClone(value);
+  for (let round = 0; round < 8 && !parsed.success; round++) {
+    const strips = strippable(parsed.error.issues);
+    if (strips === null || strips.length === 0) return first;
+    for (const strip of strips) {
+      let target: unknown = current;
+      for (const key of strip.path)
+        target =
+          typeof target === "object" && target !== null
+            ? (target as Record<PropertyKey, unknown>)[key]
+            : undefined;
+      if (typeof target !== "object" || target === null) return first;
+      for (const key of strip.keys) {
+        stripped.push(recordPath([...strip.path, key]));
+        delete (target as Record<string, unknown>)[key];
+      }
+    }
+    parsed = schema.safeParse(current);
+  }
+  if (!parsed.success) return first;
+  const critical = [
+    ...new Set(stripped.filter((item) => declared.some((path) => overlaps(item, path)))),
+  ];
+  if (critical.length > 0) return { ...first, critical };
+  return { success: true, data: parsed.data, stripped: [...new Set(stripped)] };
+};
 export const workspaceRecordSchema = z
   .object({
     schemaVersion: z.literal(1),
@@ -760,6 +863,8 @@ export const workspaceRecordSchema = z
       .object({ state: z.enum(["held", "uncertain"]), owner: ownerSchema, acquiredAt: utc })
       .strict()
       .nullable(),
+    /** Paths a reader must understand; see parseStoredRecord. */
+    critical: z.array(nonEmpty).optional(),
   })
   .strict();
 export type WorkspaceRecord = z.infer<typeof workspaceRecordSchema>;
@@ -1026,6 +1131,19 @@ export const operationSchemas = {
   state: z.discriminatedUnion("action", Object.values(stateOperations) as any),
 } as const;
 export type OperationRequest = z.infer<(typeof operationSchemas)[OperationFamily]>;
+
+/**
+ * Schemas advertised to hosts. `state.recover` needs host-supplied native
+ * recovery authority (`OperationContext.nativeRecovery`), which no shipped
+ * host provides, so advertising it only sends agents into a guaranteed
+ * permission_denied. parseOperation still accepts it for embedders that do
+ * supply that authority.
+ */
+const { recover: _unadvertisedRecover, ...advertisedStateOperations } = stateOperations;
+export const advertisedOperationSchemas = {
+  ...operationSchemas,
+  state: z.discriminatedUnion("action", Object.values(advertisedStateOperations) as any),
+} as const;
 export type TaskStartRequest = z.infer<typeof taskOperations.start>;
 
 const compiledOperationSchemas = Object.fromEntries(
@@ -1048,6 +1166,8 @@ export type ErrorCode =
   | "capability_unavailable"
   | "requirements_unsatisfied"
   | "writer_conflict"
+  /** Retryable: another live Workit call holds the checkout's metadata lock. */
+  | "busy"
   | "recovery_required"
   | "storage_error"
   | "external_outcome_unknown";
@@ -1118,7 +1238,7 @@ export function parseOperation(family: OperationFamily, input: unknown): Result<
     return failure("unsupported_version", "unsupported schema version", { operation: family });
   const compiled = compiledOperationSchemas[family].safeParse(input);
   const parsed = compiled.success ? operationSchemas[family].safeParse(input) : compiled;
-  if (parsed.success) return success(null, null, parsed.data as OperationRequest);
+  if (parsed.success) return success(null, null, parsed.data);
   const fields = parsed.error.issues.map((issue) => ({
     path: issue.code === "unrecognized_keys" ? issue.keys.join(".") : issue.path.join("."),
     reason: issue.message,
@@ -1127,7 +1247,7 @@ export function parseOperation(family: OperationFamily, input: unknown): Result<
 }
 
 export function operationJsonSchema(family: OperationFamily): z.core.JSONSchema.BaseSchema {
-  return z.toJSONSchema(operationSchemas[family], { target: "draft-2020-12" });
+  return z.toJSONSchema(advertisedOperationSchemas[family], { target: "draft-2020-12" });
 }
 
 /**
@@ -1293,7 +1413,7 @@ function canonical(value: unknown, seen: Set<object>): JsonValue {
       throw new TypeError("invalid Unicode");
     result = Object.fromEntries(
       Object.keys(value)
-        .sort()
+        .toSorted()
         .map((key) => [key, canonical((value as Record<string, unknown>)[key], seen)]),
     );
   }
@@ -1339,13 +1459,13 @@ export function decisionDigest(input: Omit<Decision, "digest"> | Decision): Dige
 export function candidateDigest(input: Candidate): Digest {
   const normalizedScope = {
     description: input.scope.description,
-    paths: [...input.scope.paths].sort(compareCodeUnits),
-    exclusions: [...input.scope.exclusions].sort(compareCodeUnits),
+    paths: [...input.scope.paths].toSorted(compareCodeUnits),
+    exclusions: [...input.scope.exclusions].toSorted(compareCodeUnits),
   };
   return sha256({
     scope: normalizedScope,
     completeness: input.completeness,
-    files: [...input.files].sort(
+    files: [...input.files].toSorted(
       (left, right) =>
         compareCodeUnits(left.path, right.path) ||
         compareCodeUnits(left.kind, right.kind) ||
@@ -1354,7 +1474,7 @@ export function candidateDigest(input: Candidate): Digest {
     ),
     environment: input.environment
       .map(({ name, value }) => ({ name, value }))
-      .sort(
+      .toSorted(
         (left, right) =>
           compareCodeUnits(left.name, right.name) || compareNullableText(left.value, right.value),
       ),
@@ -1372,8 +1492,8 @@ export function requirementId(input: {
     ...input,
     scope: {
       description: input.scope.description,
-      paths: [...input.scope.paths].sort(compareCodeUnits),
-      exclusions: [...input.scope.exclusions].sort(compareCodeUnits),
+      paths: [...input.scope.paths].toSorted(compareCodeUnits),
+      exclusions: [...input.scope.exclusions].toSorted(compareCodeUnits),
     },
   });
 }