@brainervirus/workit-core 8.11.0 → 8.12.0

package/src/core/workspaces.ts

@@ -143,6 +143,12 @@ const workspaceConfigSchema = z
     defaultEndpoint: z.unknown().optional(),
     /** How a normal-risk behavior change is verified (S17); same rules as grants. */
     verification: z.enum(["self", "independent"]).optional(),
+    /**
+     * Whether commits get the `Workit-Session:` trailer (default true). With
+     * `false`, `workit git commit` and the session hook write none and
+     * authorship lives in the ledger only (`commit.recorded`).
+     */
+    trailers: z.boolean().optional(),
     /** Autonomy grants (D15): only ever set here, by the user. */
     autonomy: z
       .object(
@@ -633,8 +639,14 @@ const runtimeWorkspaceIndexSchema = z
 /** The workspaces.json entry matching cwd, checked only for name/glob (D17). */
 const matchRuntimeWorkspace = (
   cwd: string,
-): { file: string; selected: Record<string, unknown> & { name: string } } | null => {
-  const file = path.join(configDir(), "workspaces.json");
+  dir: string = configDir(),
+): {
+  file: string;
+  selected: Record<string, unknown> & { name: string };
+  /** Every entry whose glob matches cwd, the selected one included. */
+  matches: Array<Record<string, unknown> & { name: string; glob: string }>;
+} | null => {
+  const file = path.join(dir, "workspaces.json");
   let raw: string;
   try {
     raw = readFileSync(file, "utf8");
@@ -666,7 +678,7 @@ const matchRuntimeWorkspace = (
   const matches = matchingEntries(cwd, entries ?? []);
   const workspaceName = process.env.WORKFLOW_WORKSPACE_NAME?.trim() || undefined;
   const selected = selectWorkspaceMatch(matches, cwd, workspaceName);
-  return selected ? { file, selected } : null;
+  return selected ? { file, selected, matches } : null;
 };
 
 /**
@@ -683,6 +695,37 @@ export const resolveRuntimeReleaseTracks = (
     : null;
 };
 
+/**
+ * Whether commits in cwd's workspace carry the `Workit-Session:` trailer.
+ * The selected workspace's own `trailers` wins; unset, it inherits from the
+ * nearest enclosing workspace that also matches cwd (a repo workspace nested
+ * in `work`), and defaults to true. Read leniently: no workspace, or an
+ * unreadable workspaces.json, keeps the trailer. `from` names the entry the
+ * value came from (null for the default).
+ */
+export const workspaceTrailers = (
+  cwd: string,
+  dir?: string,
+): { enabled: boolean; workspace: string | null; from: string | null } => {
+  let matched: ReturnType<typeof matchRuntimeWorkspace>;
+  try {
+    matched = matchRuntimeWorkspace(cwd, dir);
+  } catch {
+    return { enabled: true, workspace: null, from: null };
+  }
+  if (!matched) return { enabled: true, workspace: null, from: null };
+  const { selected, matches } = matched;
+  const enclosing = matches
+    .filter((entry) => entry !== selected)
+    .toSorted((a, b) => globSpecificity(b.glob) - globSpecificity(a.glob));
+  const source = [selected, ...enclosing].find((entry) => typeof entry.trailers === "boolean");
+  return {
+    enabled: source?.trailers !== false,
+    workspace: selected.name,
+    from: source?.name ?? null,
+  };
+};
+
 const resolveRuntimeWorkspaceCandidate = (
   cwd: string,
   kind: RuntimeWorkspacePolicy,

package/src/fanout-brief.ts

@@ -7,6 +7,10 @@
 // `<branch>-try<n>` (refused when another slice has that branch), worktree
 // `<worktree>+try<n>` and session `<lead>-w-<slice>+try<n>`: slice ids cannot
 // contain `+`, so no attempt collides with another slice's path or session.
+// The lead's host (WORKIT_HOST, or its own session variable) picks the identity
+// and git rules: Claude Code workers use the WORKIT_SESSION_ID in their env (the lead's: SubagentStart issues ids only to judges) and plain
+// git; OpenCode, Pi and Codex workers export nothing (the host derives the id);
+// Cursor, CI and plain terminals export `<lead>-w-<slice>`.
 // The lead must have a WORKIT_SESSION_ID: worker ids derive from it. A
 // worker id longer than the ledger's 128 characters hashes its slice part. The fan-in line follows the plan's `fanIn`:
 // one PR per slice forbids every merge; integration mode has the worker merge
@@ -36,7 +40,8 @@ export type BriefOutcome = {
   tier: string;
   /** Absolute when the slice's worktree exists, else relative to the worker's worktree root. */
   scratch: string;
-  session: string;
+  /** The id a worker exports, or null when its host issues or derives it. */
+  session: string | null;
   standing: Array<{ id: string; what: string }>;
   text: string;
 };
@@ -49,15 +54,61 @@ const REPORT = [
   "  anything out of scope as a follow-up, not a diff.",
 ];
 
-const rules = (mode: BriefMode, branch: string, base: string): string[] => [
-  "RULES:",
-  mode === "new"
-    ? `  1. First command: \`workit git branch ${branch} --base ${base}\` (your worktree may start on another name).`
-    : `  1. First command: \`git switch ${branch}\`, then continue from its head.`,
-  '  2. Decide ambiguities yourself: `workit ledger ruling "<what>" --why "<why>" --cost-if-wrong "<cost>"`; stop only for an irreversible, security-sensitive or out-of-worktree action.',
-  "  3. Commit with `workit git commit -m <msg> -- <paths in SCOPE>`; push only if this brief says so.",
-  "  4. Never record a verdict on your own work.",
-];
+/**
+ * How a worker's identity is settled on the lead's host (host-session.ts,
+ * docs/agents/hosts.md):
+ *   - `issued`: Claude Code. SubagentStart issues ids only to verifiers and
+ *     reviewers, so an implementer keeps the lead's WORKIT_SESSION_ID from its
+ *     env; worktree isolation refuses every `workit git` form, so it uses
+ *     plain git and never mints an id;
+ *   - `derived`: OpenCode, Pi, Codex. The worker's shell carries the host's own
+ *     session id, which exporting WORKIT_SESSION_ID cannot replace;
+ *   - `declared`: Cursor, CI, a plain terminal. Nothing vouches for an id, so
+ *     the brief declares `<lead>-w-<slice>`.
+ */
+export type BriefIdentity = "issued" | "derived" | "declared";
+
+const identityOf = (host: string | null): BriefIdentity => {
+  const family = host?.replace(/_(?:cli|desktop)$/, "") ?? "";
+  if (family === "claude_code") return "issued";
+  if (family === "opencode" || family === "pi" || family === "codex") return "derived";
+  return "declared";
+};
+
+const identityLines = (identity: BriefIdentity, session: string): string[] => {
+  if (identity === "issued")
+    return [
+      "  Session: your env already has WORKIT_SESSION_ID (the lead's id; SubagentStart issues ids only to verifiers and reviewers). Use it as is, in your Workit-Session trailer and workit commands; never export or hand-mint one.",
+    ];
+  if (identity === "derived")
+    return [
+      "  Session: your host already sets WORKIT_SESSION_ID in your shell; export nothing and never hand-mint one.",
+    ];
+  return [`  export WORKIT_SESSION_ID=${session}`];
+};
+
+const rules = (
+  identity: BriefIdentity,
+  mode: BriefMode,
+  branch: string,
+  base: string,
+): string[] => {
+  const plain = identity === "issued";
+  let first = `  1. First command: \`workit git branch ${branch} --base ${base}\` (your worktree may start on another name).`;
+  if (mode === "resume")
+    first = `  1. First command: \`git switch ${branch}\`, then continue from its head.`;
+  else if (plain)
+    first = `  1. First command: \`git fetch origin && git switch -c ${branch} origin/${base}\` (plain git: worktree isolation refuses every \`workit git\` form).`;
+  return [
+    "RULES:",
+    first,
+    '  2. Decide ambiguities yourself: `workit ledger ruling "<what>" --why "<why>" --cost-if-wrong "<cost>"`; stop only for an irreversible, security-sensitive or out-of-worktree action.',
+    plain
+      ? '  3. Commit with plain `git commit -m <msg> --trailer "Workit-Session: <the WORKIT_SESSION_ID in your env>" --trailer "<your host attribution trailer>" -- <paths in SCOPE>`; push only if this brief says so.'
+      : "  3. Commit with `workit git commit -m <msg> -- <paths in SCOPE>`; push only if this brief says so.",
+    "  4. Never record a verdict on your own work.",
+  ];
+};
 
 /** A session id fragment that the ledger accepts ([A-Za-z0-9_.:@/+-]). */
 const sessionSafe = (text: string): string => text.replace(/[^A-Za-z0-9_.:@/+-]/gu, "-");
@@ -119,7 +170,9 @@ export function renderBrief(
     id: row.id,
     what: String(row.what),
   }));
-  const session = workerSession(sessionSafe(input.actor.session), slice.id, input.attempt);
+  const identity = identityOf(input.actor.host);
+  const minted = workerSession(sessionSafe(input.actor.session), slice.id, input.attempt);
+  const session = identity === "declared" ? minted : null;
   const fanIn =
     plan.fanIn === "integration"
       ? [
@@ -156,8 +209,8 @@ export function renderBrief(
     ...(standing.length
       ? standing.map((order) => `  - ${order.what}`)
       : ["  - none recorded beyond this brief"]),
-    `  export WORKIT_SESSION_ID=${session}`,
-    ...rules(mode, branch, slice.base),
+    ...identityLines(identity, minted),
+    ...rules(identity, mode, branch, slice.base),
   ];
   return {
     ok: true,

package/src/forge/exec.ts

@@ -31,6 +31,8 @@ export type ForgeRunner = (
     timeoutMs: number;
     /** Credential for this call (GH_TOKEN / GITLAB_TOKEN); never logged. */
     token?: string;
+    /** Written to stdin (a JSON body for `api --input -`); argv has a size limit. */
+    input?: string;
   },
 ) => CliRun;
 
@@ -90,7 +92,9 @@ export function systemRunner(
       timeout: options.timeoutMs,
       killSignal: "SIGKILL",
       windowsHide: true,
-      stdio: ["ignore", "pipe", "pipe"],
+      ...(options.input === undefined
+        ? { stdio: ["ignore", "pipe", "pipe"] as const }
+        : { input: options.input, stdio: ["pipe", "pipe", "pipe"] as const }),
     });
     const error: NodeJS.ErrnoException | undefined = result.error;
     return {
@@ -248,8 +252,10 @@ export function apiWrite<T>(
   args: readonly string[],
   what: string,
   timeoutMs: number = FORGE_TIMEOUTS.api,
+  /** A request body sent on stdin (pair it with `--input -`). */
+  input?: string,
 ): ForgeResult<T> {
-  const run = runner(bin, args, { timeoutMs });
+  const run = runner(bin, args, input === undefined ? { timeoutMs } : { timeoutMs, input });
   if (run.status !== 0) {
     const text = redactText(`${run.stderr}\n${run.stdout}`).trim();
     const reason = forgeReason(run);

package/src/forge/github.ts

@@ -528,6 +528,7 @@ export function createGitHubForge(options: {
     },
 
     merge(number, mergeOptions) {
+      const squash = mergeOptions.method === "squash" ? mergeOptions.squashMessage : undefined;
       // sha= is GitHub's atomic head guard: 409 when the head moved.
       const merged = apiWrite<{ sha?: string; merged?: boolean; message?: string }>(
         runner,
@@ -538,12 +539,21 @@ export function createGitHubForge(options: {
           "-X",
           "PUT",
           `repos/${repo}/pulls/${number}/merge`,
-          "-f",
-          `sha=${mergeOptions.sha}`,
-          "-f",
-          `merge_method=${mergeOptions.method}`,
+          ...(squash
+            ? ["--input", "-"]
+            : ["-f", `sha=${mergeOptions.sha}`, "-f", `merge_method=${mergeOptions.method}`]),
         ],
         `merge of pull request #${number}`,
+        undefined,
+        // The squash message rides stdin: argv has a size limit (E2BIG).
+        squash
+          ? JSON.stringify({
+              sha: mergeOptions.sha,
+              merge_method: mergeOptions.method,
+              commit_title: squash.subject,
+              commit_message: squash.body,
+            })
+          : undefined,
       );
       if (!merged.ok) return merged;
       if (merged.data.merged === false)

package/src/forge/gitlab.ts

@@ -556,6 +556,7 @@ export function createGitLabForge(options: {
     },
 
     merge(iid, mergeOptions) {
+      const squash = mergeOptions.method === "squash" ? mergeOptions.squashMessage : undefined;
       // GitLab's merge method is a project setting; squash is per request.
       if (mergeOptions.method === "rebase")
         return failure(
@@ -573,12 +574,27 @@ export function createGitLabForge(options: {
           "-X",
           "PUT",
           `${project}/merge_requests/${iid}/merge`,
-          "-f",
-          `sha=${mergeOptions.sha}`,
-          "-F",
-          `squash=${mergeOptions.method === "squash" ? "true" : "false"}`,
+          ...(squash
+            ? ["--input", "-"]
+            : [
+                "-f",
+                `sha=${mergeOptions.sha}`,
+                "-F",
+                `squash=${mergeOptions.method === "squash" ? "true" : "false"}`,
+              ]),
         ],
         `merge of merge request !${iid}`,
+        undefined,
+        // The squash message rides stdin: argv has a size limit (E2BIG).
+        squash
+          ? JSON.stringify({
+              sha: mergeOptions.sha,
+              squash: true,
+              squash_commit_message: squash.body
+                ? `${squash.subject}\n\n${squash.body}`
+                : squash.subject,
+            })
+          : undefined,
       );
       if (!merged.ok) return merged;
       const value = merged.data;

package/src/forge/pr-ops.ts

@@ -16,6 +16,9 @@
 // The merge call carries the head SHA (GitHub `sha=`, GitLab `sha=`), so a
 // head that moves after the gates refuses instead of merging unverified code.
 // --delete-branch deletes with a lease on that same SHA.
+// A squash with --subject/--body, or in a workspace with `trailers: false`,
+// sends its own message (the PR title and the branch's commits by default,
+// on stdin) with `Workit-Session:` lines dropped from each trailer block.
 import {
   requireGrant,
   resolveAutonomy,
@@ -24,8 +27,9 @@ import {
 } from "../autonomy";
 import { branchKindOf, flowRoute, gitFlowOf, isProtectedTarget } from "../core/branch";
 import { vcsConfig } from "../core/vcs-config";
+import { workspaceTrailers } from "../core/workspaces";
 import { workspaceReleaseTracks } from "../core/release-tracks";
-import { deleteRemoteBranch } from "../git/ops";
+import { deleteRemoteBranch, stripSessionTrailers } from "../git/ops";
 import { spawnSync } from "node:child_process";
 import { currentBranch, fetchRefs, GIT_TIMEOUTS, remoteRefTip, resolveRef } from "../git/rev";
 import {
@@ -343,6 +347,9 @@ export type MergeInput = {
   expect?: { base: string; branch: string };
   /** Merge without a verdict (`merge: true` only); the reason is recorded. */
   unverified?: { reason: string };
+  /** Squash commit subject and body (`--subject`, `--body`); unset parts use the defaults. */
+  subject?: string;
+  body?: string;
 };
 
 export type MergeOutcome = {
@@ -469,6 +476,90 @@ export function nextHint(next: string, number: number): string | null {
   }
 }
 
+/**
+ * The squash message workit sends, or null to leave the forge default: only a
+ * squash with --subject/--body or in a workspace with `trailers: false`.
+ * Defaults: the PR title (GitHub appends `(#n)` like its own default) and the
+ * branch's commits as GitHub lists them; Workit-Session lines never survive.
+ */
+function squashMessageFor(
+  cwd: string,
+  resolved: ResolvedForge,
+  input: MergeInput,
+  doc: PrStatusDoc,
+): ForgeResult<{ subject: string; body: string }> | null {
+  if (input.method !== "squash") return null;
+  if (input.subject === undefined && input.body === undefined && workspaceTrailers(cwd).enabled)
+    return null;
+  let subject = input.subject?.trim() ?? "";
+  if (!subject) {
+    const meta = resolved.forge.prMeta(doc.number);
+    if (!meta.ok) return meta;
+    subject =
+      resolved.forge.kind === "github" ? `${meta.data.title} (#${doc.number})` : meta.data.title;
+  }
+  // An explicit body is kept byte for byte but for its trailer block.
+  const body =
+    input.body === undefined
+      ? squashCommitList(cwd, resolved, doc.base, doc.head.sha)
+      : stripSessionTrailers(input.body, { subject: false });
+  return success({ subject, body });
+}
+
+/** Bounds of the generated squash body: a forge message, not an archive. */
+const SQUASH_LIST_MAX_COMMITS = 100;
+const SQUASH_LIST_MAX_CHARS = 60_000;
+
+/**
+ * `* subject` and body of each non-merge commit on `base..head`, oldest
+ * first, from the local clone ("" when absent); each commit loses its
+ * Workit-Session trailers, and past the bounds the rest is counted.
+ */
+function squashCommitList(
+  cwd: string,
+  resolved: ResolvedForge,
+  base: string,
+  head: string,
+): string {
+  const from =
+    resolveRef(cwd, `refs/remotes/${resolved.baseRemote}/${base}`) ??
+    resolveRef(cwd, `refs/heads/${base}`);
+  if (!from) return "";
+  const log = spawnSync(
+    "git",
+    ["log", "--reverse", "--no-merges", "--format=%B%x1e", `${from}..${head}`],
+    {
+      cwd,
+      encoding: "utf8",
+      timeout: GIT_TIMEOUTS.local,
+      killSignal: "SIGKILL",
+      maxBuffer: 64 * 1024 * 1024,
+    },
+  );
+  if (log.status !== 0) return "";
+  const entries = log.stdout
+    .split("\x1e")
+    .map((message) => stripSessionTrailers(message.replace(/^\n+/u, ""), { subject: true }))
+    .filter((message) => message.trim())
+    .map((message) => {
+      const [subject = "", ...rest] = message.trimEnd().split("\n");
+      const body = rest.join("\n").replace(/^\n+/u, "");
+      return body ? `* ${subject}\n\n${body}` : `* ${subject}`;
+    });
+  const listed: string[] = [];
+  let size = 0;
+  for (const entry of entries) {
+    if (listed.length >= SQUASH_LIST_MAX_COMMITS || size + entry.length > SQUASH_LIST_MAX_CHARS)
+      break;
+    listed.push(entry);
+    size += entry.length + 2;
+  }
+  const more = entries.length - listed.length;
+  return [...listed, ...(more ? [`… and ${more} more commit${more === 1 ? "" : "s"}`] : [])].join(
+    "\n\n",
+  );
+}
+
 export async function mergePullRequest(
   cwd: string,
   resolved: ResolvedForge,
@@ -596,7 +687,13 @@ export async function mergePullRequest(
       { reason: "needs_verdict", verdict: summary },
     );
 
-  const merged = resolved.forge.merge(doc.number, { sha: head, method: input.method });
+  const squashMessage = squashMessageFor(cwd, resolved, input, doc);
+  if (squashMessage && !squashMessage.ok) return squashMessage;
+  const merged = resolved.forge.merge(doc.number, {
+    sha: head,
+    method: input.method,
+    ...(squashMessage ? { squashMessage: squashMessage.data } : {}),
+  });
   if (!merged.ok) return merged;
   // Post-verify: the forge must report the PR merged.
   let state = "open";

package/src/forge/types.ts

@@ -140,6 +140,13 @@ export type CreatePrInput = {
   draft: boolean;
 };
 
+export type MergeOptions = {
+  sha: string;
+  method: MergeMethod;
+  /** Squash only: the commit message the forge writes instead of its default. */
+  squashMessage?: { subject: string; body: string };
+};
+
 export type MergeResult = {
   /** The merge (or squash/rebase tip) commit the forge reported, when it did. */
   mergeSha: string | null;
@@ -187,7 +194,7 @@ export interface Forge {
    * Merge with the head guard: the forge refuses (`blocked`, head_moved) when
    * the PR head is no longer `sha`.
    */
-  merge(n: number, options: { sha: string; method: MergeMethod }): ForgeResult<MergeResult>;
+  merge(n: number, options: MergeOptions): ForgeResult<MergeResult>;
   /** Retarget a PR/MR to another base branch (S12 stacks). */
   updateBase(n: number, base: string): ForgeResult<void>;
   /** Title, draft flag, base and state of one PR/MR. */

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
@@ -39,6 +41,7 @@ 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";
@@ -395,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). */
@@ -430,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"];
@@ -522,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;
   },
@@ -529,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);
@@ -559,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);
@@ -568,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;
@@ -588,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 -");
@@ -632,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(
@@ -688,6 +782,7 @@ export function gitCommit(
     files,
     leftDirty,
     session,
+    sessionTrailer,
     amended: previous,
     notes,
     recorded: row.ok ? { id: String(row.value.id) } : { error: row.error },