@brainervirus/workit-core 8.10.0 → 8.12.0

package/src/git/ops.ts

@@ -12,7 +12,9 @@
 //   the named paths (`--only` semantics) or, with --all, everything is
 //   committed: unrelated dirt is never swept in implicitly. The acting session
 //   goes into a `Workit-Session:` trailer and a `commit.recorded` ledger row,
-//   so a verdict from the same session reads as the author's (D18).
+//   so a verdict from the same session reads as the author's (D18). A
+//   workspace with `trailers: false` gets the ledger row only. `--trailer`
+//   adds the caller's own trailers (Co-Authored-By) to the same commit.
 // - push: never to a protected branch, an exact SHA (a commit that lands while
 //   pushing is not pushed by accident), force only as --force-with-lease with
 //   the tip workit last recorded, and success only when the remote tip
@@ -21,16 +23,25 @@ import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 import {
+  branchKindOf,
   classifyBranchDirt,
+  flowMismatch,
+  flowRoute,
+  gitFlowOf,
   isProtectedTarget,
+  releaseBranch,
+  releaseBranchesOf,
   resolveCommitPolicyFor,
   validateBranchNameFor,
   validateCommitMessageFor,
+  type BranchKind,
+  type FlowRoute,
 } from "../core/branch";
 import { detectCommitFlavor, matchCommitFlavor } from "../core/commit-flavors";
 import { pushTargetIsStable } from "../core/pr-create";
 import { recordBranchBase, trackBranchName } from "../core/release-tracks";
 import { vcsConfig, type ResolvedReleaseTrack } from "../core/vcs-config";
+import { workspaceTrailers } from "../core/workspaces";
 import { redactText } from "../forge/redact";
 import { failure, success, type ForgeResult } from "../forge/types";
 import { appendObserved, readLedger, type LedgerActor } from "../ledger";
@@ -221,12 +232,14 @@ export type BranchOutcome = {
   notes: string[];
   /** The release track the base and name came from; null without tracks. */
   releaseTrack: ResolvedReleaseTrack | null;
+  /** The git-flow route the base came from; null outside git-flow or with a release track. */
+  flow: FlowRoute | null;
 };
 
 export type BranchInput = {
   /** An explicit branch name; else `kind` + `slug` through the track's naming. */
   name?: string;
-  kind?: "feature" | "bugfix" | "hotfix";
+  kind?: BranchKind;
   slug?: string;
   base?: string | null;
   carry?: boolean;
@@ -272,6 +285,21 @@ export function gitBranch(cwd: string, input: BranchInput): ForgeResult<BranchOu
   if (!policy.ok) return failure("blocked", policy.error, policy.correction);
   if (resolveRef(cwd, `refs/heads/${name}`))
     return failure("failed", `branch_exists: ${name} already exists`, `git switch ${name}`);
+  // git-flow (no release track): the kind decides the base, and an explicit
+  // base that is the other long-lived branch is refused.
+  const kind = input.kind ?? branchKindOf(name);
+  const flow =
+    resolved.ok !== false && !releaseTrack?.track
+      ? gitFlowOf(cwd, String(resolved.defaultTargetBranch ?? "") || null)
+      : null;
+  const route = flow && kind ? flowRoute(flow, kind) : null;
+  const mismatch = explicitBase ? flowMismatch(flow, kind, explicitBase, "base") : null;
+  if (mismatch && route)
+    return failure(
+      "blocked",
+      mismatch,
+      `workit git branch ${input.kind ? `--kind ${kind} --slug ${input.slug}` : name}  # without --base it starts from ${route.base}`,
+    );
 
   let base = explicitBase;
   let defaultTarget: string | null = null;
@@ -287,12 +315,16 @@ export function gitBranch(cwd: string, input: BranchInput): ForgeResult<BranchOu
     defaultTarget = String(resolved.defaultTargetBranch ?? "") || null;
     defaultBase = String(resolved.baseBranch ?? "") || defaultTarget;
   }
-  base ??= defaultBase;
+  base ??= route?.base ?? defaultBase;
   if (!base)
     return failure("invalid_input", "no default target branch is configured; pass --base <branch>");
   if (base.startsWith("-")) return failure("invalid_input", "--base must not start with -");
 
   const notes: string[] = [...(releaseTrack?.warnings ?? [])];
