@brainervirus/workit-core 8.9.1 → 8.11.0

package/src/hooks/raw-git.ts

@@ -24,7 +24,7 @@ import { createHash } from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { resolveBranchPolicyFor } from "../core/branch";
+import { releaseBranch, resolveBranchPolicyFor, validateBranchNameFor } from "../core/branch";
 import { resolveRuntimeWorkspaceVcs } from "../core/workspaces";
 import { pushRemoteName } from "../git/rev";
 import { appendHookObserved, readLedger } from "../ledger";
@@ -230,6 +230,18 @@ export type RawAction =
       blindForce: boolean;
       /** The remote named on the command line; null pushes to the default one. */
       remote: string | null;
+      /** Tags named as `refs/tags/<t>` destinations (bare names are told apart later). */
+      tags?: string[];
+      /** `--tags`: every tag goes along. */
+      allTags?: true;
+      /** `--delete`/`-d`: the refspecs are deleted, not pushed. */
+      deletes?: true;
+      /** Names deleted by a colon refspec (`:chore/old`). */
+      deleted?: string[];
+      /** `--all`/`--branches`: every local branch. */
+      allBranches?: true;
+      /** `--mirror`: every ref, deletions included. */
+      mirror?: true;
     }
   | { kind: "merge"; forge: "gh" | "glab" }
   | { kind: "pr-create"; forge: "gh" | "glab" }
