@brainervirus/workit-core 2.1.5 → 2.2.1

package/package.json

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

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"),
@@ -1693,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,
@@ -1705,6 +1749,7 @@ const RUN_CHECKS: Array<(res: Resolved) => DoctorCheck> = [
   checkDuplicateRegistration,
   checkMalformedConfig,
   checkWorkspaceMismatch,
+  checkWorkspaceLock,
   checkCredentialMetadata,
   checkGithubIdentity,
   checkGitLabIdentity,

package/src/core/methods.ts

@@ -110,6 +110,13 @@ 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.
+An omitted revision absorbs a concurrent write: Workit re-reads, re-checks
+policy, and reapplies the call, returning busy under persistent contention. A
+revision_conflict means a revision you passed is stale: re-read the record
+before deciding whether to retry.
 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

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/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";
@@ -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" });
 }
 
 /**