+  if (route?.mergeBack)
+    notes.push(
+      `git-flow: ${route.kind}/* lands on ${route.target} (workit pr create targets it), then ${route.target} merges back into ${route.mergeBack}`,
+    );
   const remotes = remoteNames(cwd);
   const remote = remotes.includes("origin") ? "origin" : pushRemoteName(cwd);
   const localTip = resolveRef(cwd, `refs/heads/${base}`);
@@ -351,6 +383,7 @@ export function gitBranch(cwd: string, input: BranchInput): ForgeResult<BranchOu
     carried: dirt !== "clean",
     notes,
     releaseTrack,
+    flow: route,
   });
 }
 
@@ -365,6 +398,8 @@ export type CommitOutcome = {
   /** Changes left uncommitted (not selected). */
   leftDirty: number;
   session: string | null;
+  /** Whether the commit carries the `Workit-Session:` trailer (workspace `trailers`). */
+  sessionTrailer: boolean;
   /** With --amend: the commit this one replaced. */
   amended: string | null;
   /** Follow-ups the agent should know (an amended commit that was already pushed). */
@@ -400,6 +435,51 @@ export function lintCommitMessage(
 }
 
 const SESSION_SAFE = /^[\w.:@/+-]{1,128}$/u;
+/** A `--trailer` the caller adds: one `Key: value` line. */
+const EXTRA_TRAILER = /^[A-Za-z0-9][A-Za-z0-9-]*: *\S[^\n\r]*$/u;
+
+const SESSION_KEY = /^workit-session\s*:/iu;
+/** A trailer line (`Key: value`, no leading space) as git reads one. */
+const TRAILER_LINE = /^[A-Za-z0-9][A-Za-z0-9-]*\s*:/u;
+
+/**
+ * `text` without the `Workit-Session:` lines of its trailer block: the last
+ * paragraph, when every line in it is a trailer or a folded continuation
+ * (leading whitespace) of one. Anything else, an indented line included, is
+ * prose and is left alone; the rest of the text is returned byte for byte.
+ * With `subject`, the first paragraph is a subject and never a trailer
+ * block (a commit message); without it (a PR body) it can be.
+ */
+export function stripSessionTrailers(text: string, options: { subject: boolean }): string {
+  const end = text.length - (/\s*$/u.exec(text)?.[0].length ?? 0);
+  const lines = text.slice(0, end).split("\n");
+  let start = lines.length;
+  while (start > 0 && lines[start - 1]?.trim() !== "") start -= 1;
+  if (start === 0 && options.subject) return text;
+  const block = lines.slice(start);
+  if (!block.length || !TRAILER_LINE.test(block[0] ?? "")) return text;
+  if (!block.every((line) => TRAILER_LINE.test(line) || /^\s+\S/u.test(line))) return text;
+  const kept: string[] = [];
+  let dropping = false;
+  for (const line of block) {
+    if (TRAILER_LINE.test(line)) dropping = SESSION_KEY.test(line);
+    if (!dropping) kept.push(line);
+  }
+  if (kept.length === block.length) return text;
+  let head = lines.slice(0, start);
+  if (!kept.length) {
+    let cut = head.length;
+    while (cut > 0 && head[cut - 1]?.trim() === "") cut -= 1;
+    head = head.slice(0, cut);
+  }
+  return [...head, ...kept].join("\n") + text.slice(end);
+}
+
+/** The values of the `Workit-Session:` trailers among `trailers`. */
+const sessionValues = (trailers: readonly string[]): string[] =>
+  trailers
+    .filter((trailer) => SESSION_KEY.test(trailer))
+    .map((trailer) => trailer.slice(trailer.indexOf(":") + 1).trim());
 
 // Fixed trailer syntax, whatever the user's trailer.* config says.
 const TRAILER_CONFIG = ["-c", "trailer.separators=:", "-c", "trailer.where=end"];
@@ -492,6 +572,8 @@ export function gitCommit(
     amend?: boolean;
     /** Record a commit even when it changes no file. */
     allowEmpty?: boolean;
+    /** Extra `Key: value` trailers for this commit (`--trailer`, e.g. Co-Authored-By). */
+    trailers?: readonly string[];
     actor: LedgerActor;
     env?: NodeJS.ProcessEnv;
   },
@@ -499,6 +581,19 @@ export function gitCommit(
   const given = input.message?.trim() ?? "";
   if (!given && !input.amend)
     return failure("invalid_input", "a commit message is required (-m <msg> or -F <file>)");
+  const extra = (input.trailers ?? []).map((trailer) => trailer.trim());
+  const malformed = extra.find((trailer) => !EXTRA_TRAILER.test(trailer));
+  if (malformed !== undefined)
+    return failure(
+      "invalid_input",
+      `--trailer ${JSON.stringify(malformed)} is not one "Key: value" line`,
+      `workit git commit -m '<msg>' --trailer "Co-Authored-By: Name <email>"`,
+    );
+  if (extra.some((trailer) => /^workit-session:/iu.test(trailer)))
+    return failure(
+      "invalid_input",
+      "--trailer cannot set Workit-Session: workit writes it from the acting session",
+    );
   const paths = input.paths ?? [];
   if (input.all && paths.length) return failure("invalid_input", "pass --all or paths, not both");
   const progress = operationInProgress(cwd);
@@ -529,6 +624,7 @@ export function gitCommit(
   }
   let message = given;
   let carried: string[] = [];
+  let previousTrailers: string[] = [];
   if (given) {
     const lint = lintCommitMessage(cwd, given);
     if (!lint.ok) return failure("blocked", lint.error, lint.correction);
@@ -538,7 +634,8 @@ export function gitCommit(
     if (!kept.ok)
       return failure("failed", `could not read the message of ${branch}: ${gitError(kept)}`);
     // --no-edit keeps the message whole; a new message carries the old trailers over.
-    if (given) carried = messageTrailers(cwd, kept.stdout.trim());
+    previousTrailers = messageTrailers(cwd, kept.stdout.trim());
+    if (given) carried = previousTrailers;
     else message = kept.stdout.trim();
   }
   const session = input.actor.session;
@@ -558,10 +655,36 @@ export function gitCommit(
   const args = ["commit", "--no-edit"];
   if (input.amend) args.push("--amend");
   if (input.allowEmpty || emptyAmend) args.push("--allow-empty");
-  args.push(
-    "-m",
-    withTrailers(cwd, message, [...carried, ...(session ? [`Workit-Session: ${session}`] : [])]),
+  // Off (`trailers: false`): authorship is the commit.recorded row alone,
+  // and an amend drops the Workit-Session trailers the old commit had.
+  const trailersOn = workspaceTrailers(cwd).enabled;
+  const sessionTrailer = Boolean(session) && trailersOn;
+  if (!trailersOn) {
+    carried = carried.filter((trailer) => !SESSION_KEY.test(trailer));
+    if (!given) message = stripSessionTrailers(message, { subject: true });
+  }
+  const finalMessage = withTrailers(cwd, message, [
+    ...carried,
+    ...extra,
+    ...(sessionTrailer ? [`Workit-Session: ${session}`] : []),
+  ]);
+  // Only workit writes Workit-Session: the acting session's, or (trailers
+  // on) the amended commit's own. A message line or a `trailer.<alias>.key`
+  // config that expands a --trailer into the key never forges one.
+  const allowed = new Set([
+    ...(trailersOn ? sessionValues(previousTrailers) : []),
+    ...(sessionTrailer && session ? [session] : []),
+  ]);
+  const forged = sessionValues(messageTrailers(cwd, finalMessage)).find(
+    (value) => !allowed.has(value),
   );
+  if (forged !== undefined)
+    return failure(
+      "invalid_input",
+      `forged_session_trailer: the message would carry "Workit-Session: ${forged}", which workit did not add; workit writes that trailer itself`,
+      "drop the Workit-Session line (or the trailer.<alias>.key config that expands into it)",
+    );
+  args.push("-m", finalMessage);
   if (paths.length) {
     if (paths.some((value) => value.startsWith("-") || !value.trim()))
       return failure("invalid_input", "paths must not be empty or start with -");
@@ -602,7 +725,8 @@ export function gitCommit(
   }
   const committed = git(cwd, args, {
     timeoutMs: COMMIT_TIMEOUT_MS,
-    env: input.env,
+    // Decided here: the session hook's helper skips its own `workit git trailers` call.
+    env: { ...(input.env ?? process.env), WORKIT_TRAILERS: trailersOn ? "on" : "off" },
   });
   if (!committed.ok)
     return failure(
@@ -658,6 +782,7 @@ export function gitCommit(
     files,
     leftDirty,
     session,
+    sessionTrailer,
     amended: previous,
     notes,
     recorded: row.ok ? { id: String(row.value.id) } : { error: row.error },
@@ -691,8 +816,10 @@ export function pushPreflight(
   if (isProtectedTarget(cwd, branch))
     return failure(
       "blocked",
-      `protected_branch: ${branch} is protected by the workspace branch policy; workit never pushes to it`,
-      "workit git branch <feature/name>  # push a feature branch and open a PR",
+      `protected_branch: ${branch} is protected by the workspace branch policy; workit git push never pushes to it`,
+      releaseBranch(cwd, branch)
+        ? `workit git push --release ${branch}  # finishing a release or hotfix; needs the release grant`
+        : "workit git branch <feature/name>  # push a feature branch and open a PR",
     );
   const sha = resolveRef(cwd, `refs/heads/${branch}`);
   if (!sha) return failure("not_found", `branch ${branch} has no commit to push`);
@@ -992,6 +1119,229 @@ export function executePush(
   });
 }
 
+// ---------------------------------------------------------------------------
+// release push: finishing a git-flow release or hotfix
+
+export type ReleaseRef = {
+  kind: "branch" | "tag";
+  /** The short name (`main`, `v4.1.0`). */
+  name: string;
+  /** The full ref (`refs/heads/main`, `refs/tags/v4.1.0`). */
+  ref: string;
+  /** The commit it points at (a tag peeled). */
+  sha: string;
+};
+
+export type ReleasePushPlan = Omit<PushPlan, "branch" | "sha"> & {
+  refs: ReleaseRef[];
+  /** The branch a pushed tag's commit must already be on (or a branch in this push). */
+  production: string | null;
+};
+
+/** A release tag: `v` and a digit (`v4.1.0`, `v2`). */
+const RELEASE_TAG = /^v\d/u;
+
+/**
+ * What `workit git push --release` may push: the git-flow production and
+ * develop branches and `v*` tags, nothing else, each by its local ref. Everything else stays on the feature-branch
+ * path (`workit git push`, `workit pr create`).
+ */
+export function releasePushPreflight(
+  cwd: string,
+  names: readonly string[],
+): ForgeResult<ReleasePushPlan> {
+  const progress = operationInProgress(cwd);
+  if (progress) return inProgressFailure(progress.operation, "push");
+  const wanted = [...new Set(names)];
+  if (!wanted.length) return failure("invalid_input", "name the release refs to push");
+  const { preset, branches, production } = releaseBranchesOf(cwd);
+  const refs: ReleaseRef[] = [];
+  for (const raw of wanted) {
+    if (raw.startsWith("-") || raw.includes(":"))
+      return failure("invalid_input", `${raw} is not a ref name (refspecs are not accepted)`);
+    const tagName = raw.replace(/^refs\/tags\//u, "");
+    const branchName = raw.replace(/^refs\/heads\//u, "");
+    const tag = raw.startsWith("refs/heads/") ? null : resolveRef(cwd, `refs/tags/${tagName}`);
+    const branch = raw.startsWith("refs/tags/")
+      ? null
+      : resolveRef(cwd, `refs/heads/${branchName}`);
+    if (tag && branch)
+      return failure(
+        "invalid_input",
+        `${raw} names both a branch and a tag`,
+        `workit git push --release refs/heads/${raw}  # or refs/tags/${raw}`,
+      );
+    if (tag) {
+      if (!RELEASE_TAG.test(tagName))
+        return failure(
+          "blocked",
+          `release_push_refused: tag ${tagName} is not a release tag (v<version>)`,
+          "git tag -a v<version> -m <message>  # then: workit git push --release v<version>",
+        );
+      refs.push({ kind: "tag", name: tagName, ref: `refs/tags/${tagName}`, sha: tag });
+      continue;
+    }
+    if (!branch) return failure("not_found", `${raw} is not a local branch or tag`);
+    if (!branches.some((name) => name.toLowerCase() === branchName.toLowerCase()))
+      return failure(
+        "blocked",
+        branches.length
+          ? `release_push_refused: ${branchName} is not a git-flow release branch (${branches.join(", ")})`
+          : `release_push_refused: the ${preset} policy lands ${branchName} only through a reviewed PR; workit git push --release pushes v<version> tags there, not branches`,
+        branches.length
+          ? "workit git push  # a feature, bugfix, release or hotfix branch, then: workit pr create"
+          : `workit pr create --base ${branchName}  # then tag the merged commit and: workit git push --release v<version>`,
+      );
+    refs.push({ kind: "branch", name: branchName, ref: `refs/heads/${branchName}`, sha: branch });
+  }
+  const remote = pushRemoteName(cwd, refs.find((ref) => ref.kind === "branch")?.name ?? null);
+  if (!remote)
+    return failure(
+      "not_found",
+      "no push remote is configured for this repository",
+      "git remote add origin <url>",
+    );
+  const raw = pushUrl(cwd, remote);
+  if (!raw)
+    return failure(
+      "blocked",
+      `remote "${remote}" has no single push URL`,
+      `git remote get-url --push --all ${remote}  # keep exactly one push URL`,
+    );
+  const local = parseRemoteUrl(raw)?.protocol === "file";
+  if (!local && !pushTargetIsStable(cwd, raw))
+    return failure(
+      "blocked",
+      `push_target_rewritten: the push URL of "${remote}" is rewritten by a url.*.insteadOf rule, so the destination is not the one checked`,
+      "git config --get-regexp '^url\\.'  # remove the rewrite for this remote",
+    );
+  return success({ refs, remote, url: redactRemote(raw), rawUrl: raw, local, production });
+}
+
+export type ReleasePushOutcome = {
+  remote: string;
+  url: string;
+  refs: Array<ReleaseRef & { previous: string | null; pushed: boolean }>;
+  recorded: { id: string } | { error: string };
+};
+
+/**
+ * Push the planned release refs in one atomic push: a branch only fast
+ * forward, a tag only when the remote lacks it (a release tag never moves),
+ * never forced. Success only when every remote tip observed afterwards is the
+ * local one; recorded as one `release.pushed` row.
+ */
+export function executeReleasePush(
+  cwd: string,
+  plan: ReleasePushPlan,
+  input: {
+    actor: LedgerActor;
+    grant: string;
+    timeoutMs?: number;
+    identity?: Record<string, unknown>;
+  },
+): ForgeResult<ReleasePushOutcome> {
+  const previous = new Map<string, string | null>();
+  for (const ref of plan.refs) {
+    const before = remoteRefTip(cwd, plan.rawUrl, ref.ref);
+    if (!before.ok) return failure(before.code, before.error);
+    previous.set(ref.ref, before.sha);
+    if (before.sha === null || before.sha === ref.sha) continue;
+    if (ref.kind === "tag")
+      return failure(
+        "blocked",
+        `tag_exists: ${plan.remote} already has ${ref.name} at ${before.sha.slice(0, 12)}, not ${ref.sha.slice(0, 12)}; a release tag never moves`,
+        `git tag -d ${ref.name}  # tag the next version instead`,
+      );
+    if (!git(cwd, ["merge-base", "--is-ancestor", before.sha, ref.sha]).ok)
+      return failure(
+        "failed",
+        `non_fast_forward: ${plan.remote}/${ref.name} (${before.sha.slice(0, 12)}) is not part of local ${ref.name}; a release push never rewrites it`,
+        `git fetch ${plan.remote} ${ref.name} && git switch ${ref.name} && git merge --ff-only ${plan.remote}/${ref.name}  # then: workit git push --release ${ref.name}`,
+      );
+  }
+  // A release tag marks a commit the production branch already has (or a
+  // branch this push moves): never an unmerged feature commit.
+  const tags = plan.refs.filter((ref) => ref.kind === "tag");
+  if (tags.length) {
+    let productionTip: string | null = null;
+    if (plan.production) {
+      const tip = remoteRefTip(cwd, plan.rawUrl, `refs/heads/${plan.production}`);
+      if (!tip.ok) return failure(tip.code, tip.error);
+      productionTip = tip.sha;
+    }
+    const contains = (tip: string, sha: string) =>
+      git(cwd, ["merge-base", "--is-ancestor", sha, tip]).ok;
+    for (const tag of tags) {
+      const released =
+        (productionTip !== null && contains(productionTip, tag.sha)) ||
+        plan.refs.some((ref) => ref.kind === "branch" && contains(ref.sha, tag.sha));
+      if (!released)
+        return failure(
+          "blocked",
+          `tag_unreleased: ${tag.name} (${tag.sha.slice(0, 12)}) is not on ${plan.remote}/${plan.production ?? "the production branch"}${plan.refs.some((ref) => ref.kind === "branch") ? " or a branch in this push" : ""}; a release tag marks a commit that already landed`,
+          `land it through a PR first (workit pr create), git fetch ${plan.remote}, then tag the merged commit`,
+        );
+    }
+  }
+  const pending = plan.refs.filter((ref) => previous.get(ref.ref) !== ref.sha);
+  if (pending.length) {
+    const run = gitNetwork(
+      cwd,
+      [
+        "push",
+        "--porcelain",
+        "--atomic",
+        "--no-follow-tags",
+        "--recurse-submodules=no",
+        plan.remote,
+        ...pending.map((ref) =>
+          ref.kind === "tag" ? `${ref.ref}:${ref.ref}` : `${ref.sha}:${ref.ref}`,
+        ),
+      ],
+      input.timeoutMs ?? PUSH_TIMEOUT_MS,
+    );
+    if (!run.ok)
+      return run.timedOut
+        ? failure("unavailable", `git push to ${plan.url} timed out`)
+        : failure("failed", `git push to ${plan.url} failed:\n${gitOutput(run)}`);
+  }
+  for (const ref of plan.refs) {
+    const after = remoteRefTip(cwd, plan.rawUrl, ref.ref);
+    if (!after.ok) return failure(after.code, `push sent but not verified: ${after.error}`);
+    if (after.sha !== ref.sha)
+      return failure(
+        "failed",
+        `push_unverified: ${plan.remote} ${ref.ref} is at ${after.sha?.slice(0, 12) ?? "(absent)"}, not ${ref.sha.slice(0, 12)}`,
+      );
+  }
+  const refs = plan.refs.map((ref) => ({
+    ...ref,
+    previous: previous.get(ref.ref) ?? null,
+    pushed: pending.includes(ref),
+  }));
+  const row = appendObserved(cwd, {
+    type: "release.pushed",
+    actor: input.actor,
+    remote: plan.remote,
+    url: plan.url,
+    refs: refs.map(({ ref, sha, previous: before, pushed }) => ({
+      ref,
+      sha,
+      previous: before,
+      pushed,
+    })),
+    grant: input.grant,
+    ...(input.identity ? { identity: input.identity } : {}),
+  });
+  return success({
+    remote: plan.remote,
+    url: plan.url,
+    refs,
+    recorded: row.ok ? { id: String(row.value.id) } : { error: row.error },
+  });
+}
+
 /**
  * Delete a remote branch only while it still points at `expectedTip`
  * (`--force-with-lease=refs/heads/<b>:<tip> --delete`). `lease` is false when

package/src/git/session-hook.ts

@@ -28,6 +28,12 @@
 //   it would commit a trailer-only message instead of aborting); for a
 //   template (git aborts an unedited one); for a comment-only message; and in a
 //   rebase or cherry-pick replaying commits that keep their own trailers.
+// - A workspace with `trailers: false`: the helper adds nothing when
+//   WORKIT_TRAILERS=off (set by `workit git commit`) or `workit git trailers`
+//   prints `off` (asked with a timeout when workit is on PATH). Without
+//   workit it fails open and adds the trailer, so doctor warns about any
+//   Workit hook or helper left there and `--fix` removes them
+//   (removeSessionHook); another tool's hook and its manual line stay.
 // - `--if-exists addIfDifferent`: the same session's trailer is never repeated;
 //   another session that amends adds its own, as `workit git commit --amend` does.
 import { spawnSync } from "node:child_process";
@@ -80,6 +86,19 @@ fi
 [ -n "$session" ] || exit 0
 [ \${#session} -le 128 ] || exit 0
 case "$session" in *[!A-Za-z0-9_.:@/+-]*) exit 0 ;; esac
+# A workspace with \`trailers: false\` keeps authorship in the ledger only.
+# \`workit git commit\` decides it already (WORKIT_TRAILERS); otherwise ask
+# workit, bounded, and add the trailer when it cannot answer.
+case "\${WORKIT_TRAILERS-}" in
+  off) exit 0 ;;
+  on) ;;
+  *)
+    if command -v workit >/dev/null 2>&1; then
+      t=; ! command -v timeout >/dev/null 2>&1 || t="timeout 5"
+      [ "$($t workit git trailers 2>/dev/null)" != off ] || exit 0
+    fi
+    ;;
+esac
 add_trailer() {
   [ -f "$1" ] && [ -r "$1" ] || return 0
   body=$(sed '/^# -\\{24\\} >8 -\\{24\\}$/,$d' "$1" | git stripspace --strip-comments)
@@ -519,3 +538,52 @@ export function installSessionHook(
     detail: `${verb} the Workit ${SESSION_HOOK_NAME} hook at ${status.hookPath}${helper}`,
   };
 }
+
+export type SessionHookRemoval = {
+  /** Whether Workit's own hook or helper was deleted. */
+  action: "removed" | "unchanged" | "skipped";
+  /** The files deleted: Workit's hook (only one carrying its marker) and the helper. */
+  removed: string[];
+  status: SessionHookStatus;
+  detail: string;
+};
+
+/** Whether `status` finds Workit's own hook (any version) in the slot. */
+export const workitHookIn = (status: SessionHookStatus): boolean =>
+  status.hookPath !== null && (readText(status.hookPath)?.includes(SESSION_HOOK_MARKER) ?? false);
+
+/** Whether the helper exists for `status`, current or not. */
+export const helperIn = (status: SessionHookStatus): boolean =>
+  status.helperPath !== null && exists(status.helperPath);
+
+/**
+ * For a workspace with `trailers: false`: delete Workit's own hook (only a
+ * slot holding its marker) and the helper. Another tool's hook, a husky
+ * script or a lefthook job that runs the helper is never edited; without the
+ * helper its manual line runs nothing.
+ */
+export function removeSessionHook(
+  cwd: string,
+  env: NodeJS.ProcessEnv = process.env,
+): SessionHookRemoval {
+  const status = inspectSessionHook(cwd, env);
+  if (status.state === "not_git")
+    return { action: "skipped", removed: [], status, detail: "not inside a git work tree" };
+  const removed: string[] = [];
+  if (workitHookIn(status)) {
+    rmSync(status.hookPath!, { force: true });
+    removed.push(status.hookPath!);
+  }
+  if (helperIn(status)) {
+    rmSync(status.helperPath!, { force: true });
+    removed.push(status.helperPath!);
+  }
+  return {
+    action: removed.length ? "removed" : "unchanged",
+    removed,
+    status: inspectSessionHook(cwd, env),
+    detail: removed.length
+      ? `removed ${removed.join(" and ")}`
+      : "no Workit session hook or helper to remove",
+  };
+}

package/src/hooks/handle.ts

@@ -6,6 +6,8 @@ import {
   turnContextText,
 } from "./context";
 import type { HostDescriptor, Support } from "./descriptor";
+import { branchGuidance } from "../core/branch";
+import { workspaceTrailers } from "../core/workspaces";
 import { recordIssuedSession } from "../host-session";
 import { shellPolicy } from "./policy";
 import {
@@ -77,8 +79,12 @@ const CLAUDE_WORKTREE = /[\\/]\.claude[\\/]worktrees[\\/]/;
  * (`workit git …` included) and cannot be turned off, so an isolated agent
  * runs git itself and workit for everything else.
  */
-const ISOLATED_GIT =
-  'Run git as plain, separate commands inside your worktree (`git switch -c <branch> <base>`, `git commit --trailer "Workit-Session=<your session>"`, `git push`; `workit doctor --fix` can install a commit-msg hook that adds the trailer), never `workit git …`: Claude Code\'s worktree isolation refuses a command that wraps git and cannot be turned off (https://code.claude.com/docs/en/worktrees#how-claude-code-enforces-isolation). Never dodge that check by renaming or re-wrapping git. Use workit for the non-git verbs (`workit check`, `workit ledger`, `workit pr`).';
+const isolatedGit = (cwd: string): string =>
+  `Run git as plain, separate commands inside your worktree (\`git switch -c <branch> <base>\`, ${
+    workspaceTrailers(cwd).enabled
+      ? '`git commit --trailer "Workit-Session=<your session>"`, `git push`; `workit doctor --fix` can install a prepare-commit-msg hook that adds the trailer'
+      : "`git commit` (this workspace sets trailers: false: add no Workit-Session trailer), `git push`"
+  }; add Co-Authored-By with \`git commit --trailer\` in the same commit, never by amending), never \`workit git …\`: Claude Code's worktree isolation refuses a command that wraps git and cannot be turned off (https://code.claude.com/docs/en/worktrees#how-claude-code-enforces-isolation). Never dodge that check by renaming or re-wrapping git. Use workit for the non-git verbs (\`workit check\`, \`workit ledger\`, \`workit pr\`).`;
 
 const subagentStartText = (
   input: HookInput,
@@ -91,13 +97,14 @@ const subagentStartText = (
   const isolated =
     descriptor.subagents.worktreeIsolation === "native" &&
     (role === "implementer" || CLAUDE_WORKTREE.test(input.cwd));
+  const guide = role === "implementer" ? branchGuidance(input.cwd) : null;
   if (role === "implementer" && isolated)
-    return `Workit observed ${who} working in its own git worktree: it may edit and commit there, within its brief's scope. ${ISOLATED_GIT} Use a policy-compliant branch (e.g. feature/<slug>); branch policy hooks still deny protected or non-compliant branches. Never record a verdict on your own work. Never push, open a PR, or merge unless the brief asks for it.`;
+    return `Workit observed ${who} working in its own git worktree: it may edit and commit there, within its brief's scope. ${isolatedGit(input.cwd)} Plain git is expected here, and the branch name is still policy-checked: a raw \`git switch -c\`, \`git checkout -b\`, \`git branch\` or \`git worktree add -b\` onto a protected or non-compliant name is denied, so use a policy-compliant branch.${guide ? ` ${guide}` : " (e.g. feature/<slug>)"} Never record a verdict on your own work. Never push, open a PR, or merge unless the brief asks for it.`;
   if (isolated)
-    return `${ISOLATED_GIT}\n${subagentStartText({ ...input, cwd: "" }, descriptor, event)}`;
+    return `${isolatedGit(input.cwd)}\n${subagentStartText({ ...input, cwd: "" }, descriptor, event)}`;
   if (role === "implementer")
     // No host isolation: the lead makes the worktree, and workit git works there.
-    return `Workit observed ${who} as an implementer: it edits and commits only in its own git worktree (the lead makes one with \`workit fanout worktree create <slice>\`), never in the lead's checkout, within its brief's scope. Before the first commit, switch to a policy-compliant branch with \`workit git branch <branch> --base <base>\` (e.g. feature/<slug>); branch policy hooks still deny protected or non-compliant branches. Never record a verdict on your own work. Never push, open a PR, or merge unless the brief asks for it.`;
+    return `Workit observed ${who} as an implementer: it edits and commits only in its own git worktree (the lead makes one with \`workit fanout worktree create <slice>\`), never in the lead's checkout, within its brief's scope. Before the first commit, switch to a policy-compliant branch with \`workit git branch <branch> --base <base>\` (or \`--kind <kind> --slug <slug>\`, which picks the base); branch policy hooks still deny protected or non-compliant branches, raw git included.${guide ? ` ${guide}` : " (e.g. feature/<slug>)"} Never record a verdict on your own work. Never push, open a PR, or merge unless the brief asks for it.`;
   const readOnly = `Workit observed ${who} as read-only/agent-guided.`;
   if (role !== "judge" || !event.agentId) return readOnly;
   const own = subagentSession(session, event.agentId);
@@ -139,7 +146,7 @@ export function handleHook(input: HookInput, deps: HookDeps): HookDecision {
       const skillRead = skillReadIn(event.command, event.dialect);
       if (skillRead) recordSkillLoad(input, skillRead, "read");
       const canDeny = usable(descriptor.shellPolicy.deny);
-      const policy = canDeny ? shellPolicy(input.cwd, event.command) : NONE;
+      const policy = canDeny ? shellPolicy(input.cwd, event.command, event.dialect) : NONE;
       if (policy.kind !== "none") return policy;
       // Without a post-tool event, the previous raw commit is recorded now.
       const postTool = usable(descriptor.events["shell.post"].support);

package/src/hooks/policy.ts

@@ -1,13 +1,19 @@
 import { shellBranchPolicyViolation } from "../core/route-intent";
 import type { HookDecision } from "./protocol";
+import type { ShellDialect } from "./shell-words";
 
 /**
- * Branch policy for one shell command: only direct literal branch creation
- * onto a noncompliant name is denied. Every other command keeps the host's own
- * permission decision. The reason carries the policy's correction.
+ * Branch policy for one shell command: a raw branch creation (`git switch -c`,
+ * `checkout -b`, `branch`, `worktree add -b`, in any chain, directory or
+ * wrapper) onto a noncompliant name is denied. Every other command keeps the
+ * host's own permission decision. The reason carries the policy's correction.
  */
-export const shellPolicy = (cwd: string, command: string): HookDecision => {
-  const policy = shellBranchPolicyViolation(cwd, command);
+export const shellPolicy = (
+  cwd: string,
+  command: string,
+  dialect: ShellDialect = "posix",
+): HookDecision => {
+  const policy = shellBranchPolicyViolation(cwd, command, dialect);
   return policy && !policy.ok
     ? { kind: "deny", reason: `branch_policy_denied: ${policy.error}`, unblock: null }
     : { kind: "none" };