@@ -242,6 +254,10 @@ const pushAction = (args: string[]): RawAction | null => {
   let force = false;
   let lease = false;
   let wholesale = false;
+  let allTags = false;
+  let deletes = false;
+  let allBranches = false;
+  let mirror = false;
   let remote: string | null = null;
   const positionals: string[] = [];
   for (let index = 1; index < args.length; index++) {
@@ -256,26 +272,51 @@ const pushAction = (args: string[]): RawAction | null => {
     else if (PUSH_VALUE_OPTIONS.has(arg)) index++;
     else if (arg === "--force" || /^-[a-zA-Z]*f[a-zA-Z]*$/.test(arg)) force = true;
     else if (arg.startsWith("--force-with-lease") || arg === "--force-if-includes") lease = true;
-    else if (["--all", "--mirror", "--branches", "--tags"].includes(arg)) wholesale = true;
+    else if (arg === "--delete" || arg === "-d") deletes = true;
+    else if (arg === "--tags") allTags = wholesale = true;
+    else if (arg === "--all" || arg === "--branches") allBranches = wholesale = true;
+    else if (arg === "--mirror") mirror = wholesale = true;
     else if (!arg.startsWith("-")) positionals.push(arg);
   }
   // `--repo` names the remote; positionals are then all refspecs.
   const specs = remote === null ? positionals.slice(1) : positionals;
   remote ??= positionals[0] ?? null;
   const targets: Array<string | null> = [];
+  const tags: string[] = [];
+  const deleted: string[] = [];
   for (const raw of specs) {
     if (raw.startsWith("+")) force = true;
     const spec = raw.replace(/^\+/, "");
     const colon = spec.indexOf(":");
     const destination = colon >= 0 ? spec.slice(colon + 1) : spec;
     if (!destination) continue;
-    if (destination === "HEAD") targets.push(null);
-    else if (destination.startsWith("refs/heads/")) targets.push(destination.slice(11));
-    else if (!destination.startsWith("refs/")) targets.push(destination);
+    const name =
+      destination === "HEAD"
+        ? null
+        : destination.startsWith("refs/heads/")
+          ? destination.slice(11)
+          : destination.startsWith("refs/")
+            ? undefined
+            : destination;
+    if (destination.startsWith("refs/tags/")) tags.push(destination.slice(10));
+    if (name === undefined) continue;
+    targets.push(name);
+    if (colon === 0 && name !== null) deleted.push(name);
   }
   // No refspec pushes the current branch (push.default simple/current).
   if (specs.length === 0 && !wholesale) targets.push(null);
-  return { kind: "push", targets, blindForce: force && !lease, remote };
+  return {
+    kind: "push",
+    targets,
+    blindForce: force && !lease,
+    remote,
+    ...(tags.length ? { tags } : {}),
+    ...(allTags ? { allTags: true as const } : {}),
+    ...(deletes ? { deletes: true as const } : {}),
+    ...(deleted.length ? { deleted } : {}),
+    ...(allBranches ? { allBranches: true as const } : {}),
+    ...(mirror ? { mirror: true as const } : {}),
+  };
 };
 
 /** Options whose next word is their value (never an option or subcommand). */
@@ -432,12 +473,88 @@ const headSha = (repo: Repo): string | null => {
 
 const quote = (text: string) => `\`${text}\``;
 
-const refusal = (action: RawAction, branch: string | null): string => {
+const refusal = (action: RawAction, branch: string | null, dir?: string): string => {
   if (action.kind === "merge")
     return `workit: raw ${quote(action.forge === "gh" ? "gh pr merge" : "glab mr merge")} bypasses the merge grant and the verdict gate. Run ${quote("workit pr merge")} instead (it checks both; ${quote("workit help pr")}).`;
+  // Finishing a release (git-flow main/develop, the github-flow trunk, a
+  // custom protected branch): the push has its own granted verb.
+  const plainPush = action.kind === "push" && !action.blindForce && !action.deletes;
+  if (dir && branch && plainPush && releaseBranch(dir, branch))
+    return `workit: raw ${quote("git push")} onto ${branch}, a protected release branch, bypasses workit's protected-branch check. To finish a release or hotfix, push it with ${quote(`workit git push --release ${branch} [--release v<version>]`)}: it pushes ${branch} (fast-forward only) and the release tag, verifies the remote and records it, under the ${quote("release")} grant (if refused, ask the user to run ${quote("workit grant set <workspace> release=true")}). Feature work goes through ${quote("workit git push")} and ${quote("workit pr merge")}.`;
   return `workit: raw ${quote("git push")}${action.kind === "push" && action.blindForce ? " --force" : ""} onto ${branch}, a protected branch or the default target, bypasses workit's protected-branch check. Push your feature branch with ${quote("workit git push")} (${quote("workit git push --force-with-lease")} to rewrite it) and land it with ${quote("workit pr merge")}.`;
 };
 
+type PushAction = Extract<RawAction, { kind: "push" }>;
+
+/** The local branches and tags, and the remote's branches as last fetched: one git call. */
+type RefFacts = { heads: Set<string>; tags: Set<string>; remoteHeads: Set<string> };
+
+const refFacts = (repo: Repo, remote: string): RefFacts => {
+  const facts: RefFacts = { heads: new Set(), tags: new Set(), remoteHeads: new Set() };
+  const listed = spawnSync(
+    "git",
+    ["for-each-ref", "--format=%(refname)", "refs/heads", "refs/tags", `refs/remotes/${remote}`],
+    { cwd: repo.dir, encoding: "utf8", timeout: 5_000 },
+  );
+  const remotePrefix = `refs/remotes/${remote}/`;
+  for (const ref of (listed.stdout ?? "").split("\n")) {
+    if (ref.startsWith("refs/heads/")) facts.heads.add(ref.slice(11));
+    else if (ref.startsWith("refs/tags/")) facts.tags.add(ref.slice(10));
+    else if (ref.startsWith(remotePrefix)) facts.remoteHeads.add(ref.slice(remotePrefix.length));
+  }
+  return facts;
+};
+
+/** A bare refspec naming a local tag and no local branch pushes the tag. */
+const isTag = (facts: RefFacts, name: string): boolean =>
+  facts.tags.has(name) && !facts.heads.has(name);
+
+/**
+ * A raw tag push (`git push origin v1.0`, `refs/tags/v1.0`, `--tags`) skips
+ * the release grant: denied with the workit command. `--follow-tags` only
+ * nudges (it pushes annotated tags the pushed commits already reach).
+ */
+const tagRefusal = (action: PushAction, facts: RefFacts): string | null => {
+  const tags = [
+    ...(action.tags ?? []),
+    ...action.targets.filter((name): name is string => name !== null && isTag(facts, name)),
+  ];
+  if (!tags.length && !action.allTags) return null;
+  const named = tags.length ? tags.join(" --release ") : "v<version>";
+  return `workit: raw ${quote(`git push${action.allTags ? " --tags" : ""}`)} of ${tags.length ? `tag ${tags.join(", ")}` : "tags"} bypasses the release grant. Push a release tag with ${quote(`workit git push --release ${named}`)} (v<version> tags whose commit the production branch already has; a tag never moves), under the ${quote("release")} grant (if refused, ask the user to run ${quote("workit grant set <workspace> release=true")}).`;
+};
+
+/** The remote already has the branch (ls-remote, bounded; unreachable answers yes: fail open). */
+const remoteHas = (repo: Repo, remote: string, branch: string): boolean => {
+  const listed = spawnSync("git", ["ls-remote", "--heads", remote, `refs/heads/${branch}`], {
+    cwd: repo.dir,
+    encoding: "utf8",
+    timeout: 3_000,
+    env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+  });
+  return listed.status !== 0 || (listed.stdout ?? "").trim() !== "";
+};
+
+/**
+ * A branch name that would be new on the remote and that the workspace policy
+ * does not allow, with the closest allowed name. An existing remote branch
+ * (`dependabot/…`, a legacy name) is never judged: pushing it is not a new
+ * name. `--all`/`--branches` expand to every local branch.
+ */
+const offPolicyPush = (action: PushAction, repo: Repo, facts: RefFacts, remote: string) => {
+  const names = action.allBranches
+    ? [...facts.heads]
+    : action.targets.map((target) => target ?? repo.branch);
+  for (const branch of names) {
+    if (!branch || action.deleted?.includes(branch) || isTag(facts, branch)) continue;
+    if (facts.remoteHeads.has(branch)) continue;
+    const check = validateBranchNameFor(repo.dir, branch);
+    if (check.ok || check.rule !== "allowed_pattern" || remoteHas(repo, remote, branch)) continue;
+    return `workit: raw ${quote("git push")} onto ${branch}: ${check.error}`;
+  }
+  return null;
+};
+
 const nudgeFor = (action: RawAction, host: HookInput["host"], session: string): string | null => {
   switch (action.kind) {
     case "commit": {
@@ -550,12 +667,23 @@ export function rawGitPre(
     for (const { action, repo } of actionsIn(input.cwd, command, dialect)) {
       store ??= repo.location.dir;
       if (action.kind === "merge") return deny(refusal(action, null));
-      if (action.kind === "push")
+      if (action.kind === "push" && toPushRemote(repo, action.remote)) {
+        if (action.mirror)
+          return deny(
+            `workit: raw ${quote("git push --mirror")} rewrites and deletes every remote ref, protected branches and tags included. Push one branch with ${quote("workit git push")}.`,
+          );
         for (const target of action.targets) {
           const branch = target ?? repo.branch;
-          if (branch && guardedBranch(repo.dir, branch) && toPushRemote(repo, action.remote))
-            return deny(refusal(action, branch));
+          if (branch && guardedBranch(repo.dir, branch))
+            return deny(refusal(action, branch, repo.dir));
         }
+        const remote = action.remote ?? pushRemoteName(repo.dir, repo.branch) ?? "origin";
+        const facts = refFacts(repo, remote);
+        const tagDeny = tagRefusal(action, facts);
+        if (tagDeny) return deny(tagDeny);
+        const nameDeny = action.deletes ? null : offPolicyPush(action, repo, facts, remote);
+        if (nameDeny) return deny(nameDeny);
+      }
       const nudge = nudgeFor(action, input.host, input.session.id);
       if (nudge && !nudges.has(nudgeKind(action))) nudges.set(nudgeKind(action), nudge);
     }

package/src/host-session.ts

@@ -7,6 +7,10 @@
 //   - Pi: PI_SESSION_ID (the bash tool exposes the Pi session id);
 //   - Codex CLI and Desktop: CODEX_THREAD_ID (the thread id hooks get as session_id).
 // Cursor puts no conversation id in its shell; its hook names the id to use.
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { resolveStore } from "./store/paths";
 
 export type HostSession = { host: string | null; session: string | null };
 
@@ -51,3 +55,188 @@ export function hostSessionFromEnv(env: NodeJS.ProcessEnv): HostSession {
   }
   return inner ? { host: inner.host, session: inner.session } : { host: declared, session: null };
 }
+
+/**
+ * Where this shell's session comes from:
+ *   - `derived`: the host's own shell variable (OPENCODE_SESSION_ID,
+ *     PI_SESSION_ID, CODEX_THREAD_ID), which a caller cannot replace by
+ *     exporting WORKIT_SESSION_ID;
+ *   - `declared`: a host that puts no id in the shell but names itself
+ *     (WORKIT_HOST, e.g. Claude Code's SessionStart export) declares it in
+ *     WORKIT_SESSION_ID;
+ *   - `none`: no host at all (CI, a plain terminal, Cursor's prefixed
+ *     commands): whatever session the caller names is only declared.
+ */
+export type RealSession = HostSession & { kind: "derived" | "declared" | "none" };
+
+export function realHostSession(env: NodeJS.ProcessEnv): RealSession {
+  for (const [key, host] of HOST_SESSION_VARS) {
+    const session = env[key]?.trim();
+    if (session) return { host: host(env), session, kind: "derived" };
+  }
+  const declared = hostSessionFromEnv(env);
+  const hosted = declared.host !== null && declared.host !== "cli";
+  return { ...declared, kind: hosted ? "declared" : "none" };
+}
+
+// Ids a SubagentStart hook gave a lead's subagents (`<lead>:<agent id>`): one
+// empty file per id under `<store>/hooks/issued/<lead hash>/`, so concurrent
+// hooks never lose each other's write, bounded per lead.
+const ISSUED_PER_LEAD = 64;
+
+/**
+ * Written into each issued-id file. A hook bundle that contains this string
+ * records issued ids; `workit doctor` looks for it in the installed Claude
+ * Code and Codex hooks to catch a plugin older than the CLI.
+ */
+export const ISSUED_SESSIONS_MARKER = "workit-issued-sessions/1";
+
+const hash = (value: string): string =>
+  createHash("sha256").update(value).digest("hex").slice(0, 32);
+
+const issuedRoot = (cwd: string): string | null => {
+  const location = resolveStore(cwd);
+  return location instanceof Error ? null : path.join(location.dir, "hooks", "issued");
+};
+
+const issuedDir = (cwd: string, lead: string): string | null => {
+  const root = issuedRoot(cwd);
+  return root === null ? null : path.join(root, hash(lead));
+};
+
+/** No hook in this workspace has ever recorded an issued id (an older plugin hook, most likely). */
+const noIssuedRecord = (cwd: string | undefined): boolean => {
+  if (cwd === undefined) return false;
+  try {
+    const root = issuedRoot(cwd);
+    return root !== null && !fs.existsSync(root);
+  } catch {
+    return false;
+  }
+};
+
+/** Per host: how to update the plugin whose SubagentStart hook issues ids. */
+const PLUGIN_UPDATE: Readonly<Record<string, string>> = {
+  claude_code: "claude plugin marketplace update workit && claude plugin update workit@workit",
+  codex: "codex plugin remove workit@workit && codex plugin add workit@workit",
+};
+
+/** Remember that a SubagentStart hook issued `issued` to a subagent of `lead`. Fails open. */
+export function recordIssuedSession(cwd: string, lead: string, issued: string): void {
+  try {
+    const dir = issuedDir(cwd, lead);
+    if (!dir) return;
+    fs.mkdirSync(dir, { recursive: true });
+    const own = hash(issued);
+    fs.writeFileSync(path.join(dir, own), ISSUED_SESSIONS_MARKER);
+    const entries = fs.readdirSync(dir);
+    if (entries.length <= ISSUED_PER_LEAD) return;
+    // Oldest first; the id just issued is never the one pruned.
+    const byAge = entries
+      .filter((name) => name !== own)
+      .map((name) => ({ name, at: fs.statSync(path.join(dir, name)).mtimeMs }))
+      .toSorted((a, b) => a.at - b.at);
+    for (const { name } of byAge.slice(0, entries.length - ISSUED_PER_LEAD))
+      fs.rmSync(path.join(dir, name), { force: true });
+  } catch {
+    // Fail open: an unrecorded id is refused later, never a broken hook.
+  }
+}
+
+const wasIssued = (cwd: string | undefined, lead: string, claimed: string): boolean => {
+  if (cwd === undefined) return false;
+  try {
+    const dir = issuedDir(cwd, lead);
+    return dir !== null && fs.existsSync(path.join(dir, hash(claimed)));
+  } catch {
+    return false;
+  }
+};
+
+const leadOf = (session: string): string => session.slice(0, session.lastIndexOf(":"));
+
+/**
+ * Hosts whose child sessions run their own shell with their own host session
+ * id: a child proves itself from its own shell, so a lead never mints a child id.
+ */
+const OWN_CHILD_SHELL = new Set(["opencode", "pi"]);
+
+const SESSION_UNSAFE = /[^A-Za-z0-9_.:@/+-]/g;
+
+/**
+ * The host-derived identity of a child session: `<lead>:<child>`, the shape
+ * Claude Code's SubagentStart hook gives a subagent. The child's own id is
+ * kept whole (it is what the host vouches for); the lead part is trimmed to
+ * fit the ledger's 128-character session grammar.
+ */
+export function childSessionId(lead: string, child: string): string {
+  const leaf = child.replace(SESSION_UNSAFE, "-").slice(-120);
+  const prefix = lead.replace(SESSION_UNSAFE, "-").slice(0, 127 - leaf.length);
+  return prefix ? `${prefix}:${leaf}` : leaf;
+}
+
+export type SessionClaimRefusal = { error: string; unblock: string };
+
+/**
+ * Whether `claimed` may act as this shell's session (`cwd` locates the
+ * workspace's record of hook-issued ids):
+ *   - no host session (CI, a plain terminal): any id; `--session X` and
+ *     WORKIT_SESSION_ID=X are the same declaration;
+ *   - the shell's own session (a declared `<lead>:<x>` on Claude Code only
+ *     when its SubagentStart hook issued it);
+ *   - on a host that sets the id, `<lead>:<this session>`: a child naming its
+ *     own host session;
+ *   - `<this session>:<agent id>` only when this lead's SubagentStart hook
+ *     issued it (Claude Code, Codex).
+ * Anything else is a forged id: a verdict recorded under it would make author
+ * is not verifier a naming convention.
+ */
+export function sessionClaimRefusal(
+  env: NodeJS.ProcessEnv,
+  claimed: string,
+  cwd?: string,
+): SessionClaimRefusal | null {
+  const real = realHostSession(env);
+  const host = family(real.host);
+  // A host that always sets its own variable, named without it: the variable
+  // was removed (`env -u OPENCODE_SESSION_ID`), so nothing vouches for the id.
+  if (real.kind !== "derived" && host !== null && HOST_SET_VARIABLE[host])
+    return {
+      error: `forged_session: WORKIT_HOST names ${real.host}, but its own ${HOST_SET_VARIABLE[host]} is not in this shell, so ${claimed} cannot be checked`,
+      unblock: `record the verdict from the ${real.host} session's own shell, where ${HOST_SET_VARIABLE[host]} is set`,
+    };
+  if (real.kind === "none" || !real.session) return null;
+  let issuedClaim = false;
+  if (claimed === real.session) {
+    const declaredChild =
+      real.kind === "declared" && host === "claude_code" && claimed.includes(":");
+    if (!declaredChild || wasIssued(cwd, leadOf(claimed), claimed)) return null;
+    issuedClaim = true;
+  } else if (real.kind === "derived" && claimed.endsWith(`:${real.session}`)) return null;
+  else if (claimed.startsWith(`${real.session}:`)) {
+    if (wasIssued(cwd, real.session, claimed)) return null;
+    issuedClaim = true;
+  }
+  const error = `forged_session: ${claimed} is neither this shell's session (${real.session}) nor an id its host issued to a child of it`;
+  // A well-formed subagent id, but no hook here ever recorded one: the hook
+  // most likely predates this CLI (CLI and plugin update separately).
+  if (issuedClaim && noIssuedRecord(cwd) && host !== null && PLUGIN_UPDATE[host])
+    return {
+      error: `${error}; no SubagentStart hook in this workspace has recorded an issued id`,
+      unblock: `the workit plugin hook is probably older than this CLI and does not record the ids it issues: update the plugin (${PLUGIN_UPDATE[host]}), then relaunch the verifier so its SubagentStart runs the new hook (workit doctor checks this as hook_issued_sessions)`,
+    };
+  const ownChildShell = host !== null && OWN_CHILD_SHELL.has(host);
+  return {
+    error,
+    unblock: ownChildShell
+      ? `record the verdict from the verifier's own ${host === "pi" ? "Pi worker" : "OpenCode child session"} shell, where WORKIT_SESSION_ID is already set; never set WORKIT_SESSION_ID or --session by hand`
+      : "never name a session yourself: spawn a verifier or reviewer subagent and pass exactly the --session its SubagentStart context names, or pass --as verifier",
+  };
+}
+
+/** Hosts that always put their own session variable in the agent's shell. */
+const HOST_SET_VARIABLE: Readonly<Record<string, string>> = {
+  opencode: "OPENCODE_SESSION_ID",
+  pi: "PI_SESSION_ID",
+  codex: "CODEX_THREAD_ID",
+};

package/src/ledger.ts

@@ -1140,10 +1140,31 @@ export function authorSessions(
   return sessions;
 }
 
+/** Where each host's verifier session comes from, for refusal hints. */
+const HOST_DERIVED_SESSIONS =
+  "Claude Code, Codex and Cursor: `--session <lead>:<agent id>` from the SubagentStart hook; OpenCode child sessions and Pi workers: WORKIT_SESSION_ID=<lead>:<child> already set in their shell";
+
+/** Whether `derived` is a host-derived `<lead>:<bare>` id for the bare host session `bare`. */
+const derivesFrom = (derived: string, bare: string): boolean =>
+  !bare.includes(":") && derived.endsWith(`:${bare}`);
+
+/**
+ * Whether `session` is one of the authors: the same id, or one is a bare host
+ * session and the other its derived `<lead>:<session>` form (an OpenCode
+ * child that committed as `<lead>:<child>` and judges as `<child>` is still
+ * the author). Two derived ids never match on a shared last segment.
+ */
+const authoredBy = (authors: Set<string>, session: string): boolean => {
+  if (authors.has(session)) return true;
+  for (const author of authors)
+    if (derivesFrom(author, session) || derivesFrom(session, author)) return true;
+  return false;
+};
+
 const independenceReasons = (row: ReadRow, authors: Set<string>): RejectReason[] => {
   const reasons: RejectReason[] = [];
   if (!row.actor.session) reasons.push("no_session");
-  else if (authors.has(row.actor.session)) reasons.push("author_session");
+  else if (authoredBy(authors, row.actor.session)) reasons.push("author_session");
   if (row.self === true && !reasons.includes("no_session")) reasons.push("self");
   return reasons;
 };
@@ -1687,15 +1708,16 @@ export function recordVerdict(
     head: key.head,
   });
   const authoring = [session, input.derivedFrom].find(
-    (candidate): candidate is string => typeof candidate === "string" && authors.has(candidate),
+    (candidate): candidate is string =>
+      typeof candidate === "string" && authoredBy(authors, candidate),
   );
   if (!self && authoring)
     return err(
       "blocked",
       `author_verdict: session ${authoring} authored ${branch}; a verdict must come from a different session`,
       input.derivedFrom === undefined
-        ? "have a non-author session record the verdict: spawn a verifier with its own WORKIT_SESSION_ID=<lead>-v<n> (Claude Code: subagents get one from the SubagentStart hook); or, as the author, pass --self (self-reviewed, never accepted)"
-        : "run the verifier as a separate session: the lead spawns it with its own WORKIT_SESSION_ID (Claude Code: subagents get one from the SubagentStart hook)",
+        ? `have a non-author session record the verdict: spawn a verifier subagent, which gets its own host-derived session (${HOST_DERIVED_SESSIONS}); or, as the author, pass --self (self-reviewed, never accepted)`
+        : `run the verifier as a separate session: spawn a verifier subagent, which gets its own host-derived session (${HOST_DERIVED_SESSIONS})`,
     );
   const link = checkSupersede(context, "verdict", { self, kind, branch });
   if (!link.ok) return link;