@brainervirus/workit-core 2.9.0 → 4.0.0

package/src/core/workspace-branch-policy.ts

@@ -0,0 +1,123 @@
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { detectBranchPolicy } from "./branch-policy";
+import { configDir } from "./config";
+import {
+  readWorkspacesResult,
+  resolveWorkspaceFrom,
+  validateWorkspaceGlob,
+  validateWorkspacesDocument,
+  workspacesRevision,
+  type WorkspaceConfig,
+} from "./workspaces";
+
+const readFileSafe = (p: string): string | null => {
+  try {
+    return readFileSync(p, "utf8");
+  } catch {
+    return null;
+  }
+};
+
+// The one proposal→write path for a workspace branch policy, shared by the
+// OpenCode `workit_init_apply` branch_policy action (init.ts) and the CLI
+// wizard, so both produce byte-identical workspaces.json writes.
+export function applyWorkspaceBranchPolicy(opts: {
+  workspace_root: string;
+  env?: NodeJS.ProcessEnv;
+}): Record<string, any> {
+  const { workspace_root, env = process.env } = opts;
+  const dir = path.join(env.WORKFLOW_TOOLKIT_CONFIG ?? configDir());
+  const {
+    status,
+    path: wsPath,
+    entries,
+    document,
+    revision,
+    error: workspacesError,
+  } = readWorkspacesResult(dir);
+  if (status === "malformed" || status === "invalid")
+    return { ok: false, error: workspacesError ?? `invalid workspaces.json: ${wsPath}` };
+  const detection = detectBranchPolicy(workspace_root);
+  const name = String(env.WORKFLOW_BP_NAME ?? path.basename(workspace_root));
+  const integration = (env.WORKFLOW_BP_INTEGRATION ?? detection.integration) as "pr" | "merge";
+  const policy = {
+    preset: detection.preset,
+    developBranch: env.WORKFLOW_BP_DEVELOP ?? detection.developBranch ?? undefined,
+    prefixes: detection.prefixes,
+    allowed: detection.allowed,
+    protected: detection.protected,
+    integration,
+  };
+  const glob = `${workspace_root.replace(/[\\/]+$/, "")}/**`;
+  if (!validateWorkspaceGlob(glob).ok)
+    return { ok: false, error: `invalid workspace glob: ${glob}` };
+  let existing: WorkspaceConfig | null;
+  try {
+    existing = resolveWorkspaceFrom(workspace_root, dir);
+  } catch (error) {
+    const selectedName = env.WORKFLOW_BP_NAME?.trim();
+    if (!selectedName)
+      return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    try {
+      existing = resolveWorkspaceFrom(workspace_root, dir, selectedName);
+    } catch (selectionError) {
+      return {
+        ok: false,
+        error: selectionError instanceof Error ? selectionError.message : String(selectionError),
+      };
+    }
+  }
+  if (existing?.branchPolicy && isDeepStrictEqual(existing.branchPolicy, policy)) {
+    return {
+      ok: true,
+      status: "already-configured",
+      workspace: existing,
+      policy,
+      config_path: wsPath,
+    };
+  }
+  const next = existing
+    ? entries.map((w) => (w.name === existing?.name ? { ...w, branchPolicy: policy } : w))
+    : [...entries, { name, glob, branchPolicy: policy }];
+  if (!existing && entries.some((entry) => entry.name === name))
+    return { ok: false, error: `workspace name ${JSON.stringify(name)} is already configured` };
+  const proposed = validateWorkspacesDocument({ ...document, workspaces: next }, wsPath);
+  if (proposed.status !== "valid") return { ok: false, error: proposed.error };
+  if (workspacesRevision(readFileSafe(wsPath)) !== revision)
+    return {
+      ok: false,
+      error: `workspaces.json changed while applying the branch policy: ${wsPath}`,
+    };
+  mkdirSync(path.dirname(wsPath), { recursive: true });
+  const tmp = `${wsPath}.${process.pid}.tmp`;
+  try {
+    writeFileSync(tmp, JSON.stringify({ ...document, workspaces: next }, null, 2) + "\n", "utf8");
+    if (workspacesRevision(readFileSafe(wsPath)) !== revision) {
+      rmSync(tmp, { force: true });
+      return {
+        ok: false,
+        error: `workspaces.json changed while applying the branch policy: ${wsPath}`,
+      };
+    }
+    renameSync(tmp, wsPath);
+  } catch (error) {
+    try {
+      rmSync(tmp, { force: true });
+    } catch {}
+    return {
+      ok: false,
+      error: `failed to write ${wsPath}: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+  return {
+    ok: true,
+    status: existing ? "updated" : "configured",
+    workspace: existing
+      ? { ...existing, branchPolicy: policy }
+      : { name, glob, branchPolicy: policy },
+    policy,
+    config_path: wsPath,
+  };
+}

package/src/core.ts

@@ -61,12 +61,7 @@ export type {
   Result as ContractResult,
 } from "./core/task-contract";
 export { TaskStore, runtimeVersion } from "./core/task-store";
-export type {
-  MetadataLock,
-  ProcessEvidence,
-  RecoveryInput,
-  TaskIndexEntry,
-} from "./core/task-store";
+export type { TaskIndexEntry } from "./core/task-store";
 export { compactTaskContext, reconcileResume } from "./core/task-context";
 export type {
   CompactTaskContext,

package/src/hooks/context.ts

@@ -6,10 +6,24 @@ import { canonicalJson } from "../core/task-contract";
 import { isObservedCheck, type Freshness } from "../core/task-evaluation";
 import { worktreeSignal } from "../git/rev";
 import { WorkitCore, type OperationContext } from "../core/task-engine";
-import { fileSignature, racySignature, TaskStore, type TaskIndexEntry } from "../core/task-store";
+import {
+  fileSignature,
+  MIGRATION_PENDING,
+  racySignature,
+  TaskStore,
+  type TaskIndexEntry,
+} from "../core/task-store";
 import { capabilitiesFor, type HostDescriptor } from "./descriptor";
 import type { HookInput } from "./protocol";
 
+/**
+ * Shown on every per-turn path while the checkout's 2.x store waits for the
+ * CLI to migrate it (hooks never migrate), instead of silently no context.
+ */
+export const MIGRATION_PENDING_NOTE = "workit migration pending — run `workit task status`";
+const migrationPending = (result: { ok: boolean; code?: string; error?: string }): boolean =>
+  !result.ok && result.code === "needs_input" && (result.error ?? "").startsWith(MIGRATION_PENDING);
+
 /** A native host session, e.g. `{ host: "opencode", handle: sessionID }`. */
 export type SessionHandle = { host: string; handle: string };
 
@@ -50,6 +64,34 @@ export const currentTaskEntry = (
   return active.length === 1 ? active[0] : null;
 };
 
+/**
+ * The open task bound to this checkout's branch (its implicit task, D3),
+ * unless a host conversation other than this one is bound to it: someone
+ * else's conversation is only ever offered, never injected. Sessions of the
+ * CLI (`workit_cli`, which creates implicit tasks) are tooling, not
+ * conversations.
+ */
+const implicitTaskEntry = (
+  store: TaskStore,
+  entries: TaskIndexEntry[],
+  session: SessionHandle,
+): TaskIndexEntry | null => {
+  const open = entries.filter(
+    (entry) =>
+      entry.key !== null &&
+      entry.status !== "closed" &&
+      !entry.sessions.some(
+        (item) =>
+          item.host !== "workit_cli" &&
+          !(item.host === session.host && item.handle === session.handle),
+      ),
+  );
+  if (open.length === 0) return null;
+  const key = store.currentKey();
+  if (!key.ok) return null;
+  return open.filter((entry) => entry.key === key.data.key).toSorted(newestFirst)[0] ?? null;
+};
+
 /**
  * History offer for open tasks not bound to `session` (and not `excludeTaskId`,
  * the task already shown), built from the task index. Task text is quoted and
@@ -109,7 +151,9 @@ const recentSignal = (root: string): string | null => {
 const cache = new Map<string, CachedContext>();
 
 /**
- * Compact context for `session`'s current task, for per-turn host injection.
+ * Compact context for `session`'s current task (the task bound to the
+ * session, else the implicit task of the checkout's branch), for per-turn
+ * host injection.
  *
  * Reads the task index (no full-record parse for unrelated tasks), never
  * captures a candidate, and reuses the previous result while the task and
@@ -123,8 +167,10 @@ export function sessionCompactContext(
   selection: HostDescriptor["context"]["task"] = "session-bound",
 ): string | null {
   const listed = store.listTaskIndex();
-  if (!listed.ok) return null;
-  const entry = currentTaskEntry(listed.data, session, selection);
+  if (!listed.ok) return migrationPending(listed) ? MIGRATION_PENDING_NOTE : null;
+  const entry =
+    currentTaskEntry(listed.data, session, selection) ??
+    implicitTaskEntry(store, listed.data, session);
   return entry ? entryCompactContext(store, entry, session, context) : null;
 }
 
@@ -208,8 +254,13 @@ export const sessionContextText = (
   try {
     const store = new TaskStore(input.cwd);
     const listed = store.listTaskIndex();
+    // Hooks never migrate (hot path, possibly a live 2.x writer): say how.
+    if (migrationPending(listed))
+      return `<workit-contract>\n${invariantBootstrap()}\n${MIGRATION_PENDING_NOTE}${options.addendum ? `\n${options.addendum}` : ""}\n</workit-contract>`;
     if (!listed.ok) throw new Error(listed.error);
-    const entry = currentTaskEntry(listed.data, session, descriptor.context.task);
+    const entry =
+      currentTaskEntry(listed.data, session, descriptor.context.task) ??
+      implicitTaskEntry(store, listed.data, session);
     const text = entry
       ? entryCompactContext(store, entry, session, hookOperationContext(input, descriptor))
       : null;
@@ -230,6 +281,7 @@ export const turnContextText = (input: HookInput, descriptor: HostDescriptor): s
       hookOperationContext(input, descriptor),
       descriptor.context.task,
     );
+    if (text === MIGRATION_PENDING_NOTE) return text;
     return text ? `<workit-task-context>${text}</workit-task-context>` : null;
   } catch {
     return null;

package/src/hooks/hosts/opencode.ts

@@ -4,8 +4,8 @@ import type { HostDescriptor } from "../descriptor";
 export const OPENCODE_DESCRIPTOR: HostDescriptor = {
   host: "opencode",
   label: "OpenCode",
-  verifiedAgainst: "@opencode-ai/plugin 1.18.30",
-  docs: ["https://opencode.ai/docs/plugins/"],
+  verifiedAgainst: "@opencode/plugin 2.0.18",
+  docs: ["https://opencode.ai/v2/docs/build/plugins/"],
   transport: "in-process-plugin",
   events: {
     // No separate start event: context is injected on every agent-loop call.

package/src/ledger.ts

@@ -40,6 +40,7 @@ import { createHash, randomBytes } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { GIT_TIMEOUTS, currentBranch, headSha, patchId, worktreeTree } from "./git/rev";
+import { resolveStore } from "./store/paths";
 
 export const LEDGER_VERSION = 1;
 /** The largest row (including its newline) that one append may carry. */
@@ -254,29 +255,22 @@ export function diffHash(cwd: string, base: string, head: string): string | null
 
 export type StoreRoot = { root: string; shared: boolean };
 
-const NOT_A_REPO = /not a git repository \(or any (of the parent directories|parent up to)/u;
-
 /**
  * Where workit state lives for `cwd`: `<git common dir>/workit` (shared by all
  * worktrees of the repo), or `<cwd>/.workit` only when git reports that `cwd`
- * is not inside a repository. A broken repository, a missing git binary or a
- * refused (dubious-ownership) repository is `unavailable`.
+ * is not inside a repository (or git is not installed). A broken repository
+ * or a refused (dubious-ownership) repository is `unavailable`. The task
+ * store resolves the same way (store/paths.ts).
  */
 export function storeRoot(cwd: string): LedgerResult<StoreRoot> {
-  const run = gitRun(cwd, ["rev-parse", "--path-format=absolute", "--git-common-dir"]);
-  const common = run.stdout.trim();
-  if (run.ok && common)
-    return {
-      ok: true,
-      value: { root: path.join(path.resolve(cwd, common), "workit"), shared: true },
-    };
-  if (!run.ok && NOT_A_REPO.test(run.stderr))
-    return { ok: true, value: { root: path.join(path.resolve(cwd), ".workit"), shared: false } };
-  return err(
-    "unavailable",
-    `cannot locate the workit store: git rev-parse failed (${run.stderr.trim().split("\n")[0] || "no output"})`,
-    "fix the repository (git status should work here) or run from a non-git directory",
-  );
+  const location = resolveStore(path.resolve(cwd));
+  if (location instanceof Error)
+    return err(
+      "unavailable",
+      location.message.replace(/; fix the repository.*$/u, ""),
+      "fix the repository (git status should work here) or run from a non-git directory",
+    );
+  return { ok: true, value: { root: location.dir, shared: location.shared } };
 }
 
 export function ledgerPath(cwd: string): LedgerResult<string> {

package/src/store/event-log.ts

@@ -0,0 +1,217 @@
+// The append-only event log of one task: `events.jsonl`, one JSON event per
+// line, plus `snapshot.json`, a rebuildable cache of the reduced state
+// (design §4.1).
+//
+// - A writer holds the task lock, appends one complete line with O_APPEND in
+//   a single write, and fsyncs. A crash can therefore only leave a torn last
+//   line (no trailing newline); readers ignore it and the next locked append
+//   truncates it away first. Any other unreadable line is real damage.
+// - Readers are lenient (D17): unknown event keys and unknown event types are
+//   ignored, unless the event says `critical: true`, in which case a reader
+//   that does not know the type fails closed with an upgrade message.
+// - The snapshot names the event it was taken after (seq, id, byte range). A
+//   snapshot that does not match the log is ignored and the log is replayed.
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+export const EVENT_VERSION = 1;
+
+export type EventActor = { host: string; session: string | null; agentId: string | null };
+
+export type StoreEvent = {
+  v: number;
+  seq: number;
+  at: string;
+  id: string;
+  task: string;
+  actor: EventActor | null;
+  type: string;
+  data: Record<string, unknown>;
+  critical?: boolean;
+};
+
+export type LogRead = {
+  events: StoreEvent[];
+  /** Byte offset just past the last complete event line. */
+  end: number;
+  /** Byte offset where the last complete event line starts. */
+  lastStart: number;
+  /** File size; larger than `end` when a torn line trails the log. */
+  size: number;
+};
+
+export class LogDamage extends Error {
+  constructor(
+    message: string,
+    readonly upgrade: boolean = false,
+  ) {
+    super(message);
+  }
+}
+
+const isObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+const parseEvent = (line: string, file: string, offset: number): StoreEvent => {
+  let value: unknown;
+  try {
+    value = JSON.parse(line);
+  } catch {
+    throw new LogDamage(`${file}: unreadable event at byte ${offset}`);
+  }
+  if (!isObject(value) || typeof value.v !== "number")
+    throw new LogDamage(`${file}: malformed event at byte ${offset}`);
+  if (value.v > EVENT_VERSION)
+    throw new LogDamage(
+      `${file}: event format v${value.v} was written by a newer Workit; upgrade Workit to read this task`,
+      true,
+    );
+  if (
+    typeof value.seq !== "number" ||
+    !Number.isInteger(value.seq) ||
+    typeof value.type !== "string" ||
+    typeof value.id !== "string" ||
+    typeof value.task !== "string" ||
+    !isObject(value.data)
+  )
+    throw new LogDamage(`${file}: malformed event at byte ${offset}`);
+  return value as StoreEvent;
+};
+
+/**
+ * Read the events of `file` starting at byte `from` (a line start). A torn
+ * trailing line is excluded; `expectSeq` is the seq the first event must have.
+ * Returns null when the file does not exist.
+ */
+export function readLog(file: string, from = 0, expectSeq: number | null = null): LogRead | null {
+  let fd: number;
+  try {
+    fd = fs.openSync(file, "r");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw error;
+  }
+  let bytes: Buffer;
+  let size: number;
+  try {
+    size = fs.fstatSync(fd).size;
+    if (from > size) throw new LogDamage(`${file}: shorter than its snapshot`);
+    bytes = Buffer.alloc(size - from);
+    let read = 0;
+    while (read < bytes.length) {
+      const got = fs.readSync(fd, bytes, read, bytes.length - read, from + read);
+      if (got === 0) break;
+      read += got;
+    }
+    bytes = bytes.subarray(0, read);
+    size = from + read;
+  } finally {
+    fs.closeSync(fd);
+  }
+  const events: StoreEvent[] = [];
+  let start = 0;
+  let lastStart = from;
+  let seq = expectSeq;
+  for (;;) {
+    const newline = bytes.indexOf(0x0a, start);
+    if (newline < 0) break;
+    const line = bytes.subarray(start, newline).toString("utf8");
+    if (line.trim() !== "") {
+      const event = parseEvent(line, file, from + start);
+      if (seq !== null && event.seq !== seq)
+        throw new LogDamage(`${file}: event seq ${event.seq} where ${seq} was expected`);
+      seq = event.seq + 1;
+      events.push(event);
+      lastStart = from + start;
+    }
+    start = newline + 1;
+  }
+  return { events, end: from + start, lastStart, size };
+}
+
+/** Durably write `dir`'s entries (no-op where directories cannot be fsynced). */
+export const fsyncDirectory = (dir: string): void => {
+  try {
+    const fd = fs.openSync(dir, "r");
+    try {
+      fs.fsyncSync(fd);
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch (error) {
+    if (process.platform !== "win32") throw error;
+  }
+};
+
+/**
+ * Append one event line. `validEnd` is where the last complete line ends: a
+ * torn tail beyond it is truncated first. Returns the byte offset the line
+ * starts at.
+ */
+export function appendEvent(file: string, event: StoreEvent, validEnd: number): number {
+  const line = Buffer.from(`${JSON.stringify(event)}\n`, "utf8");
+  const created = !fs.existsSync(file);
+  // Cut a torn tail first, through a writable handle: an append-only handle
+  // cannot truncate on Windows.
+  if (!created && fs.statSync(file).size !== validEnd) {
+    const cut = fs.openSync(file, "r+");
+    try {
+      fs.ftruncateSync(cut, validEnd);
+      fs.fsyncSync(cut);
+    } finally {
+      fs.closeSync(cut);
+    }
+  }
+  const fd = fs.openSync(file, "a", 0o600);
+  try {
+    let written = 0;
+    while (written < line.length) written += fs.writeSync(fd, line, written, line.length - written);
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  if (created) fsyncDirectory(path.dirname(file));
+  return validEnd;
+}
+
+/** Replace `file` with `bytes` atomically (temp file + rename). */
+export function replaceFile(file: string, bytes: string, durable: boolean): void {
+  const temporary = `${file}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    const fd = fs.openSync(temporary, "wx", 0o600);
+    try {
+      fs.writeSync(fd, bytes);
+      if (durable) fs.fsyncSync(fd);
+    } finally {
+      fs.closeSync(fd);
+    }
+    renameWithRetry(temporary, file);
+    if (durable) fsyncDirectory(path.dirname(file));
+  } catch (error) {
+    try {
+      fs.unlinkSync(temporary);
+    } catch {}
+    throw error;
+  }
+}
+
+const TRANSIENT_WINDOWS_CODES = new Set(["EPERM", "EACCES", "EBUSY"]);
+/** Windows briefly refuses to replace a file another process is reading. */
+export const isTransientWindowsError = (error: unknown): boolean => {
+  if (process.platform !== "win32") return false;
+  const code = (error as { code?: unknown } | null)?.code;
+  return typeof code === "string" && TRANSIENT_WINDOWS_CODES.has(code);
+};
+export const retryTransient = <T>(run: () => T): T => {
+  if (process.platform !== "win32") return run();
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      return run();
+    } catch (error) {
+      if (attempt >= 20 || !isTransientWindowsError(error)) throw error;
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 5 * (attempt + 1));
+    }
+  }
+};
+const renameWithRetry = (from: string, to: string) => retryTransient(() => fs.renameSync(from, to));

package/src/store/notes.ts

@@ -0,0 +1,29 @@
+// One-time notes from the store to the user. A host installs a reporter on
+// the global `Symbol.for("workit.migrationReporter")` slot (the CLI router
+// does; it must not import workit-core on its cold path). Without one, the
+// note is silent: hooks and in-process hosts own their output channels.
+
+export type MigrationReport = {
+  /** The 2.x store that was migrated. */
+  from: string;
+  /** The store it now lives in. */
+  to: string;
+  /** Where the 2.x files were backed up. */
+  backup: string;
+  tasks: number;
+  skipped: number;
+  workspace: boolean;
+};
+
+const SLOT = Symbol.for("workit.migrationReporter");
+
+export const reportMigration = (report: MigrationReport): void => {
+  try {
+    const reporter = (globalThis as Record<symbol, unknown>)[SLOT];
+    if (typeof reporter === "function") reporter(report);
+  } catch {}
+};
+
+/** Whether a host installed a reporter (it can tell the user about a migration). */
+export const migrationReporterInstalled = (): boolean =>
+  typeof (globalThis as Record<symbol, unknown>)[SLOT] === "function";