@helmsmith/workbrokr 0.1.0 → 0.3.0

package/dist/core/index.js

@@ -0,0 +1,1576 @@
+// src/core/config.ts
+import {
+  appendFileSync,
+  existsSync as existsSync2,
+  mkdirSync as mkdirSync2,
+  readFileSync,
+  realpathSync as realpathSync2,
+  writeFileSync
+} from "fs";
+import { join as join2 } from "path";
+
+// src/core/errors.ts
+var REFUSALS = /* @__PURE__ */ new Set([
+  "MANIFEST_INVALID",
+  "AREA_UNKNOWN",
+  "TASK_INVALID",
+  "TYPE_UNKNOWN",
+  "MODE_UNKNOWN",
+  "MODE_MISMATCH",
+  "SCOPE_REQUIRES_TASK",
+  "SCOPE_OUTSIDE_AREA",
+  "MAIN_CHECKOUT",
+  "WORKTREE_INVALID",
+  "PROTECTED_BRANCH",
+  "EFFORT_OPEN",
+  "EFFORT_NOT_FOUND",
+  "SCOPE_CONFLICT",
+  "COMMONS_LOCKED",
+  "NO_FREE_SLOT",
+  "LEASE_NOT_FOUND",
+  "PORT_RANGE_TAKEN",
+  "SYNC_CONFLICT",
+  "DIRTY_WORKTREE",
+  "UNPUSHED",
+  "PR_CLOSED"
+]);
+function exitCodeFor(code) {
+  return REFUSALS.has(code) ? 2 : 1;
+}
+var WorkkitError = class extends Error {
+  code;
+  details;
+  constructor(code, message, details) {
+    super(message);
+    this.name = "WorkkitError";
+    this.code = code;
+    if (details) this.details = details;
+  }
+};
+function toErrorBody(err) {
+  if (err instanceof WorkkitError) {
+    return err.details ? { code: err.code, message: err.message, details: err.details } : { code: err.code, message: err.message };
+  }
+  return { code: "INTERNAL", message: err instanceof Error ? err.message : String(err) };
+}
+
+// src/core/git.ts
+import { spawnSync } from "child_process";
+import { existsSync, mkdirSync, realpathSync, rmSync, statSync } from "fs";
+import { dirname, join, resolve, sep } from "path";
+var realpathOr = (p) => {
+  try {
+    return realpathSync(p);
+  } catch {
+    return p;
+  }
+};
+var SAFE_SUBMODULE_NAME = /^[^\p{Cc}\s=]+$/u;
+var Git = class _Git {
+  constructor(cwd) {
+    this.cwd = cwd;
+  }
+  cwd;
+  tryRun(args) {
+    const r = spawnSync("git", args, { cwd: this.cwd, encoding: "utf8" });
+    return { code: r.status ?? 1, out: r.stdout ?? "", err: r.stderr ?? "" };
+  }
+  run(args) {
+    const r = this.tryRun(args);
+    if (r.code !== 0) {
+      throw new WorkkitError(
+        "GIT_FAILED",
+        `git ${args.join(" ")} (in ${this.cwd}): ${r.err.trim() || r.out.trim()}`,
+        {
+          args,
+          cwd: this.cwd
+        }
+      );
+    }
+    return r.out;
+  }
+  lines(args) {
+    return this.run(args).split("\n").map((l) => l.trim()).filter(Boolean);
+  }
+  /** The checkout's top level (symlinks resolved). */
+  root() {
+    return realpathSync(this.run(["rev-parse", "--show-toplevel"]).trim());
+  }
+  /** The main checkout's top level, from any worktree of the repo. */
+  mainRoot() {
+    const common = realpathSync(
+      this.run(["rev-parse", "--path-format=absolute", "--git-common-dir"]).trim()
+    );
+    return dirname(common);
+  }
+  /** The main checkout is the one whose git dir IS the common dir (compared as absolute realpaths). */
+  isMainCheckout() {
+    const gitDir = realpathSync(
+      this.run(["rev-parse", "--path-format=absolute", "--git-dir"]).trim()
+    );
+    const common = realpathSync(
+      this.run(["rev-parse", "--path-format=absolute", "--git-common-dir"]).trim()
+    );
+    return gitDir === common;
+  }
+  currentBranch() {
+    return this.run(["branch", "--show-current"]).trim();
+  }
+  branchExists(name) {
+    return this.tryRun(["rev-parse", "--verify", "-q", `refs/heads/${name}`]).code === 0;
+  }
+  remoteBranchExists(name) {
+    return this.run(["ls-remote", "--heads", "origin", name]).trim().length > 0;
+  }
+  fetch(branch) {
+    this.run(["fetch", "-q", "origin", branch]);
+  }
+  hasUpstream() {
+    return this.tryRun(["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"]).code === 0;
+  }
+  /** Commits on HEAD that origin does not have: against the upstream, else the same-named remote branch, else origin/<base>. */
+  unpushedCount(base) {
+    let ref = `origin/${base}`;
+    if (this.hasUpstream()) ref = "@{u}";
+    else if (this.remoteBranchExists(this.currentBranch())) ref = `origin/${this.currentBranch()}`;
+    return this.lines(["rev-list", `${ref}..HEAD`]).length;
+  }
+  /** Commits on origin/<base> that HEAD does not have (0 when the ref is unknown). */
+  behindCount(base) {
+    const r = this.tryRun(["rev-list", "--count", `HEAD..origin/${base}`]);
+    return r.code === 0 ? Number(r.out.trim()) || 0 : 0;
+  }
+  isDirty() {
+    return this.run(["status", "--porcelain"]).trim().length > 0;
+  }
+  changedPathsStaged() {
+    return this.lines(["diff", "--cached", "--name-only"]);
+  }
+  /** The other parent of a merge in progress, or undefined when none is. */
+  mergeHead() {
+    const r = this.tryRun(["rev-parse", "-q", "--verify", "MERGE_HEAD"]);
+    return r.code === 0 ? r.out.trim() : void 0;
+  }
+  /** Staged paths whose index content differs from `ref` (so, authored here rather than taken from `ref`). */
+  stagedDifferingFrom(ref, paths) {
+    if (paths.length === 0) return [];
+    return this.lines(["diff", "--cached", "--name-only", "--no-renames", ref, "--", ...paths]);
+  }
+  changedPaths(from, to) {
+    return this.lines(["diff", "--name-only", "--no-renames", from, to]);
+  }
+  /** Paths this branch changed since it diverged from origin/<base> (three-dot), without the base's own changes. */
+  changedSince(base) {
+    return this.lines(["diff", "--name-only", "--no-renames", `origin/${base}...HEAD`]);
+  }
+  commitsNotOn(base) {
+    return this.lines(["rev-list", `origin/${base}..HEAD`]);
+  }
+  rev(ref) {
+    return this.run(["rev-parse", ref]).trim();
+  }
+  /** Fast-forward when HEAD has no own commits, otherwise merge; never rebase. A conflict is left in place. */
+  syncFrom(base) {
+    const target = `origin/${base}`;
+    const before = this.rev("HEAD");
+    const targetRev = this.rev(target);
+    if (before === targetRev) return { kind: "up-to-date", before, after: before, conflicted: [] };
+    if (this.tryRun(["merge-base", "--is-ancestor", "HEAD", target]).code === 0) {
+      this.run(["merge", "--ff-only", "-q", target]);
+      return { kind: "ff", before, after: this.rev("HEAD"), conflicted: [] };
+    }
+    if (this.tryRun(["merge-base", "--is-ancestor", target, "HEAD"]).code === 0) {
+      return { kind: "up-to-date", before, after: before, conflicted: [] };
+    }
+    const merged = this.tryRun(["merge", "--no-edit", "-q", target]);
+    if (merged.code === 0)
+      return { kind: "merge", before, after: this.rev("HEAD"), conflicted: [] };
+    const conflicted = this.lines(["diff", "--name-only", "--diff-filter=U"]);
+    return { kind: "conflict", before, after: before, conflicted };
+  }
+  /** `origin/<branch>` after a fetch attempt, when the remote has it; the local copy may have been retired. */
+  remoteRef(branch) {
+    this.tryRun(["fetch", "-q", "origin", branch]);
+    const ref = `refs/remotes/origin/${branch}`;
+    return this.tryRun(["rev-parse", "--verify", "-q", ref]).code === 0 ? `origin/${branch}` : void 0;
+  }
+  /**
+   * Add a worktree on `branch`: the local branch if it exists, else a tracking
+   * branch from origin/<branch> if the remote has it (so retiring the local
+   * branch while its PR was open never recreates it from the base), else a
+   * new branch from `startPoint`.
+   */
+  worktreeAdd(path, branch, startPoint) {
+    mkdirSync(dirname(path), { recursive: true });
+    if (this.branchExists(branch)) {
+      this.run(["worktree", "add", "-q", path, branch]);
+      return;
+    }
+    const remote = this.remoteRef(branch);
+    if (remote) {
+      this.run(["worktree", "add", "-q", "--track", "-b", branch, path, remote]);
+      return;
+    }
+    this.run(["worktree", "add", "-q", "--no-track", "-b", branch, path, startPoint ?? "HEAD"]);
+  }
+  worktreeRemove(path) {
+    this.run(["worktree", "remove", "--force", path]);
+  }
+  checkout(branch, createFrom) {
+    if (this.branchExists(branch)) {
+      this.run(["checkout", "-q", branch]);
+      return;
+    }
+    const remote = this.remoteRef(branch);
+    if (remote) {
+      this.run(["checkout", "-q", "--track", "-b", branch, remote]);
+      return;
+    }
+    this.run(["checkout", "-q", "--no-track", "-b", branch, createFrom ?? "HEAD"]);
+  }
+  push(branch) {
+    this.run(["push", "-q", "-u", "origin", branch]);
+  }
+  deleteLocalBranch(branch) {
+    this.run(["branch", "-q", "-D", branch]);
+  }
+  isAncestor(ancestor, descendant) {
+    return this.tryRun(["merge-base", "--is-ancestor", ancestor, descendant]).code === 0;
+  }
+  /** True when HEAD's tree matches origin/<base>, or every commit on HEAD is patch-equivalent to origin/<base> (squash-merged). */
+  isEquivalentToBase(base) {
+    const target = `origin/${base}`;
+    if (this.tryRun(["diff", "--quiet", target, "HEAD"]).code === 0) return true;
+    const cherry = this.tryRun(["cherry", target, "HEAD"]);
+    if (cherry.code !== 0) return false;
+    const lines = cherry.out.split("\n").map((l) => l.trim()).filter(Boolean);
+    return lines.length > 0 && lines.every((l) => l.startsWith("- "));
+  }
+  /**
+   * Give a linked worktree its own clone of every submodule the main checkout has initialized,
+   * cloned locally from the main checkout's module directory (no network) and then re-pointed at
+   * the real URL. `git worktree add` under submodule.recurse leaves a gitfile aimed at a module
+   * directory that was never cloned; a gitfile aimed at the MAIN checkout's module directory is
+   * worse, because that module's core.worktree is the main checkout's submodule, so any git
+   * command in the worktree's submodule (checkout -f, reset, merge) rewrites the human's files.
+   * Both shapes are replaced; a submodule that is already its own working tree is left alone.
+   */
+  repairSubmodules(mainRoot, log = () => {
+  }) {
+    const gitmodules = join(this.cwd, ".gitmodules");
+    if (!existsSync(gitmodules)) return;
+    const cfg = this.tryRun([
+      "config",
+      "-f",
+      ".gitmodules",
+      "--get-regexp",
+      "^submodule\\..*\\.path$"
+    ]);
+    if (cfg.code !== 0) return;
+    const wtGitDir = this.run(["rev-parse", "--path-format=absolute", "--git-dir"]).trim();
+    for (const line of cfg.out.split("\n").filter(Boolean)) {
+      const m = /^submodule\.(.+)\.path\s+(.+)$/.exec(line.trim());
+      if (!m) continue;
+      const [, name, subPath] = m;
+      const modulesDir = resolve(wtGitDir, "modules");
+      const moduleDir = resolve(modulesDir, name);
+      if (!SAFE_SUBMODULE_NAME.test(name) || name.split(/[\\/]/).some((seg) => seg === "" || seg === "." || seg === "..") || !moduleDir.startsWith(modulesDir + sep)) {
+        log(`submodule ${subPath}: refusing name ${JSON.stringify(name)}; not repaired`);
+        continue;
+      }
+      const wtSub = join(this.cwd, subPath);
+      const wtGit = join(wtSub, ".git");
+      if (this.isOwnSubmodule(wtSub, wtGit)) continue;
+      const mainSub = join(mainRoot, subPath);
+      if (!existsSync(join(mainSub, ".git"))) continue;
+      const src = new _Git(mainSub).tryRun(["rev-parse", "--path-format=absolute", "--git-dir"]);
+      if (src.code !== 0 || !src.out.trim()) continue;
+      if (existsSync(wtGit) && statSync(wtGit).isFile()) rmSync(wtGit);
+      rmSync(moduleDir, { recursive: true, force: true });
+      const r = this.tryRun([
+        "-c",
+        "protocol.file.allow=always",
+        "-c",
+        `submodule.${name}.url=${src.out.trim()}`,
+        "submodule",
+        "update",
+        "--init",
+        "--",
+        subPath
+      ]);
+      if (r.code !== 0) {
+        log(
+          `submodule ${subPath}: not repaired (${(r.err || r.out).trim()}); the project's refresh steps may still set it up`
+        );
+        continue;
+      }
+      this.tryRun(["submodule", "sync", "-q", "--", subPath]);
+    }
+  }
+  /** A submodule is the worktree's own when git, run inside it, says its top level IS that directory. */
+  isOwnSubmodule(wtSub, wtGit) {
+    if (!existsSync(wtGit)) return false;
+    const top = new _Git(wtSub).tryRun(["rev-parse", "--show-toplevel"]);
+    if (top.code !== 0) return false;
+    return realpathOr(top.out.trim()) === realpathOr(wtSub);
+  }
+};
+
+// src/core/config.ts
+function renderTemplate(s, vars) {
+  return s.replace(/\$\{([A-Z0-9_]+)\}/g, (_, name) => {
+    if (!(name in vars)) {
+      throw new WorkkitError(
+        "MANIFEST_INVALID",
+        `template references ${name}, which this effort does not define`
+      );
+    }
+    return vars[name];
+  });
+}
+function storybookHostFor(m, worktree) {
+  if (!worktree) return "";
+  return m.storybook?.hostRoot ? join2(worktree, m.storybook.hostRoot) : worktree;
+}
+function slotVars(m, o) {
+  const vars = {
+    SLOT: o.slot === void 0 ? "" : String(o.slot),
+    PROJECT: m.project,
+    AREA: o.area ?? "",
+    BRANCH: o.branch ?? "",
+    WORKTREE: o.worktree ?? "",
+    LOG_DIR: o.logDir ?? "",
+    STORYBROKR_HOST: storybookHostFor(m, o.worktree)
+  };
+  for (const service of Object.keys(m.ports.services)) {
+    const p = o.ports[service];
+    vars[`PORT_${service.toUpperCase()}`] = p === void 0 ? "" : String(p);
+  }
+  if (o.storybookPort !== void 0) vars.PORT_STORYBOOK = String(o.storybookPort);
+  else if (vars.PORT_STORYBOOK === void 0) vars.PORT_STORYBOOK = "";
+  return vars;
+}
+function ensureExcluded(worktree, patterns) {
+  const r = new Git(worktree).tryRun(["rev-parse", "--path-format=absolute", "--git-common-dir"]);
+  if (r.code !== 0) return;
+  const common = realpathSync2(r.out.trim());
+  const file = join2(common, "info", "exclude");
+  mkdirSync2(join2(common, "info"), { recursive: true });
+  const present = new Set(
+    existsSync2(file) ? readFileSync(file, "utf8").split("\n").map((l) => l.trim()) : []
+  );
+  const missing = patterns.filter((p) => !present.has(p));
+  if (missing.length === 0) return;
+  appendFileSync(
+    file,
+    `${present.size ? "\n" : ""}# written by @helmsmith/workbrokr: per-worktree config and logs
+${missing.join("\n")}
+`
+  );
+}
+function emitWorktreeConfig(a) {
+  ensureExcluded(a.worktree, [
+    ".slot",
+    a.m.env.file,
+    `${a.m.logs.dir.replace(/\/+$/, "")}/`,
+    `${a.m.worktreeRoot.replace(/\/+$/, "")}/`
+  ]);
+  const logDir = join2(a.worktree, a.m.logs.dir);
+  mkdirSync2(logDir, { recursive: true });
+  const vars = slotVars(a.m, { ...a, logDir });
+  const envFile = join2(a.worktree, a.m.env.file);
+  const lines = Object.entries(a.m.env.template).map(([k, v]) => `${k}=${renderTemplate(v, vars)}`);
+  writeFileSync(envFile, `${lines.join("\n")}
+`);
+  let slotFile;
+  if (a.slot !== void 0) {
+    slotFile = join2(a.worktree, ".slot");
+    writeFileSync(slotFile, `${a.slot}
+`);
+  }
+  return slotFile ? { envFile, slotFile, logDir, vars } : { envFile, logDir, vars };
+}
+
+// src/core/guards.ts
+import { existsSync as existsSync3, realpathSync as realpathSync3 } from "fs";
+
+// src/core/scopes.ts
+import picomatch from "picomatch";
+function areaVars(area) {
+  const parts = area.split("/");
+  return { group: parts.slice(0, -1).join("/"), section: parts[parts.length - 1] };
+}
+function fill(template, vars) {
+  let missing = false;
+  const out = template.replace(/\{(group|section|module)\}/g, (_, name) => {
+    const v = vars[name];
+    if (v === void 0 || v === "") {
+      missing = true;
+      return "";
+    }
+    return v;
+  });
+  return missing ? null : out;
+}
+function extraScopesForMode(spec, mode) {
+  if (!spec.extraScopes) return [];
+  if (Array.isArray(spec.extraScopes)) {
+    return mode === "frontend" || mode === "fullstack" ? spec.extraScopes : [];
+  }
+  const out = [];
+  if (mode === "frontend" || mode === "fullstack") out.push(...spec.extraScopes.frontend ?? []);
+  if (mode === "backend" || mode === "fullstack") out.push(...spec.extraScopes.backend ?? []);
+  return out;
+}
+var normalizeGlob = (g) => g.replace(/^\.\//, "").replace(/\/+$/, "");
+var hasWildcard = (s) => /[*?[{]/.test(s);
+function isSubGlob(child, parent) {
+  const c = normalizeGlob(child);
+  const p = normalizeGlob(parent);
+  if (c === p) return true;
+  const cSegs = c.split("/");
+  const pSegs = p.split("/");
+  for (let i = 0; i < pSegs.length; i++) {
+    const ps = pSegs[i];
+    if (ps === "**") return true;
+    const cs = cSegs[i];
+    if (cs === void 0 || cs === "**") return false;
+    if (!hasWildcard(ps) && !hasWildcard(cs)) {
+      if (ps !== cs) return false;
+      continue;
+    }
+    if (!hasWildcard(cs) && hasWildcard(ps)) {
+      if (!picomatch.isMatch(cs, ps, { dot: true })) return false;
+      continue;
+    }
+    if (cs !== ps) return false;
+  }
+  return cSegs.length === pSegs.length;
+}
+function expandScopes(m, area, mode, narrowedScopes, hasTask = false) {
+  const spec = m.areas[area];
+  if (!spec)
+    throw new WorkkitError(
+      "AREA_UNKNOWN",
+      `unknown area "${area}" (known: ${Object.keys(m.areas).join(", ")})`
+    );
+  const vars = { ...areaVars(area), module: spec.module };
+  const out = [];
+  if (mode === "frontend" || mode === "fullstack") {
+    for (const t of m.scopes.frontend) {
+      const g = fill(t, vars);
+      if (g) out.push(g);
+    }
+  }
+  if (mode === "backend" || mode === "fullstack") {
+    if (!spec.module) {
+      throw new WorkkitError(
+        "MANIFEST_INVALID",
+        `area "${area}" has no module, so a ${mode} effort cannot hold a backend scope; add areas["${area}"].module or use --mode frontend`
+      );
+    }
+    for (const t of m.scopes.backend) {
+      const g = fill(t, vars);
+      if (g) out.push(g);
+    }
+  }
+  out.push(...extraScopesForMode(spec, mode));
+  if (!narrowedScopes || narrowedScopes.length === 0) return out;
+  if (!hasTask) {
+    throw new WorkkitError(
+      "SCOPE_REQUIRES_TASK",
+      "--scope narrowing requires --task <slug> so primary area efforts always protect the full area"
+    );
+  }
+  const allowed = [...out, ...spec.sharedScopes ?? []];
+  for (const g of narrowedScopes) {
+    if (!allowed.some((base) => isSubGlob(g, base))) {
+      throw new WorkkitError(
+        "SCOPE_OUTSIDE_AREA",
+        `narrowed scope "${g}" is outside ${area}'s ${mode} scopes (${allowed.join(", ")})`,
+        { area, mode, scope: g, allowed }
+      );
+    }
+  }
+  return narrowedScopes;
+}
+function allowedScopesForEffort(m, effort) {
+  const shared = m.areas[effort.area]?.sharedScopes ?? [];
+  const allCommons = Object.values(m.commons).flat();
+  return [...effort.scopes, ...shared, ...allCommons];
+}
+function literalPrefix(glob) {
+  const i = glob.search(/[*?[{]/);
+  return i < 0 ? glob : glob.slice(0, i);
+}
+function segmentsOverlap(sx, sy) {
+  if (sx === sy) return true;
+  const wx = hasWildcard(sx);
+  const wy = hasWildcard(sy);
+  if (!wx && !wy) return false;
+  if (!wx && wy) return picomatch.isMatch(sx, sy, { dot: true });
+  if (wx && !wy) return picomatch.isMatch(sy, sx, { dot: true });
+  const starToken = /^\*([^*?[{]+)\*$/;
+  const mx = starToken.exec(sx);
+  const my = starToken.exec(sy);
+  if (mx && my) {
+    const tx = mx[1];
+    const ty = my[1];
+    return tx.includes(ty) || ty.includes(tx);
+  }
+  return true;
+}
+function twoGlobsOverlap(x, y) {
+  const xs = normalizeGlob(x).split("/");
+  const ys = normalizeGlob(y).split("/");
+  const len = Math.min(xs.length, ys.length);
+  for (let i = 0; i < len; i++) {
+    if (xs[i] === "**" || ys[i] === "**") return true;
+    if (!segmentsOverlap(xs[i], ys[i])) return false;
+  }
+  if (xs.length === ys.length) return true;
+  const longer = xs.length > ys.length ? xs : ys;
+  return longer[len] === "**";
+}
+function globsOverlap(a, b) {
+  const pairs = [];
+  for (const x of a) {
+    for (const y of b) {
+      if (twoGlobsOverlap(x, y)) pairs.push(`${x} ~ ${y}`);
+    }
+  }
+  return pairs;
+}
+function pathsMatching(paths, globs) {
+  if (globs.length === 0) return [];
+  const isMatch = picomatch(globs, { dot: true });
+  return paths.filter((p) => isMatch(p));
+}
+function commonsTouched(m, paths) {
+  return Object.entries(m.commons).filter(([, globs]) => pathsMatching(paths, globs).length > 0).map(([name]) => name);
+}
+
+// src/core/guards.ts
+function assertNotProtected(m, branch) {
+  if (m.protectedBranches.includes(branch)) {
+    throw new WorkkitError(
+      "PROTECTED_BRANCH",
+      `branch "${branch}" is protected (${m.protectedBranches.join(", ")}): work happens on <type>/<area> branches, never here`,
+      { branch }
+    );
+  }
+}
+function assertNotMainCheckout(git) {
+  if (git.isMainCheckout()) {
+    throw new WorkkitError(
+      "MAIN_CHECKOUT",
+      `${git.cwd} is the main checkout, which is a mirror of the base branch: run \`work start\` to get an area worktree`,
+      { cwd: git.cwd }
+    );
+  }
+}
+var same = (a, b) => {
+  try {
+    return realpathSync3(a) === realpathSync3(b);
+  } catch {
+    return a === b;
+  }
+};
+var effortLabel = (e) => e.task ? `${e.area}--${e.task}` : e.area;
+function checkCommit(c) {
+  const refusals = [];
+  const warnings = [];
+  if (c.m.protectedBranches.includes(c.branch)) {
+    refusals.push(
+      `branch "${c.branch}" is protected (${c.m.protectedBranches.join(", ")}): work happens on <type>/<area> branches, never here`
+    );
+  }
+  const mergeHead = c.git.mergeHead();
+  const authored = mergeHead ? new Set(c.git.stagedDifferingFrom(mergeHead, c.stagedPaths)) : new Set(c.stagedPaths);
+  const ownPaths = c.stagedPaths.filter((p) => authored.has(p));
+  const allEfforts = c.registry.efforts({ project: c.project });
+  const efforts = new Map(allEfforts.map((e) => [e.id, e]));
+  const openEfforts = allEfforts.filter((e) => e.state === "active" || e.state === "starting");
+  const mine = openEfforts.find(
+    (e) => c.checkoutRoot && existsSync3(e.worktree) ? same(e.worktree, c.checkoutRoot) : e.branch === c.branch
+  );
+  for (const lease of c.registry.leases({ project: c.project, kind: "commons" })) {
+    const holder = efforts.get(lease.effort);
+    const holderHasWorktree = Boolean(holder && existsSync3(holder.worktree));
+    if (holder && holderHasWorktree && c.checkoutRoot) {
+      if (same(holder.worktree, c.checkoutRoot)) continue;
+    } else if (lease.owner.session === c.ownerSession) {
+      continue;
+    }
+    if (holder && mine && holder.area === mine.area) continue;
+    const globs = c.m.commons[String(lease.value)] ?? [];
+    const hit = pathsMatching(ownPaths, globs);
+    if (hit.length > 0) {
+      refusals.push(
+        `commons "${lease.value}" is write-locked by ${lease.owner.session} (effort ${lease.effort}, since ${lease.touched}); staged: ${hit.join(", ")}`
+      );
+    }
+  }
+  for (const other of openEfforts) {
+    if (c.checkoutRoot && existsSync3(other.worktree) && same(other.worktree, c.checkoutRoot)) {
+      continue;
+    }
+    if (!c.checkoutRoot && other.branch === c.branch) continue;
+    const hit = pathsMatching(ownPaths, other.scopes);
+    if (hit.length > 0) {
+      refusals.push(
+        `path(s) ${hit.join(", ")} are inside the active scope of ${effortLabel(other)} (${other.branch}, owned by ${other.owner.session})`
+      );
+    }
+  }
+  if (mine && ownPaths.length > 0) {
+    const allowed = allowedScopesForEffort(c.m, mine);
+    const inScope = new Set(pathsMatching(ownPaths, allowed));
+    const outside = ownPaths.filter((p) => !inScope.has(p));
+    if (outside.length > 0) {
+      warnings.push(
+        `${outside.length} staged path(s) are outside the effort's scope (${effortLabel(mine)}): ${outside.join(", ")}`
+      );
+    }
+  }
+  return { refusals, warnings };
+}
+function checkPush(c) {
+  const refusals = [];
+  const warnings = [];
+  const destination = (c.remoteRef ?? `refs/heads/${c.branch}`).replace(/^refs\/heads\//, "");
+  if (c.m.protectedBranches.includes(destination)) {
+    refusals.push(
+      c.isDelete ? `refusing to delete protected branch "${destination}"` : `"${destination}" is protected (${c.m.protectedBranches.join(", ")}): nothing is pushed to it directly, open a PR from ${c.branch || "an area branch"}`
+    );
+    return { refusals, warnings };
+  }
+  if (c.isDelete) return { refusals, warnings };
+  const effort = c.registry.efforts({ project: c.project }).find((e) => (e.state === "active" || e.state === "parked") && e.branch === c.branch);
+  const commons = commonsTouched(c.m, c.changedPaths);
+  if (effort) {
+    const allowed = allowedScopesForEffort(c.m, effort);
+    const inScope = new Set(pathsMatching(c.changedPaths, allowed));
+    const outside = c.changedPaths.filter((p) => !inScope.has(p));
+    if (outside.length > 0) {
+      warnings.push(
+        `${outside.length} changed path(s) are outside the effort's scope (${effortLabel(effort)}): ${outside.join(", ")} \u2014 add a scope template or expect a merge collision`
+      );
+    }
+  }
+  for (const name of commons)
+    warnings.push(`commons ${name} touched: the other areas are told at \`work finish\``);
+  return { refusals, warnings };
+}
+
+// src/core/hooks.ts
+import { chmodSync, lstatSync, mkdirSync as mkdirSync3, writeFileSync as writeFileSync2 } from "fs";
+import { join as join4 } from "path";
+
+// src/core/manifest.ts
+import { existsSync as existsSync4, readFileSync as readFileSync2 } from "fs";
+import { join as join3 } from "path";
+import { pathToFileURL } from "url";
+import { z } from "zod";
+var MANIFEST_FILES = [
+  "helmsmith.config.ts",
+  "helmsmith.config.mjs",
+  "helmsmith.config.json"
+];
+var BRANCH_NAME = /^[A-Za-z0-9][A-Za-z0-9._/-]*$/;
+var BRANCH_NAME_HINT = 'must be a plain ref name: letters, digits, ".", "_", "/", "-"';
+var TASK_SLUG = /^(?!.*--)[a-z0-9][a-z0-9_-]{0,47}$/;
+var Service = z.object({
+  start: z.string().min(1),
+  stop: z.string().min(1),
+  health: z.string().min(1),
+  healthyCodes: z.array(z.number().int()).optional(),
+  reset: z.string().optional(),
+  healthTimeoutMs: z.number().int().positive().optional(),
+  modes: z.array(z.enum(["backend", "fullstack"])).optional()
+});
+var ExtraScopes = z.union([
+  z.array(z.string()),
+  z.object({
+    frontend: z.array(z.string()).optional(),
+    backend: z.array(z.string()).optional()
+  })
+]);
+var Schema = z.object({
+  project: z.string().regex(/^[a-z0-9][a-z0-9-]*$/),
+  baseBranch: z.string().regex(BRANCH_NAME, BRANCH_NAME_HINT),
+  protectedBranches: z.array(z.string().regex(BRANCH_NAME, BRANCH_NAME_HINT)).optional(),
+  worktreeRoot: z.string().default(".claude/worktrees"),
+  branch: z.object({ types: z.array(z.string().regex(/^[a-z]+$/)).min(1) }).default({ types: ["feature", "chore", "fix"] }),
+  slots: z.object({
+    count: z.number().int().min(1).max(100),
+    reserved: z.array(z.number().int().min(0))
+  }).default({ count: 10, reserved: [0] }),
+  ports: z.object({
+    services: z.record(z.string(), z.object({ base: z.number().int().min(1024).max(65535) }))
+  }),
+  services: z.record(z.string(), Service),
+  storybook: z.object({ hostRoot: z.string() }).optional(),
+  logs: z.object({ dir: z.string() }).default({ dir: ".logs" }),
+  env: z.object({ file: z.string(), template: z.record(z.string(), z.string()) }).optional(),
+  seed: z.array(z.string().min(1)).optional(),
+  refresh: z.array(
+    z.object({
+      when: z.string().optional(),
+      always: z.boolean().optional(),
+      run: z.string().optional(),
+      mark: z.string().optional(),
+      restoreWhenIfClean: z.boolean().optional()
+    })
+  ).default([]),
+  scopes: z.object({ frontend: z.array(z.string()), backend: z.array(z.string()) }),
+  areas: z.record(
+    z.string().regex(/^(?!.*--)[a-z0-9-]+(\/[a-z0-9-]+)*$/),
+    z.object({
+      module: z.string().optional(),
+      commons: z.array(z.string()).optional(),
+      extraScopes: ExtraScopes.optional(),
+      sharedScopes: z.array(z.string()).optional()
+    })
+  ),
+  commons: z.record(z.string(), z.array(z.string())).default({}),
+  expiry: z.object({
+    slotHours: z.number().positive(),
+    commonsHours: z.number().positive(),
+    storybookHours: z.number().positive()
+  }).default({ slotHours: 12, commonsHours: 4, storybookHours: 2 }),
+  archive: z.object({
+    paths: z.array(z.string()),
+    keepDays: z.number().int().positive(),
+    keepPerArea: z.number().int().positive()
+  }).default({ paths: [], keepDays: 30, keepPerArea: 5 })
+});
+function templateVariables(m) {
+  const vars = /* @__PURE__ */ new Set([
+    "SLOT",
+    "LOG_DIR",
+    "PROJECT",
+    "AREA",
+    "BRANCH",
+    "WORKTREE",
+    "PORT_STORYBOOK",
+    "STORYBROKR_HOST"
+  ]);
+  for (const s of Object.keys(m.ports.services)) vars.add(`PORT_${s.toUpperCase()}`);
+  return vars;
+}
+function defaultEnv(services) {
+  const template = {
+    // biome-ignore lint/suspicious/noTemplateCurlyInString: manifest template placeholder
+    SLOT: "${SLOT}",
+    // biome-ignore lint/suspicious/noTemplateCurlyInString: manifest template placeholder
+    LOG_DIR: "${LOG_DIR}",
+    // biome-ignore lint/suspicious/noTemplateCurlyInString: manifest template placeholder
+    STORYBROKR_HOST: "${STORYBROKR_HOST}"
+  };
+  for (const s of services) template[`PORT_${s.toUpperCase()}`] = `\${PORT_${s.toUpperCase()}}`;
+  return { file: ".env.slot", template };
+}
+function validateManifest(raw) {
+  const parsed = Schema.safeParse(raw);
+  if (!parsed.success) {
+    throw new WorkkitError(
+      "MANIFEST_INVALID",
+      parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")
+    );
+  }
+  const m = parsed.data;
+  const problems = [];
+  const areas = Object.keys(m.areas).sort();
+  for (const a of areas) {
+    for (const b of areas) {
+      if (a !== b && b.startsWith(`${a}/`)) {
+        problems.push(`area "${a}" is an ancestor of "${b}": areas must be leaves`);
+      }
+    }
+  }
+  for (const s of Object.keys(m.services)) {
+    if (!m.ports.services[s]) problems.push(`service "${s}" has no port base under ports.services`);
+  }
+  for (const s of Object.keys(m.ports.services)) {
+    if (!m.services[s] && s !== "storybook") problems.push(`port "${s}" names no service`);
+  }
+  for (const r of m.slots.reserved) {
+    if (r >= m.slots.count) problems.push(`reserved slot ${r} is outside 0..${m.slots.count - 1}`);
+  }
+  const env = m.env ?? defaultEnv(Object.keys(m.ports.services));
+  const allowed = templateVariables(m);
+  for (const [k, v] of Object.entries(env.template)) {
+    for (const [, name] of v.matchAll(/\$\{([A-Z0-9_]+)\}/g)) {
+      if (!allowed.has(name)) {
+        problems.push(
+          `env.template.${k} references ${name}, which no slot derives (allowed: ${[...allowed].join(", ")})`
+        );
+      }
+    }
+  }
+  for (const [area, spec] of Object.entries(m.areas)) {
+    for (const c of spec.commons ?? []) {
+      if (!m.commons[c])
+        problems.push(`area "${area}" names commons "${c}", which is not declared`);
+    }
+  }
+  if (problems.length) throw new WorkkitError("MANIFEST_INVALID", problems.join("; "));
+  return { ...m, protectedBranches: m.protectedBranches ?? [m.baseBranch], env };
+}
+async function loadManifest(repoRoot) {
+  for (const name of MANIFEST_FILES) {
+    const file = join3(repoRoot, name);
+    if (!existsSync4(file)) continue;
+    if (name.endsWith(".json")) return validateManifest(JSON.parse(readFileSync2(file, "utf8")));
+    const mod = await import(`${pathToFileURL(file).href}?t=${Date.now()}`);
+    return validateManifest(mod.default);
+  }
+  throw new WorkkitError(
+    "MANIFEST_NOT_FOUND",
+    `no ${MANIFEST_FILES.join(" | ")} in ${repoRoot}; run \`work init\``
+  );
+}
+
+// src/core/hooks.ts
+var HOOKS_DIR = ".helmsmith/hooks";
+function preCommitScript(protectedBranches) {
+  return `#!/bin/sh
+# Installed by \`work init\` (@helmsmith/workbrokr). The protected-branch rule lives here; the rest in workbrokr.
+PROTECTED="${protectedBranches.join(" ")}"
+branch=$(git symbolic-ref --short -q HEAD)
+for p in $PROTECTED; do
+  if [ "$branch" = "$p" ]; then
+    echo "work: branch \\"$branch\\" is protected ($PROTECTED): work happens on <type>/<area> branches, never here" >&2
+    exit 2
+  fi
+done
+if command -v workbrokr >/dev/null 2>&1; then
+  workbrokr hook pre-commit "$@" || exit $?
+else
+  echo "work: workbrokr is not on PATH; commons and scope checks skipped (npm i -g @helmsmith/workbrokr)" >&2
+fi
+COMMON_DIR=$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)
+LEGACY="$COMMON_DIR/hooks/pre-commit"
+if [ -n "$COMMON_DIR" ] && [ -x "$LEGACY" ]; then
+  SELF_DIR=$(cd "$(dirname "$0")" && pwd)
+  LEGACY_DIR=$(cd "$(dirname "$LEGACY")" && pwd)
+  if [ "$SELF_DIR" != "$LEGACY_DIR" ]; then
+    exec "$LEGACY" "$@"
+  fi
+fi
+exit 0
+`;
+}
+function prePushScript(protectedBranches) {
+  return `#!/bin/sh
+# Installed by \`work init\` (@helmsmith/workbrokr). Refuses a push to, or a delete of, a protected branch here; the rest in workbrokr.
+PROTECTED="${protectedBranches.join(" ")}"
+input=$(cat)
+printf '%s\\n' "$input" | while read -r lref lsha rref rsha; do
+  [ -n "$rref" ] || continue
+  dest=\${rref#refs/heads/}
+  for p in $PROTECTED; do
+    if [ "$dest" = "$p" ]; then
+      echo "work: \\"$dest\\" is protected ($PROTECTED): nothing is pushed to it directly, open a PR from an area branch" >&2
+      exit 2
+    fi
+  done
+done || exit 2
+if command -v workbrokr >/dev/null 2>&1; then
+  printf '%s\\n' "$input" | workbrokr hook pre-push "$@" || exit $?
+else
+  echo "work: workbrokr is not on PATH; scope and commons warnings skipped" >&2
+fi
+COMMON_DIR=$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)
+LEGACY="$COMMON_DIR/hooks/pre-push"
+if [ -n "$COMMON_DIR" ] && [ -x "$LEGACY" ]; then
+  SELF_DIR=$(cd "$(dirname "$0")" && pwd)
+  LEGACY_DIR=$(cd "$(dirname "$LEGACY")" && pwd)
+  if [ "$SELF_DIR" != "$LEGACY_DIR" ]; then
+    printf '%s\\n' "$input" | exec "$LEGACY" "$@"
+  fi
+fi
+exit 0
+`;
+}
+function installHooks(repoRoot, opts) {
+  for (const b of opts.protectedBranches) {
+    if (!BRANCH_NAME.test(b))
+      throw new WorkkitError("MANIFEST_INVALID", `protected branch "${b}" is not a plain ref name`);
+  }
+  const hooksDir = join4(repoRoot, HOOKS_DIR);
+  mkdirSync3(hooksDir, { recursive: true });
+  const files = [];
+  const scripts = [
+    ["pre-commit", preCommitScript(opts.protectedBranches)],
+    ["pre-push", prePushScript(opts.protectedBranches)]
+  ];
+  for (const [name, body] of scripts) {
+    const file = join4(hooksDir, name);
+    let existing;
+    try {
+      existing = lstatSync(file);
+    } catch {
+      existing = void 0;
+    }
+    if (existing?.isSymbolicLink()) {
+      throw new WorkkitError("INTERNAL", `refusing to write hook ${file}: it is a symlink`, {
+        file
+      });
+    }
+    writeFileSync2(file, body);
+    chmodSync(file, 493);
+    files.push(file);
+  }
+  new Git(repoRoot).run(["config", "core.hooksPath", HOOKS_DIR]);
+  return { hooksDir, files };
+}
+
+// src/core/paths.ts
+import { homedir } from "os";
+import { join as join5 } from "path";
+function homeDir(env = process.env) {
+  return env.HELMSMITH_HOME && env.HELMSMITH_HOME.length > 0 ? env.HELMSMITH_HOME : join5(homedir(), ".cache", "helmsmith");
+}
+var registryFile = (home) => join5(home, "registry.json");
+var lockDir = (home) => join5(home, "registry.lock");
+
+// src/core/ports.ts
+function portsForSlot(m, slot) {
+  return Object.fromEntries(
+    Object.entries(m.ports.services).map(([service, { base }]) => [service, base + slot])
+  );
+}
+function rangesFor(m) {
+  return Object.fromEntries(
+    Object.entries(m.ports.services).map(([service, { base }]) => [
+      service,
+      { base, count: m.slots.count }
+    ])
+  );
+}
+function rangesOverlap(a, b) {
+  return a.base < b.base + b.count && b.base < a.base + a.count;
+}
+function ensureRanges(registry, m, repoRoot) {
+  const mine = rangesFor(m);
+  assertNoOverlap(registry, m, mine);
+  const current = registry.project(m.project);
+  if (current && JSON.stringify(current.ranges) === JSON.stringify(mine)) return;
+  registry.upsertProject(m.project, { root: repoRoot, ranges: mine });
+}
+function claimRanges(registry, m, repoRoot) {
+  const mine = rangesFor(m);
+  assertNoOverlap(registry, m, mine);
+  registry.upsertProject(m.project, { root: repoRoot, ranges: mine });
+}
+function assertNoOverlap(registry, m, mine) {
+  const others = Object.entries(registry.read().projects).filter(([name]) => name !== m.project);
+  for (const [service, range] of Object.entries(mine)) {
+    for (const [name, entry] of others) {
+      for (const [theirService, theirs] of Object.entries(entry.ranges)) {
+        if (rangesOverlap(range, theirs)) {
+          throw new WorkkitError(
+            "PORT_RANGE_TAKEN",
+            `ports ${range.base}-${range.base + range.count - 1} for "${service}" overlap project "${name}" (${theirService}: ${theirs.base}-${theirs.base + theirs.count - 1}); pick another base in ports.services.${service}`,
+            { project: name, service, theirs }
+          );
+        }
+      }
+    }
+  }
+}
+
+// src/core/refresh.ts
+import { spawnSync as spawnSync2 } from "child_process";
+import { createHash } from "crypto";
+import { existsSync as existsSync5, mkdirSync as mkdirSync4, readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "fs";
+import { dirname as dirname2, join as join6 } from "path";
+import picomatch2 from "picomatch";
+function matchesWhen(glob) {
+  const isMatch = picomatch2(glob, { dot: true });
+  return (p) => isMatch(p);
+}
+function readStamps(stampFile) {
+  if (!stampFile || !existsSync5(stampFile)) return {};
+  try {
+    return JSON.parse(readFileSync3(stampFile, "utf8"));
+  } catch {
+    return {};
+  }
+}
+function writeStamps(stampFile, stamps) {
+  mkdirSync4(dirname2(stampFile), { recursive: true });
+  writeFileSync3(stampFile, `${JSON.stringify(stamps, null, 2)}
+`);
+}
+function matchedFilesInWorktree(worktree, whenGlob) {
+  if (!/[*?[{]/.test(whenGlob)) {
+    return existsSync5(join6(worktree, whenGlob)) ? [whenGlob] : [];
+  }
+  const r = spawnSync2("git", ["ls-files"], { cwd: worktree, encoding: "utf8" });
+  if (r.status !== 0) return [];
+  const isMatch = matchesWhen(whenGlob);
+  return (r.stdout ?? "").split("\n").map((l) => l.trim()).filter((l) => l.length > 0 && isMatch(l) && existsSync5(join6(worktree, l)));
+}
+function hashFiles(worktree, relPaths) {
+  if (relPaths.length === 0) return null;
+  const h = createHash("sha256");
+  for (const rel of [...relPaths].sort()) {
+    const abs = join6(worktree, rel);
+    if (!existsSync5(abs)) continue;
+    h.update(`${rel}\0`);
+    h.update(readFileSync3(abs));
+    h.update("\0");
+  }
+  return h.digest("hex");
+}
+function isFileCleanInGit(worktree, relPath) {
+  const r = spawnSync2("git", ["status", "--porcelain", "--", relPath], {
+    cwd: worktree,
+    encoding: "utf8"
+  });
+  return r.status === 0 && (r.stdout ?? "").trim().length === 0;
+}
+function selectRefresh(entries, changedPaths, opts) {
+  const runs = [];
+  const marks = [];
+  const stored = readStamps(opts?.stampFile);
+  const pendingStamps = { ...stored };
+  const cleanWhenFiles = /* @__PURE__ */ new Set();
+  for (const e of entries) {
+    let hit = e.always === true;
+    let matchedFiles = [];
+    if (e.when !== void 0) {
+      const byChanged = changedPaths.some(matchesWhen(e.when));
+      if (opts?.worktree) {
+        matchedFiles = matchedFilesInWorktree(opts.worktree, e.when);
+        const digest = hashFiles(opts.worktree, matchedFiles);
+        if (digest !== null) {
+          if (stored[e.when] !== digest) hit = true;
+          pendingStamps[e.when] = digest;
+        }
+      }
+      if (byChanged) hit = true;
+    }
+    if (!hit) continue;
+    if (e.run) {
+      runs.push(e.run);
+      if (opts?.worktree && e.when && e.restoreWhenIfClean !== false) {
+        for (const f of matchedFiles) {
+          if (isFileCleanInGit(opts.worktree, f)) cleanWhenFiles.add(f);
+        }
+      }
+    }
+    if (e.mark) marks.push(e.mark);
+  }
+  if (!opts?.worktree) return { runs, marks };
+  return {
+    runs,
+    marks,
+    pendingStamps,
+    cleanWhenFiles: [...cleanWhenFiles]
+  };
+}
+function runRefresh(runs, cwd, log, env = process.env, opts) {
+  for (const cmd of runs) {
+    log(`$ ${cmd}`);
+    const r = spawnSync2("sh", ["-c", cmd], { cwd, env, encoding: "utf8" });
+    if (r.stdout) log(r.stdout.trimEnd());
+    if (r.stderr) log(r.stderr.trimEnd());
+    if (r.status !== 0) {
+      throw new WorkkitError("INTERNAL", `refresh command failed (${r.status}): ${cmd}`, {
+        cmd,
+        status: r.status
+      });
+    }
+  }
+  if (opts?.restoreFiles && opts.restoreFiles.length > 0) {
+    for (const rel of opts.restoreFiles) {
+      if (!isFileCleanInGit(cwd, rel)) {
+        spawnSync2("git", ["checkout", "--", rel], { cwd, encoding: "utf8" });
+      }
+    }
+  }
+  if (opts?.stampFile && opts.pendingStamps) {
+    writeStamps(opts.stampFile, opts.pendingStamps);
+  }
+}
+
+// src/core/registry.ts
+import { randomBytes } from "crypto";
+import {
+  existsSync as existsSync6,
+  mkdirSync as mkdirSync5,
+  readFileSync as readFileSync4,
+  renameSync,
+  rmSync as rmSync2,
+  statSync as statSync2,
+  writeFileSync as writeFileSync4
+} from "fs";
+var newId = (prefix) => `${prefix}_${randomBytes(4).toString("hex")}`;
+var EMPTY = { version: 1, projects: {}, leases: [], efforts: [] };
+var LOCK_STALE_MS = 1e4;
+var LOCK_WAIT_MS = 15e3;
+function sleep(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+var Registry = class _Registry {
+  constructor(home, now) {
+    this.home = home;
+    this.now = now;
+  }
+  home;
+  now;
+  static open(home, now = () => /* @__PURE__ */ new Date()) {
+    mkdirSync5(home, { recursive: true });
+    return new _Registry(home, now);
+  }
+  /** The registry as it is on disk. A file that does not parse is refused, never replaced. */
+  read() {
+    const file = registryFile(this.home);
+    if (!existsSync6(file)) return structuredClone(EMPTY);
+    let parsed;
+    try {
+      parsed = JSON.parse(readFileSync4(file, "utf8"));
+    } catch (err) {
+      throw new WorkkitError(
+        "INTERNAL",
+        `${file} is corrupt (${err instanceof Error ? err.message : String(err)}); nothing was changed. Move it aside (mv ${file} ${file}.corrupt-$(date +%s)) to start fresh, knowing its leases and running pids are lost`,
+        { file }
+      );
+    }
+    const r = parsed;
+    if (!r || typeof r !== "object" || r.version !== 1) {
+      throw new WorkkitError(
+        "INTERNAL",
+        `${file} has an unknown registry version (${String(r?.version)}); this build reads version 1`,
+        { file }
+      );
+    }
+    return {
+      version: 1,
+      projects: r.projects ?? {},
+      leases: r.leases ?? [],
+      efforts: r.efforts ?? [],
+      notices: r.notices ?? []
+    };
+  }
+  /** Lock, re-read, mutate, write atomically, unlock. The only way state changes. */
+  update(fn) {
+    const lock = lockDir(this.home);
+    const started = Date.now();
+    for (; ; ) {
+      try {
+        mkdirSync5(lock);
+        break;
+      } catch {
+        try {
+          if (Date.now() - statSync2(lock).mtimeMs > LOCK_STALE_MS) {
+            const claimed = `${lock}.stale.${process.pid}.${Date.now()}`;
+            renameSync(lock, claimed);
+            rmSync2(claimed, { recursive: true, force: true });
+            continue;
+          }
+        } catch {
+          continue;
+        }
+        if (Date.now() - started > LOCK_WAIT_MS) {
+          throw new WorkkitError(
+            "INTERNAL",
+            `registry lock ${lock} held for over ${LOCK_WAIT_MS} ms`
+          );
+        }
+        sleep(25);
+      }
+    }
+    try {
+      const r = this.read();
+      const out = fn(r);
+      const file = registryFile(this.home);
+      const tmp = `${file}.${process.pid}.tmp`;
+      writeFileSync4(tmp, `${JSON.stringify(r, null, 2)}
+`);
+      renameSync(tmp, file);
+      return out;
+    } finally {
+      rmSync2(lock, { recursive: true, force: true });
+    }
+  }
+  project(name) {
+    return this.read().projects[name];
+  }
+  upsertProject(name, entry) {
+    this.update((r) => {
+      r.projects[name] = entry;
+    });
+  }
+  leases(filter = {}) {
+    return this.read().leases.filter(
+      (l) => Object.entries(filter).every(([k, v]) => l[k] === v)
+    );
+  }
+  efforts(filter = {}) {
+    return this.read().efforts.filter(
+      (e) => Object.entries(filter).every(([k, v]) => e[k] === v)
+    );
+  }
+  activeEffortFor(project, area, task) {
+    return this.efforts({ project, area, state: "active" }).find(
+      (e) => (e.task ?? void 0) === (task ?? void 0)
+    );
+  }
+  /** An effort that is being started counts as open: nobody else may start on the same (area, task) meanwhile. */
+  openEffortFor(project, area, task) {
+    return this.efforts({ project, area }).find(
+      (e) => (e.state === "starting" || e.state === "active") && (e.task ?? void 0) === (task ?? void 0)
+    );
+  }
+  addNotice(project, area, notice) {
+    this.update((r) => {
+      const existing = r.notices ?? [];
+      const dup = existing.findIndex(
+        (n) => n.project === project && n.area === area && n.notice.from === notice.from && n.notice.text === notice.text
+      );
+      if (dup >= 0) {
+        existing[dup] = { project, area, notice };
+        r.notices = existing;
+      } else {
+        r.notices = [...existing, { project, area, notice }];
+      }
+    });
+  }
+  notices(project, area) {
+    return (this.read().notices ?? []).filter((n) => n.project === project && n.area === area).map((n) => n.notice);
+  }
+  clearNotices(project, area) {
+    this.update((r) => {
+      r.notices = (r.notices ?? []).filter((n) => !(n.project === project && n.area === area));
+    });
+  }
+  clearNoticesFrom(project, branches) {
+    const set = new Set(branches);
+    this.update((r) => {
+      r.notices = (r.notices ?? []).filter(
+        (n) => !(n.project === project && set.has(n.notice.from))
+      );
+    });
+  }
+  pruneNoticesWhere(project, area, remove) {
+    this.update((r) => {
+      r.notices = (r.notices ?? []).filter(
+        (n) => !(n.project === project && n.area === area && remove(n.notice))
+      );
+    });
+  }
+  allocateSlot(project, m, owner, effort, exclude = /* @__PURE__ */ new Set()) {
+    return this.update((r) => {
+      const taken = new Set(
+        r.leases.filter((l) => l.project === project && l.kind === "slot").map((l) => l.value)
+      );
+      const reserved = new Set(m.slots.reserved);
+      let slot = -1;
+      for (let n = 0; n < m.slots.count; n++) {
+        if (!taken.has(n) && !reserved.has(n) && !exclude.has(n)) {
+          slot = n;
+          break;
+        }
+      }
+      if (slot < 0) {
+        throw new WorkkitError(
+          "NO_FREE_SLOT",
+          `no free slot in ${project} (0..${m.slots.count - 1}, reserved ${[...reserved].join(",")}): \`work status\` lists the efforts holding them; \`work finish\` or \`work reap\` frees one`
+        );
+      }
+      const lease = this.lease(
+        project,
+        "slot",
+        slot,
+        owner,
+        effort,
+        m.expiry.slotHours,
+        portsForSlot(m, slot)
+      );
+      r.leases.push(lease);
+      return lease;
+    });
+  }
+  addLease(kind, project, value, owner, effort, hours, extra = {}) {
+    return this.update((r) => {
+      const l = { ...this.lease(project, kind, value, owner, effort, hours), ...extra };
+      r.leases.push(l);
+      return l;
+    });
+  }
+  lease(project, kind, value, owner, effort, hours, ports) {
+    const now = this.now();
+    return {
+      id: newId("lease"),
+      project,
+      kind,
+      value,
+      ...ports ? { ports } : {},
+      owner,
+      effort,
+      created: now.toISOString(),
+      touched: now.toISOString(),
+      expires: new Date(now.getTime() + hours * 36e5).toISOString()
+    };
+  }
+  touch(leaseId, hours) {
+    this.update((r) => {
+      const l = r.leases.find((x) => x.id === leaseId);
+      if (!l) throw new WorkkitError("LEASE_NOT_FOUND", leaseId);
+      const now = this.now();
+      l.touched = now.toISOString();
+      l.expires = new Date(now.getTime() + hours * 36e5).toISOString();
+    });
+  }
+  patchLease(leaseId, patch) {
+    this.update((r) => {
+      const i = r.leases.findIndex((x) => x.id === leaseId);
+      if (i < 0) throw new WorkkitError("LEASE_NOT_FOUND", leaseId);
+      r.leases[i] = { ...r.leases[i], ...patch };
+    });
+  }
+  release(leaseId) {
+    this.update((r) => {
+      r.leases = r.leases.filter((l) => l.id !== leaseId);
+    });
+  }
+  expired(now = this.now()) {
+    return this.read().leases.filter((l) => Date.parse(l.expires) < now.getTime());
+  }
+  addEffort(e) {
+    this.update((r) => {
+      r.efforts.push(e);
+    });
+  }
+  updateEffort(id, patch) {
+    return this.update((r) => {
+      const i = r.efforts.findIndex((e) => e.id === id);
+      if (i < 0) throw new WorkkitError("EFFORT_NOT_FOUND", `no effort ${id}`);
+      r.efforts[i] = { ...r.efforts[i], ...patch };
+      return r.efforts[i];
+    });
+  }
+  removeEfforts(predicate) {
+    return this.update((r) => {
+      const before = r.efforts.length;
+      r.efforts = r.efforts.filter((e) => !predicate(e));
+      return before - r.efforts.length;
+    });
+  }
+};
+
+// src/core/runner.ts
+import { spawn, spawnSync as spawnSync3 } from "child_process";
+import { closeSync, openSync } from "fs";
+import { join as join7 } from "path";
+var DEFAULT_HEALTH_TIMEOUT_MS = 18e4;
+var HEALTH_POLL_MS = 1e3;
+var PROBE_CAP_MS = 1e4;
+var STOP_COMMAND_TIMEOUT_MS = 15e3;
+var STOP_GRACE_MS = 5e3;
+var sleep2 = (ms) => new Promise((r) => setTimeout(r, ms));
+function isAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function pidSignature(pid) {
+  const r = spawnSync3("ps", ["-o", "lstart=", "-p", String(pid)], { encoding: "utf8" });
+  return r.status === 0 ? (r.stdout ?? "").trim() : "";
+}
+function serviceModes(name, spec) {
+  if (spec.modes && spec.modes.length > 0) return spec.modes;
+  return name === "frontend" ? ["fullstack"] : ["backend", "fullstack"];
+}
+function probe(spec, cwd, env, timeoutMs = PROBE_CAP_MS) {
+  const r = spawnSync3("sh", ["-c", spec.health], {
+    cwd,
+    env,
+    encoding: "utf8",
+    timeout: Math.max(100, timeoutMs)
+  });
+  const out = (r.stdout ?? "").trim();
+  const last = out.split(/\s+/).filter(Boolean).pop() ?? "";
+  if (r.error) return { healthy: false, last: `probe ${r.error.message}` };
+  if (r.status !== 0) return { healthy: false, last: (r.stderr ?? "").trim() || out };
+  if (spec.healthyCodes && spec.healthyCodes.length > 0)
+    return { healthy: spec.healthyCodes.includes(Number(last)), last };
+  return { healthy: true, last };
+}
+async function waitHealthy(o) {
+  const budget = o.timeoutMs ?? o.spec.healthTimeoutMs ?? DEFAULT_HEALTH_TIMEOUT_MS;
+  const deadline = Date.now() + budget;
+  let last = "";
+  while (Date.now() < deadline) {
+    const p = probe(o.spec, o.cwd, o.env, Math.min(PROBE_CAP_MS, deadline - Date.now()));
+    if (p.healthy) return;
+    last = p.last;
+    if (Date.now() >= deadline) break;
+    await sleep2(Math.min(HEALTH_POLL_MS, Math.max(0, deadline - Date.now())));
+  }
+  throw new WorkkitError(
+    "HEALTH_TIMEOUT",
+    `service "${o.name}" was not healthy within ${(budget / 1e3).toFixed(0)} s (last probe: ${last || "no output"})`,
+    { service: o.name, last }
+  );
+}
+function spawnService(name, spec, a) {
+  const fd = openSync(join7(a.logDir, `${name}.log`), "a");
+  try {
+    const child = spawn("sh", ["-c", spec.start], {
+      cwd: a.cwd,
+      env: a.env,
+      detached: true,
+      stdio: ["ignore", fd, fd]
+    });
+    child.unref();
+    if (child.pid === void 0) {
+      throw new WorkkitError("SERVICE_FAILED", `service "${name}" did not spawn: ${spec.start}`, {
+        service: name
+      });
+    }
+    return child.pid;
+  } finally {
+    closeSync(fd);
+  }
+}
+async function startServices(a) {
+  const pids = {};
+  const signatures = {};
+  const targetMode = a.mode ?? "fullstack";
+  const entries = Object.entries(a.m.services).filter(([name, spec]) => {
+    if (a.onlyServices) return a.onlyServices.includes(name);
+    return serviceModes(name, spec).includes(targetMode);
+  });
+  for (const [name, spec] of entries) {
+    a.onLog?.(`starting ${name}: ${spec.start}`);
+    pids[name] = spawnService(name, spec, a);
+    signatures[name] = pidSignature(pids[name]);
+    a.onSpawn?.(name, pids[name], signatures[name]);
+    try {
+      await waitHealthy({ name, spec, cwd: a.cwd, env: a.env });
+    } catch (err) {
+      await stopServices({ m: a.m, cwd: a.cwd, env: a.env, pids, signatures, onLog: a.onLog });
+      throw err;
+    }
+    a.onLog?.(`${name} healthy (pid ${pids[name]})`);
+  }
+  return { pids, signatures };
+}
+function killGroup(pid, signal) {
+  try {
+    process.kill(-pid, signal);
+  } catch {
+    try {
+      process.kill(pid, signal);
+    } catch {
+    }
+  }
+}
+async function stopServices(o) {
+  const names = Object.keys(o.m.services).filter((n) => o.pids[n] !== void 0).reverse();
+  if (!o.skipStopCommands) {
+    for (const name of names) {
+      const spec = o.m.services[name];
+      o.onLog?.(`stopping ${name}: ${spec.stop}`);
+      const r = spawnSync3("sh", ["-c", spec.stop], {
+        cwd: o.cwd,
+        env: o.env,
+        encoding: "utf8",
+        timeout: STOP_COMMAND_TIMEOUT_MS
+      });
+      if (r.error) o.onLog?.(`stop command for ${name} ${r.error.message}`);
+    }
+  }
+  const ours = names.filter((n) => {
+    const pid = o.pids[n];
+    if (!isAlive(pid)) return false;
+    const expected = o.signatures?.[n];
+    if (expected === void 0) return true;
+    const actual = pidSignature(pid);
+    if (actual !== expected) {
+      o.onLog?.(
+        `not signalling pid ${pid} (${n}): it is no longer the process started for this lease`
+      );
+      return false;
+    }
+    return true;
+  });
+  const alive = () => ours.filter((n) => isAlive(o.pids[n]));
+  if (alive().length === 0) return;
+  for (const n of alive()) killGroup(o.pids[n], "SIGTERM");
+  const deadline = Date.now() + STOP_GRACE_MS;
+  while (alive().length > 0 && Date.now() < deadline) await sleep2(200);
+  for (const n of alive()) killGroup(o.pids[n], "SIGKILL");
+  const hardDeadline = Date.now() + STOP_GRACE_MS;
+  while (alive().length > 0 && Date.now() < hardDeadline) await sleep2(100);
+}
+
+// src/core/session.ts
+import { hostname, userInfo } from "os";
+function currentOwner(env = process.env) {
+  const named = [env.WORK_SESSION, env.CLAUDE_SESSION_NAME, env.CLAUDE_CODE_SESSION_ID].find(
+    (v) => v !== void 0 && v.length > 0
+  );
+  return { session: named ?? `${userInfo().username}@${hostname()}`, pid: process.pid };
+}
+export {
+  BRANCH_NAME,
+  Git,
+  HOOKS_DIR,
+  MANIFEST_FILES,
+  Registry,
+  TASK_SLUG,
+  WorkkitError,
+  allowedScopesForEffort,
+  areaVars,
+  assertNotMainCheckout,
+  assertNotProtected,
+  checkCommit,
+  checkPush,
+  claimRanges,
+  commonsTouched,
+  currentOwner,
+  emitWorktreeConfig,
+  ensureExcluded,
+  ensureRanges,
+  exitCodeFor,
+  expandScopes,
+  globsOverlap,
+  homeDir,
+  installHooks,
+  isAlive,
+  isSubGlob,
+  literalPrefix,
+  loadManifest,
+  lockDir,
+  newId,
+  pathsMatching,
+  pidSignature,
+  portsForSlot,
+  probe,
+  rangesFor,
+  rangesOverlap,
+  registryFile,
+  renderTemplate,
+  runRefresh,
+  selectRefresh,
+  serviceModes,
+  slotVars,
+  startServices,
+  stopServices,
+  storybookHostFor,
+  templateVariables,
+  toErrorBody,
+  validateManifest,
+  waitHealthy
+};
+//# sourceMappingURL=index.js.map