@workit-dev/core 0.0.1 → 1.0.0

package/src/core/vcs-config.ts

@@ -0,0 +1,540 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { originUrl } from "../git/facts";
+import { configDir, vcsConfigPath } from "./config";
+import { resolveRuntimeWorkspaceVcs, workspaceDefaultTarget } from "./workspaces";
+import { resolveTrackFor, type RuntimeReleaseTrack, type TrackResolution } from "./release-tracks";
+// VCS resolution and CLI-backed identity/style reads.
+
+const workspacesPath = (): string => path.join(configDir(), "workspaces.json");
+
+const vcsCwd = (cwd?: string): string => cwd ?? process.env.WORKIT_WORKSPACE_ROOT ?? process.cwd();
+
+// RL-03b: the origin remote is the ground truth for PR creation. A stale global
+// provider (e.g. gitlab from another repo) must not drive glab on a
+// github.com-hosted checkout. Recognized hosts only — custom/self-hosted
+// remotes keep the configured provider, and a missing origin is untouched.
+const remoteProvider = (cwd: string): string | null => {
+  const url = originUrl(cwd) ?? "";
+  if (/github\.com[:/]/.test(url)) return "github";
+  if (/gitlab\.com[:/]/.test(url)) return "gitlab";
+  return null;
+};
+
+const remoteEndpoint = (
+  remote: string,
+): { host: string; path: string; protocol: string; port: string } | null => {
+  const raw = remote.trim();
+  if (!raw) return null;
+  const scp = /^(?:[^@\s]+@)?([^:]+):(.+)$/u.exec(raw);
+  if (scp && !raw.includes("://"))
+    return {
+      host: scp[1].toLowerCase(),
+      path: scp[2].replace(/^\//u, "").replace(/\.git$/u, ""),
+      protocol: "ssh:",
+      port: "",
+    };
+  try {
+    const url = new URL(raw);
+    return {
+      host: url.hostname.toLowerCase(),
+      path: url.pathname
+        .replace(/^\//u, "")
+        .replace(/\.git$/u, "")
+        .replace(/\/$/u, ""),
+      protocol: url.protocol,
+      port: url.port,
+    };
+  } catch {
+    return null;
+  }
+};
+
+const configuredSshEndpoint = (host: string): { host: string; port: string } | null => {
+  if (host.startsWith("-")) return null;
+  const resolved = spawnSync("ssh", ["-G", host], {
+    encoding: "utf8",
+    timeout: 5000,
+    maxBuffer: 1024 * 1024,
+    env: { ...process.env, PATH: process.env.PATH ?? "" },
+  });
+  if (resolved.status !== 0) return null;
+  const output = resolved.stdout ?? "";
+  const hostname = /^hostname\s+(\S+)/imu.exec(output)?.[1]?.toLowerCase();
+  if (!hostname) return null;
+  return { host: hostname, port: /^port\s+(\d+)/imu.exec(output)?.[1] ?? "22" };
+};
+
+const sshApiHostAliases: Record<string, Array<{ host: string; port: string }>> = {
+  "github.com": [{ host: "ssh.github.com", port: "443" }],
+  "gitlab.com": [{ host: "altssh.gitlab.com", port: "443" }],
+};
+
+/** Confirm that Git transport and authenticated provider API calls target the same host. */
+export const hostingApiHostMatches = (
+  remote: string,
+  apiHost: string,
+  resolveSshEndpoint: (
+    host: string,
+  ) => { host: string; port: string } | null = configuredSshEndpoint,
+): boolean => {
+  const endpoint = remoteEndpoint(remote);
+  if (!endpoint) return false;
+  let expected: { host: string; port: string };
+  try {
+    const url = new URL(`https://${apiHost}`);
+    if (url.pathname !== "/" || url.search || url.hash || url.username || url.password)
+      return false;
+    expected = {
+      host: url.hostname.toLowerCase().replace(/\.$/u, ""),
+      port: url.port,
+    };
+  } catch {
+    return false;
+  }
+  if (endpoint.protocol !== "ssh:") {
+    return endpoint.host.replace(/\.$/u, "") === expected.host && endpoint.port === expected.port;
+  }
+  const resolved = resolveSshEndpoint(endpoint.host);
+  if (!resolved) return false;
+  const hostname = resolved.host.toLowerCase().replace(/\.$/u, "");
+  const port = endpoint.port || resolved.port;
+  if (hostname === expected.host) return port === (expected.port || "22");
+  return Boolean(
+    sshApiHostAliases[expected.host]?.some(
+      (alias) =>
+        alias.host === hostname &&
+        alias.port === port &&
+        (!expected.port || expected.port === port),
+    ),
+  );
+};
+
+// RL-01: typed vcs.json reader. Missing is a legitimate unconfigured state;
+// malformed (parse failure or a non-object) is reported with the exact path so
+// risky consumers stop instead of silently reading defaults.
+export type VcsConfigResult = {
+  status: "missing" | "valid" | "malformed";
+  path: string;
+  config: Record<string, any>;
+  error?: string;
+};
+
+export const readVcsConfig = (): VcsConfigResult => {
+  const file = vcsConfigPath();
+  let raw: string;
+  try {
+    raw = fs.readFileSync(file, "utf8");
+  } catch {
+    return { status: "missing", path: file, config: {} };
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return { status: "malformed", path: file, config: {}, error: `${file} is not valid JSON` };
+  }
+  if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+    return { status: "valid", path: file, config: parsed as Record<string, any> };
+  }
+  return { status: "malformed", path: file, config: {}, error: `${file} is not a JSON object` };
+};
+
+export type IssueTrackerProvider = "github" | "gitlab" | "youtrack";
+
+/** A workspace's issue tracker, with legacy keys migrated (issueTrackerOf). */
+export type IssueTracker = {
+  provider: IssueTrackerProvider;
+  /** Derive the issue from the branch name when no issue is named. */
+  link: boolean;
+  relation: "closes" | "refs";
+  /** Post the PR URL on each linked issue after the PR is opened. */
+  backlink: boolean;
+  /** YouTrack's base URL from the workspace (`youtrack.baseUrl`), else null. */
+  baseUrl: string | null;
+  /** The GitHub/GitLab repository that holds the issues (`issues.repo`); null: the PR's own. */
+  repo: string | null;
+  /** That repository's host (`issues.host`); null: the PR's host, or the tracker's public one. */
+  host: string | null;
+  /** Which keys set it: the `issues` block or a legacy alias. */
+  source: "issues" | "issues.link_on_pr" | "youtrack.link_issues" | "youtrack.baseUrl";
+  /** Values read leniently (D17): what was ignored and what was used instead. */
+  warnings: string[];
+};
+
+const TRACKERS: ReadonlySet<string> = new Set(["github", "gitlab", "youtrack"]);
+
+const asRecord = (value: unknown): Record<string, unknown> =>
+  value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+
+const flag = (value: unknown): boolean | null => (typeof value === "boolean" ? value : null);
+
+const text = (value: unknown): string | null =>
+  typeof value === "string" && value.trim() ? value.trim() : null;
+
+/**
+ * The tracker from a workspace's `issues` and `youtrack` blocks. Legacy
+ * configs keep their behavior: `youtrack.link_issues: true` reads as
+ * `{ provider: youtrack, link: true }` (and wins over a legacy GitHub
+ * `link_on_pr`, as it always did), `issues.link_on_pr` as `link`, and a bare
+ * `youtrack.baseUrl` as a YouTrack tracker that links only named issues. An
+ * unknown `relation`, `repo` or `host` is a warning, never an error (D17).
+ */
+export function issueTrackerOf(issues: unknown, youtrack: unknown): IssueTracker | null {
+  const iss = asRecord(issues);
+  const yt = asRecord(youtrack);
+  const warnings: string[] = [];
+  const named =
+    typeof iss.provider === "string" && TRACKERS.has(iss.provider.toLowerCase())
+      ? (iss.provider.toLowerCase() as IssueTrackerProvider)
+      : null;
+  if (iss.relation !== undefined && iss.relation !== "closes" && iss.relation !== "refs")
+    warnings.push(
+      `issues.relation ${JSON.stringify(iss.relation)} is not closes or refs; read as closes`,
+    );
+  for (const key of ["repo", "host"] as const)
+    if (iss[key] !== undefined && text(iss[key]) === null)
+      warnings.push(`issues.${key} is not a non-empty string; ignored`);
+  const common = {
+    relation: iss.relation === "refs" ? ("refs" as const) : ("closes" as const),
+    backlink: iss.backlink === true,
+    baseUrl: text(yt.baseUrl),
+    repo: text(iss.repo)?.replace(/^\/+|\/+$/gu, "") ?? null,
+    host: text(iss.host)?.toLowerCase() ?? null,
+    warnings,
+  };
+  const legacyGithub = named === "github" && flag(iss.link) === null;
+  if (flag(yt.link_issues) === true && (named === null || legacyGithub))
+    return { provider: "youtrack", link: true, ...common, source: "youtrack.link_issues" };
+  if (named) {
+    const link =
+      flag(iss.link) ??
+      flag(iss.link_on_pr) ??
+      (named === "youtrack" ? flag(yt.link_issues) : null) ??
+      false;
+    return {
+      provider: named,
+      link,
+      ...common,
+      source:
+        flag(iss.link) === null && flag(iss.link_on_pr) !== null ? "issues.link_on_pr" : "issues",
+    };
+  }
+  if (common.baseUrl)
+    return { provider: "youtrack", link: false, ...common, source: "youtrack.baseUrl" };
+  return null;
+}
+
+/** The release track a vcsConfig call resolved (null: the workspace has no tracks). */
+export type ResolvedReleaseTrack = {
+  name: string | null;
+  source: string;
+  detail: string;
+  warnings: string[];
+  track: RuntimeReleaseTrack | null;
+  /** Every configured track, for displays and the branch policy. */
+  tracks: RuntimeReleaseTrack[];
+  /** The line is undetermined (or WORKIT_RELEASE_TRACK is wrong): mutating verbs refuse. */
+  blocking: string | null;
+};
+
+export type VcsConfigOptions = {
+  /** An explicit release track (`--track`); WORKIT_RELEASE_TRACK is read below it. */
+  track?: string | null;
+  /** Resolve the track for this branch instead of the checked-out one. */
+  branch?: string | null;
+};
+
+const trackSummary = (resolution: TrackResolution): ResolvedReleaseTrack | null =>
+  resolution.status === "resolved"
+    ? {
+        name: resolution.track?.name ?? null,
+        source: resolution.source,
+        detail: resolution.detail,
+        warnings: resolution.warnings,
+        track: resolution.track,
+        tracks: resolution.tracks,
+        blocking: resolution.blocking,
+      }
+    : null;
+
+/** Port of scripts/vcs/config.sh — mode: load | summary | resolve. */
+export function vcsConfig(
+  mode: "load" | "summary" | "resolve",
+  cwd?: string,
+  options: VcsConfigOptions = {},
+): Record<string, any> {
+  const ws = resolveRuntimeWorkspaceVcs(vcsCwd(cwd));
+  const wsVcs = (ws?.vcs ?? {}) as Record<string, any>;
+  const wsYt = (ws?.youtrack ?? {}) as Record<string, any>;
+  const wsIssues = (ws?.issues ?? {}) as Record<string, any>;
+  const { status: cfgStatus, path: cfgPath, config: cfg, error: cfgError } = readVcsConfig();
+
+  // Explicit workspace vcs.provider is the user's per-repo intent and wins;
+  // otherwise, with a determinate repo root (explicit cwd or host-provided
+  // WORKIT_WORKSPACE_ROOT), the origin remote is authoritative over the
+  // global default (RL-03b). Ambient process.cwd() callers keep the legacy
+  // config-only contract (CA-06 parity), so a stale global default cannot
+  // contaminate host-agnostic reads.
+  const root = vcsCwd(cwd);
+  const determinateRoot = cwd !== undefined || process.env.WORKIT_WORKSPACE_ROOT !== undefined;
+  // No silent default: a provider resolves from the workspace, the origin
+  // remote, or the global config — otherwise it is null, explicitly. Branch
+  // policy never needed a provider (preset defaults apply); credential and
+  // PR flows fail closed on null instead of assuming a host.
+  const rawProvider =
+    wsVcs.provider ?? (determinateRoot ? remoteProvider(root) : null) ?? cfg.provider ?? null;
+  const provider =
+    rawProvider === null || rawProvider === undefined
+      ? null
+      : String(rawProvider).toLowerCase() || null;
+  // CA-05: workspace/global explicit target wins; when unset the resolved
+  // branch-policy preset supplies the default (gitflow->develop,
+  // github-flow->main, trunk-based->master, custom->develop). Shared by load
+  // and resolve so both surfaces stay consistent.
+  // CA-09: the one resolver wrapper — same policy resolution every consumer
+  // uses, so the tightened gate in branch-policy-resolver.test.ts stays green.
+  // CA-02: a matched workspace's OWN branchPolicy default beats any global
+  // vcs.json default (PR #43: global develop shadowed the personal github-flow
+  // main). Explicit workspace vcs.defaultTargetBranch stays authoritative; a
+  // workspace without a branchPolicy still falls back to the global vcs.json
+  // default, and unmatched repos keep it too.
+  // CA-05/CA-02 (workspaces.ts workspaceDefaultTarget): shared with doctor
+  // and grant show so their display never disagrees with the commands.
+  const workspaceDefault = workspaceDefaultTarget(root, cfg.defaultTargetBranch);
+  const issueTracker = issueTrackerOf(wsIssues, wsYt);
+  const linkIssues = typeof wsYt.link_issues === "boolean" ? wsYt.link_issues : null;
+  const youtrackBaseUrl = typeof wsYt.baseUrl === "string" ? wsYt.baseUrl : null;
+  // github issues path only when BOTH providers are github (mirrors WorkspaceConfig.issues).
+  let issuesProvider: string | null = null;
+  let linkOnPr: boolean | null = null;
+  if (
+    provider === "github" &&
+    typeof wsIssues.provider === "string" &&
+    wsIssues.provider.toLowerCase() === "github"
+  ) {
+    issuesProvider = "github";
+    linkOnPr = typeof wsIssues.link_on_pr === "boolean" ? wsIssues.link_on_pr : null;
+  }
+
+  if (mode === "resolve") {
+    // RL-01: malformed vcs.json blocks resolution with an exact-path diagnostic
+    // instead of silently resolving defaults; a missing file is still a
+    // legitimate unconfigured state that falls back to defaults.
+    if (cfgStatus === "malformed") return { ok: false, error: cfgError, configPath: cfgPath };
+    // Release tracks (core/release-tracks.ts): the one place a branch's line is
+    // decided, in resolve mode only (load serves identity, push and tracker
+    // paths that never need it). With tracks, the PR target and the base for
+    // new branches come from the resolved track; without, the workspace
+    // default stays as is.
+    const trackResolution = resolveTrackFor(root, {
+      track: options.track,
+      ...(options.branch !== undefined ? { branch: options.branch } : {}),
+      defaultBranch: workspaceDefault,
+    });
+    if (trackResolution.status === "invalid")
+      return { ok: false, error: trackResolution.error, configPath: workspacesPath() };
+    const releaseTrack = trackSummary(trackResolution);
+    const defaultTarget = releaseTrack?.track?.pullRequestTarget ?? workspaceDefault;
+    const baseBranch = releaseTrack?.track?.baseBranch ?? defaultTarget;
+    return {
+      ok: true,
+      workspace_name: ws?.name ?? null,
+      provider,
+      defaultTargetBranch: defaultTarget,
+      /** The target before release tracks (vcs.defaultTargetBranch or the policy default). */
+      workspaceDefaultTargetBranch: workspaceDefault,
+      baseBranch,
+      releaseTrack,
+      link_issues: linkIssues,
+      youtrack_base_url: youtrackBaseUrl,
+      issues_provider: issuesProvider,
+      link_on_pr: linkOnPr,
+      issue_tracker: issueTracker,
+    };
+  }
+
+  if (cfgStatus === "malformed") {
+    return { ok: false, error: cfgError, configPath: cfgPath };
+  }
+  if (cfgStatus === "missing" && provider === null)
+    return { ok: false, error: `vcs.json is missing: ${cfgPath}`, configPath: cfgPath };
+  // Hosting cannot resolve without a provider; branch policy still can.
+  if (provider === null) {
+    return {
+      ok: false,
+      error: `no vcs provider configured (set vcs.provider in ${cfgPath}, match a workspace entry, or run inside a checkout with a recognized origin remote)`,
+      configPath: cfgPath,
+    };
+  }
+
+  const prov = (cfg[provider] ?? {}) as Record<string, any>;
+  const out: Record<string, any> = {
+    ok: true,
+    configPath: path.resolve(cfgPath),
+    provider,
+    // Load mode does not resolve release tracks: the workspace default.
+    defaultTargetBranch: workspaceDefault,
+    pr: cfg.pr ?? {},
+    workspace_name: ws?.name ?? null,
+    link_issues: linkIssues,
+    youtrack_base_url: youtrackBaseUrl,
+    issues_provider: issuesProvider,
+    link_on_pr: linkOnPr,
+    issue_tracker: issueTracker,
+  };
+  if (provider === "gitlab") {
+    out.gitlab = {
+      host: prov.host ?? "gitlab.com",
+      apiUrl: prov.apiUrl ?? "https://gitlab.com/api/v4",
+    };
+  } else if (provider === "github") {
+    out.github = { host: prov.host ?? "github.com" };
+  }
+  return out;
+}
+
+/** Probe the CLI credential actually used for this checkout, never a Workit token file. */
+export function vcsCliIdentity(cwd?: string): Record<string, any> {
+  const root = vcsCwd(cwd);
+  const cfg = vcsConfig("load", root);
+  if (!cfg.ok) return { ok: false, error: cfg.error ?? "vcs config not ready" };
+  const provider = cfg.provider as string;
+  if (provider !== "gitlab" && provider !== "github")
+    return { ok: false, error: `unsupported provider: ${provider}` };
+  const bin = provider === "gitlab" ? "glab" : "gh";
+  const host = String(
+    provider === "github" ? (cfg.github?.host ?? "github.com") : (cfg.gitlab?.host ?? "gitlab.com"),
+  ).toLowerCase();
+  const env = {
+    ...process.env,
+    PATH: process.env.PATH ?? "",
+    ...(provider === "github" ? { GH_HOST: host } : { GITLAB_HOST: host }),
+  };
+  const result = spawnSync(bin, ["api", "user"], {
+    cwd: root,
+    encoding: "utf8",
+    env,
+  });
+  if (result.status !== 0)
+    return { ok: false, provider, error: `${bin} is missing or not authenticated` };
+  try {
+    const user = JSON.parse(result.stdout ?? "") as Record<string, unknown>;
+    const username = provider === "gitlab" ? user.username : user.login;
+    if (typeof username !== "string" || !username)
+      return { ok: false, provider, error: `invalid ${bin} identity response` };
+    const expected = resolveRuntimeWorkspaceVcs(root)?.vcs?.account;
+    if (expected && username.toLowerCase() !== expected.toLowerCase())
+      return {
+        ok: false,
+        provider,
+        error: `${bin} account ${username} does not match ${expected}`,
+      };
+    return { ok: true, provider, host, username, name: user.name };
+  } catch {
+    return { ok: false, provider, error: `invalid JSON from ${bin} api user` };
+  }
+}
+
+/** Legacy command name, now verifies native CLI auth rather than a separate token. */
+/** Port of scripts/vcs/merged-style.sh — recent merged MR/PR bodies for style reference. */
+export function mergedPrStyle(limit = 6, cwd?: string): Record<string, any> {
+  const cfg = vcsConfig("load", cwd);
+  if (!cfg.ok) return { ok: false, error: "vcs not configured" };
+  const provider = cfg.provider as string;
+  const host = String(
+    provider === "github" ? (cfg.github?.host ?? "github.com") : (cfg.gitlab?.host ?? "gitlab.com"),
+  ).toLowerCase();
+  const env = {
+    ...process.env,
+    PATH: process.env.PATH ?? "",
+    ...(provider === "github" ? { GH_HOST: host } : { GITLAB_HOST: host }),
+  };
+  const examples: Array<Record<string, any>> = [];
+
+  const descInfo = (desc: string, caseInsensitiveNotes = false): Record<string, any> => ({
+    hasNotesSection: caseInsensitiveNotes ? /##\s*notes/i.test(desc) : /##\s*Notes/.test(desc),
+    sections: desc
+      .split("\n")
+      .filter((l) => l.startsWith("## "))
+      .map((l) => l.trim()),
+    descriptionPreview: desc.slice(0, 600),
+  });
+
+  const remoteResult = spawnSync("git", ["remote", "get-url", "--push", "--all", "origin"], {
+    cwd,
+    encoding: "utf8",
+  });
+  const remotes = (remoteResult.stdout ?? "")
+    .split(/\r?\n/u)
+    .map((value) => value.trim())
+    .filter(Boolean);
+  if (remotes.length === 0) return { ok: false, error: "no origin remote" };
+  if (remotes.length !== 1) return { ok: false, error: "origin has ambiguous push destinations" };
+  const remote = remotes[0];
+  const endpoint = remoteEndpoint(remote);
+  if (!endpoint?.path) return { ok: false, error: "hosting repository could not be resolved" };
+  if (!hostingApiHostMatches(remote, host))
+    return { ok: false, error: "PR style target does not match the provider host" };
+
+  if (provider === "gitlab") {
+    const run = (args: string[]) =>
+      spawnSync("glab", ["api", ...args], {
+        cwd,
+        encoding: "utf8",
+        env,
+      });
+    let r = run([
+      `projects/${endpoint.path.replaceAll("/", "%2F")}/merge_requests?state=merged&per_page=${limit}&order_by=updated_at&sort=desc`,
+    ]);
+    if (r.status !== 0) return { ok: false, error: "could not list merge requests" };
+    for (const mr of JSON.parse(r.stdout ?? "[]") as Array<Record<string, any>>) {
+      const desc = String(mr.description ?? "").trim();
+      examples.push({
+        title: mr.title,
+        url: mr.web_url,
+        squash: mr.squash,
+        ...descInfo(desc, true),
+      });
+    }
+  } else if (provider === "github") {
+    const r = spawnSync(
+      "gh",
+      [
+        "pr",
+        "list",
+        "--repo",
+        `${host}/${endpoint.path}`,
+        "--state",
+        "merged",
+        "--limit",
+        String(limit),
+        "--json",
+        "title,url,body",
+      ],
+      { cwd, encoding: "utf8", env },
+    );
+    if (r.status !== 0) return { ok: false, error: "could not list pull requests" };
+    for (const pr of JSON.parse(r.stdout ?? "[]") as Array<Record<string, any>>) {
+      const desc = String(pr.body ?? "").trim();
+      examples.push({ title: pr.title, url: pr.url, ...descInfo(desc) });
+    }
+  }
+
+  return {
+    ok: true,
+    provider,
+    count: examples.length,
+    styleHints: [
+      "Prefer ## Summary bullets + ## Validation or ## Test plan only",
+      "Do not add ## Notes with branch names, commit counts, or diff stats",
+      "Do not paste commit log or diff stat into the body",
+    ],
+    examples,
+  };
+}
+
+export const vcsWorkspacesPath = workspacesPath;

package/src/core/workers.ts

@@ -0,0 +1,62 @@
+import type {
+  Caller,
+  Id,
+  Provenance,
+  Ref,
+  Result,
+  Revision,
+  Worker,
+  WorkerReport,
+} from "./task-contract";
+
+export type WorkerState = Worker["state"];
+export type HostSession = Extract<Ref, { kind: "host" }>;
+
+export type NativeWorkerObservation = {
+  taskId: Id;
+  workerId: Id;
+  expectedRevision: Revision;
+  expectedWorkspaceRevision: Revision;
+  state: WorkerState;
+  session: HostSession | null;
+  report?: WorkerReport;
+  observation: unknown;
+};
+
+export type NativeWorkerVerification = {
+  observation: unknown;
+  expected: Omit<NativeWorkerObservation, "observation"> & {
+    workspaceId: Id;
+  };
+  caller: Caller;
+};
+
+/** A host that observes its own child sessions attests their lifecycle. */
+export type NativeWorkerVerifier = {
+  verifyWorker: (input: NativeWorkerVerification) => Result<Provenance>;
+};
+
+/** The one shared definition of active or uncertain worker state used by
+ * close, revise, resume, and replacement-launch checks. */
+export const UNCERTAIN_WORKER_STATES = ["dispatching", "running", "cancelling", "unknown"] as const;
+export const isUncertainWorker = (state: WorkerState): boolean =>
+  (UNCERTAIN_WORKER_STATES as readonly string[]).includes(state);
+
+/**
+ * Lifecycle gate table: which worker states block each lead transition.
+ * Pause freezes, so live workers never block it; resume, revise, and close
+ * must reconcile first.
+ */
+export const workerBlocksTransition = (
+  transition: "pause" | "resume" | "revise" | "close",
+  state: WorkerState,
+): boolean => (transition === "pause" ? false : isUncertainWorker(state));
+
+/**
+ * A worker may be continued in its own session only while it holds live
+ * state: a running process, or uncommitted changes in its worktree. A worker
+ * that reported and is clean is continued by a fresh worker on the same
+ * slice. An unreadable worktree counts as no live state.
+ */
+export const holdsLiveState = (state: WorkerState, dirty: boolean | null): boolean =>
+  state === "running" || dirty === true;