@brainervirus/workit-core 8.14.1 → 8.15.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainervirus/workit-core",
-  "version": "8.14.1",
+  "version": "8.15.1",
   "private": false,
   "description": "Workit shared core — task, policy, evidence, review, decision, worker, and writer state for agentic coding workflows",
   "keywords": [

package/skills/workit-ship/SKILL.md

@@ -33,8 +33,8 @@ that repeats because the base keeps moving, or after 3 failed fix attempts on
 the same check.
 
 1. **Open.** `workit git push`, then `workit pr create --title "<title>"
-   --body-file <f|->` (idempotent; body: `references/pr-body.md`; edits:
-   `workit pr edit`). A stack: `workit stack plan <bottom> ... <top>`, one
+   --body-file <f|->` plus `--issue <#n|ID>` per issue (`--refs`: no close; idempotent;
+   body: `references/pr-body.md`; edits: `workit pr edit`). A stack: `workit stack plan <bottom> ... <top>`, one
    `workit pr create --base <parent> --fill` per branch, then
    `workit stack sync`. Finish the whole stack before babysitting any PR.
 2. **Read state** with `workit pr status --json`. `REVIEW` alone is a pending

package/src/core/vcs-config.ts

@@ -143,6 +143,93 @@ export const readVcsConfig = (): VcsConfigResult => {
   return { status: "malformed", path: file, config: {}, error: `${file} is not a JSON object` };
 };
 
+export type IssueTrackerProvider = "github" | "gitlab" | "youtrack";
+
+/** A workspace's issue tracker, with legacy keys migrated (issueTrackerOf). */
+export type IssueTracker = {
+  provider: IssueTrackerProvider;
+  /** Derive the issue from the branch name when no issue is named. */
+  link: boolean;
+  relation: "closes" | "refs";
+  /** Post the PR URL on each linked issue after the PR is opened. */
+  backlink: boolean;
+  /** YouTrack's base URL from the workspace (`youtrack.baseUrl`), else null. */
+  baseUrl: string | null;
+  /** The GitHub/GitLab repository that holds the issues (`issues.repo`); null: the PR's own. */
+  repo: string | null;
+  /** That repository's host (`issues.host`); null: the PR's host, or the tracker's public one. */
+  host: string | null;
+  /** Which keys set it: the `issues` block or a legacy alias. */
+  source: "issues" | "issues.link_on_pr" | "youtrack.link_issues" | "youtrack.baseUrl";
+  /** Values read leniently (D17): what was ignored and what was used instead. */
+  warnings: string[];
+};
+
+const TRACKERS: ReadonlySet<string> = new Set(["github", "gitlab", "youtrack"]);
+
+const asRecord = (value: unknown): Record<string, unknown> =>
+  value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+
+const flag = (value: unknown): boolean | null => (typeof value === "boolean" ? value : null);
+
+const text = (value: unknown): string | null =>
+  typeof value === "string" && value.trim() ? value.trim() : null;
+
+/**
+ * The tracker from a workspace's `issues` and `youtrack` blocks. Legacy
+ * configs keep their behavior: `youtrack.link_issues: true` reads as
+ * `{ provider: youtrack, link: true }` (and wins over a legacy GitHub
+ * `link_on_pr`, as it always did), `issues.link_on_pr` as `link`, and a bare
+ * `youtrack.baseUrl` as a YouTrack tracker that links only named issues. An
+ * unknown `relation`, `repo` or `host` is a warning, never an error (D17).
+ */
+export function issueTrackerOf(issues: unknown, youtrack: unknown): IssueTracker | null {
+  const iss = asRecord(issues);
+  const yt = asRecord(youtrack);
+  const warnings: string[] = [];
+  const named =
+    typeof iss.provider === "string" && TRACKERS.has(iss.provider.toLowerCase())
+      ? (iss.provider.toLowerCase() as IssueTrackerProvider)
+      : null;
+  if (iss.relation !== undefined && iss.relation !== "closes" && iss.relation !== "refs")
+    warnings.push(
+      `issues.relation ${JSON.stringify(iss.relation)} is not closes or refs; read as closes`,
+    );
+  for (const key of ["repo", "host"] as const)
+    if (iss[key] !== undefined && text(iss[key]) === null)
+      warnings.push(`issues.${key} is not a non-empty string; ignored`);
+  const common = {
+    relation: iss.relation === "refs" ? ("refs" as const) : ("closes" as const),
+    backlink: iss.backlink === true,
+    baseUrl: text(yt.baseUrl),
+    repo: text(iss.repo)?.replace(/^\/+|\/+$/gu, "") ?? null,
+    host: text(iss.host)?.toLowerCase() ?? null,
+    warnings,
+  };
+  const legacyGithub = named === "github" && flag(iss.link) === null;
+  if (flag(yt.link_issues) === true && (named === null || legacyGithub))
+    return { provider: "youtrack", link: true, ...common, source: "youtrack.link_issues" };
+  if (named) {
+    const link =
+      flag(iss.link) ??
+      flag(iss.link_on_pr) ??
+      (named === "youtrack" ? flag(yt.link_issues) : null) ??
+      false;
+    return {
+      provider: named,
+      link,
+      ...common,
+      source:
+        flag(iss.link) === null && flag(iss.link_on_pr) !== null ? "issues.link_on_pr" : "issues",
+    };
+  }
+  if (common.baseUrl)
+    return { provider: "youtrack", link: false, ...common, source: "youtrack.baseUrl" };
+  return null;
+}
+
 /** The release track a vcsConfig call resolved (null: the workspace has no tracks). */
 export type ResolvedReleaseTrack = {
   name: string | null;
@@ -220,6 +307,7 @@ export function vcsConfig(
   // CA-05/CA-02 (workspaces.ts workspaceDefaultTarget): shared with doctor
   // and grant show so their display never disagrees with the commands.
   const workspaceDefault = workspaceDefaultTarget(root, cfg.defaultTargetBranch);
+  const issueTracker = issueTrackerOf(wsIssues, wsYt);
   const linkIssues = typeof wsYt.link_issues === "boolean" ? wsYt.link_issues : null;
   const youtrackBaseUrl = typeof wsYt.baseUrl === "string" ? wsYt.baseUrl : null;
   // github issues path only when BOTH providers are github (mirrors WorkspaceConfig.issues).
@@ -267,6 +355,7 @@ export function vcsConfig(
       youtrack_base_url: youtrackBaseUrl,
       issues_provider: issuesProvider,
       link_on_pr: linkOnPr,
+      issue_tracker: issueTracker,
     };
   }
 
@@ -297,6 +386,7 @@ export function vcsConfig(
     youtrack_base_url: youtrackBaseUrl,
     issues_provider: issuesProvider,
     link_on_pr: linkOnPr,
+    issue_tracker: issueTracker,
   };
   if (provider === "gitlab") {
     out.gitlab = {

package/src/core/workers.ts

@@ -51,3 +51,12 @@ export const workerBlocksTransition = (
   transition: "pause" | "resume" | "revise" | "close",
   state: WorkerState,
 ): boolean => (transition === "pause" ? false : isUncertainWorker(state));
+
+/**
+ * A worker may be continued in its own session only while it holds live
+ * state: a running process, or uncommitted changes in its worktree. A worker
+ * that reported and is clean is continued by a fresh worker on the same
+ * slice. An unreadable worktree counts as no live state.
+ */
+export const holdsLiveState = (state: WorkerState, dirty: boolean | null): boolean =>
+  state === "running" || dirty === true;

package/src/core/workspaces.ts

@@ -175,8 +175,21 @@ const workspaceConfigSchema = z
       .object({ baseUrl: nonBlank.optional(), link_issues: z.boolean().optional() })
       .passthrough()
       .optional(),
+    /**
+     * The issue tracker PRs link to (any forge with any tracker). `link`
+     * derives the issue from the branch; `youtrack.link_issues` and
+     * `link_on_pr` are read as aliases (vcs-config.ts issueTrackerOf).
+     * `relation`, `repo` and `host` are read leniently there (D17): an
+     * unknown value warns and falls back, never invalidating the file.
+     */
     issues: z
-      .object({ provider: z.literal("github").optional(), link_on_pr: z.boolean().optional() })
+      .object({
+        provider: z.enum(["github", "gitlab", "youtrack"]).optional(),
+        link: z.boolean().optional(),
+        relation: z.unknown().optional(),
+        backlink: z.boolean().optional(),
+        link_on_pr: z.boolean().optional(),
+      })
       .passthrough()
       .optional(),
     branchPolicy: workspaceBranchPolicySchema.optional(),
@@ -187,13 +200,6 @@ const workspaceConfigSchema = z
   })
   .passthrough()
   .superRefine((workspace, context) => {
-    if (workspace.issues && workspace.vcs?.provider !== "github") {
-      context.addIssue({
-        code: "custom",
-        path: ["issues"],
-        message: `GitHub issue linking requires the github provider, got ${workspace.vcs?.provider ?? "unset"}`,
-      });
-    }
     if (
       workspace.defaultProfile !== undefined &&
       !Object.hasOwn(workspace.profiles ?? {}, workspace.defaultProfile)

package/src/core/youtrack.ts

@@ -224,6 +224,14 @@ export function youTrackWorkDateMs(dateRaw: string):
   }
 }
 
+/** youtrack.json's baseUrl without trailing slashes, read-only (no token needed); null when unset. */
+export const youTrackBaseUrl = (): string | null => {
+  const read = readYouTrackContextConfig();
+  if ("error" in read) return null;
+  const base = typeof read.data.baseUrl === "string" ? read.data.baseUrl.replace(/\/+$/, "") : "";
+  return base || null;
+};
+
 export const youTrackToken = (): { token: string; base: string } | { error: string } => {
   const loaded = readYouTrackConfig(true);
   if ("error" in loaded) return loaded;

package/src/fanout-brief.ts

@@ -39,6 +39,8 @@ export type BriefOutcome = {
   branch: string;
   base: string;
   tier: string;
+  /** Issues the slice's PR links (the brief's ISSUE line). */
+  issues: string[];
   /** The model `fanout.tierModels` names for the tier on the lead's host, else null. */
   model: string | null;
   /** Absolute when the slice's worktree exists, else relative to the worker's worktree root. */
@@ -195,6 +197,11 @@ export function renderBrief(
     ...(slice.owns.length ? [`  owns: ${slice.owns.join(", ")}`] : []),
     `  branch: ${branch}   base: ${slice.base}`,
     `CONTEXT: ${slice.context ?? "none given: read the files in SCOPE and the neighbours they import"}`,
+    ...(slice.issues.length
+      ? [
+          `ISSUE: ${slice.issues.join(", ")}  (\`workit pr create\` on ${branch} links ${slice.issues.length === 1 ? "it" : "them"} by itself; no --issue needed)`,
+        ]
+      : []),
     ...(mode === "resume" && head
       ? [
           `  resume: continue ${branch} from ${head.slice(0, 12)}; read \`git log ${slice.base}..${branch}\` and \`workit ledger list --branch ${branch}\` (the last report, verdicts, rulings)`,
@@ -229,6 +236,7 @@ export function renderBrief(
       branch,
       base: slice.base,
       tier: slice.tier,
+      issues: slice.issues,
       model: model?.model ?? null,
       scratch,
       session,

package/src/fanout.ts

@@ -20,7 +20,7 @@
 //
 // Each slice's `hash` covers what it is (goal, acceptance, verify, forbidden,
 // scope, owns, branch, base, dependencies), not how it is briefed (tier,
-// timebox, context) or where its worktree goes. A re-plan that changes a
+// timebox, context, issues) or where its worktree goes. A re-plan that changes a
 // slice starts a new run for that slice alone: its `hashSince` moves to now,
 // and only ledger rows recorded under its hash (worktree rows carry
 // `sliceHash`) or since then link a gone branch's merged PR to it or count as
@@ -69,6 +69,8 @@ export type Slice = {
   forbidden: string[];
   context: string | null;
   timebox: string | null;
+  /** Issues the slice's PR links (`issue` in the plan: `#42`, `IRPT-74` or a URL). */
+  issues: string[];
   /** sliceHash of this definition: which run of the slice a ledger row belongs to. */
   hash: string;
   /** When a slice with this hash was first planned: older rows are not its run. */
@@ -405,6 +407,8 @@ export function parsePlan(raw: unknown, defaults: PlanDefaults, name?: string |
       problems.push(`${where}: tier must be one of ${TIERS.join(", ")}`);
     const dependsOn = textList(item.dependsOn ?? []);
     if (dependsOn === null) problems.push(`${where}: dependsOn must be a list of slice ids`);
+    const issues = textList(item.issue ?? []);
+    if (issues === null) problems.push(`${where}: issue must be an issue id or a list of them`);
     const optional = (field: string): string | null =>
       typeof item[field] === "string" && filled(item[field]) ? item[field].trim() : null;
     slices.push({
@@ -425,6 +429,7 @@ export function parsePlan(raw: unknown, defaults: PlanDefaults, name?: string |
       forbidden,
       context: optional("context"),
       timebox: optional("timebox"),
+      issues: [...new Set((issues ?? []).map((entry) => entry.trim()).filter(filled))],
       hash: "",
       hashSince: "",
     });
@@ -777,7 +782,7 @@ export const planLeads = (
 
 /**
  * sha256 (16 hex) of the slice's definition. Brief-only fields (tier,
- * timebox, context) and the worktree path are left out, so fixing a typo in
+ * timebox, context, issues) and the worktree path are left out, so fixing a typo in
  * them never re-dispatches landed work.
  */
 export function sliceHash(slice: Slice): string {
@@ -788,6 +793,7 @@ export function sliceHash(slice: Slice): string {
     tier: _tier,
     timebox: _timebox,
     context: _context,
+    issues: _issues,
     ...definition
   } = slice;
   return createHash("sha256").update(JSON.stringify(definition)).digest("hex").slice(0, 16);
@@ -842,6 +848,7 @@ function parseStored(raw: unknown): FanoutFile | null {
       forbidden: list(item.forbidden),
       context: typeof item.context === "string" ? item.context : null,
       timebox: typeof item.timebox === "string" ? item.timebox : null,
+      issues: list(item.issues),
       hash: text(item.hash),
       // A plan written before slice hashes: its run began at createdAt.
       hashSince: text(item.hashSince) || text(raw.createdAt),
@@ -942,6 +949,28 @@ export function selectFanout(
       );
 }
 
+/**
+ * The issues the fanout slice on `branch` links (its `issue` field), so a
+ * worker's `workit pr create` links them unasked. A race attempt branch
+ * `<branch>-try<n>` counts as its slice; no plan or no slice is none.
+ */
+export function sliceIssuesFor(cwd: string, branch: string | null): string[] {
+  if (!branch) return [];
+  const all = listFanouts(cwd);
+  if (!all.ok) return [];
+  const issues = all.data.flatMap((plan) =>
+    plan.slices
+      .filter(
+        (slice) =>
+          slice.branch === branch ||
+          (branch.startsWith(`${slice.branch}-try`) &&
+            /^\d+$/u.test(branch.slice(slice.branch.length + 4))),
+      )
+      .flatMap((slice) => slice.issues),
+  );
+  return [...new Set(issues)];
+}
+
 function writeFanout(cwd: string, plan: FanoutFile): FanoutResult<string> {
   const dir = fanoutsDir(cwd);
   if (!dir.ok) return dir;

package/src/forge/github.ts

@@ -719,5 +719,29 @@ export function createGitHubForge(options: {
         url: safeUrl(created.data.html_url ?? null),
       });
     },
+
+    issueComments(n) {
+      const listed = rest<Array<{ body?: unknown }>>(
+        `repos/${repo}/issues/${n}/comments?per_page=100`,
+        `comments on issue #${n}`,
+      );
+      if (!listed.ok) return listed;
+      if (!Array.isArray(listed.data))
+        return failure("failed", `gh api issue #${n} comments returned no list`);
+      return success(
+        listed.data.flatMap((comment) => (typeof comment.body === "string" ? [comment.body] : [])),
+      );
+    },
+
+    commentIssue(n, body) {
+      const posted = apiWrite<unknown>(
+        runner,
+        "gh",
+        apiHost,
+        ["api", "-X", "POST", `repos/${repo}/issues/${n}/comments`, "-f", `body=${body}`],
+        `comment on issue #${n}`,
+      );
+      return posted.ok ? success(undefined) : posted;
+    },
   };
 }

package/src/forge/gitlab.ts

@@ -776,5 +776,32 @@ export function createGitLabForge(options: {
         url: safeUrl(created.data["_links"]?.self ?? null),
       });
     },
+
+    issueComments(iid) {
+      const listed = apiJson<Array<{ body?: unknown }>>(
+        runner,
+        "glab",
+        apiHost,
+        api(`${project}/issues/${iid}/notes?per_page=100`),
+        `notes on issue #${iid}`,
+      );
+      if (!listed.ok) return listed;
+      if (!Array.isArray(listed.data))
+        return failure("failed", `glab api issue #${iid} notes returned no list`);
+      return success(
+        listed.data.flatMap((note) => (typeof note.body === "string" ? [note.body] : [])),
+      );
+    },
+
+    commentIssue(iid, body) {
+      const posted = apiWrite<unknown>(
+        runner,
+        "glab",
+        apiHost,
+        ["api", "-X", "POST", `${project}/issues/${iid}/notes`, "-f", `body=${body}`],
+        `note on issue #${iid}`,
+      );
+      return posted.ok ? success(undefined) : posted;
+    },
   };
 }

package/src/forge/issue-link.ts

@@ -0,0 +1,458 @@
+// Issue links for `workit pr create` (#324): which issues a PR links, the body
+// line each one gets, the `pr.linked` ledger rows, the optional tracker
+// backlink, and the links `pr status` lists.
+//
+// Issues come from `--issue` (repeatable), else the fanout slice the branch
+// belongs to (its `issue` field), else the branch name when the workspace
+// tracker has `link: true`. `IRPT-74` and `.../issue/IRPT-74` are YouTrack;
+// an issue URL names its own forge; `#42`, `42` and `owner/repo#42` are on
+// the workspace tracker (`issues.provider` github or gitlab), else the PR's
+// forge. An issue on the PR's own forge closes in its syntax (`Closes #42`,
+// `Refs #42`, `Closes owner/repo#42`); one on another forge cannot close
+// across forges and gets `Related to: <issue URL>`.
+import { vcsConfig, type IssueTracker } from "../core/vcs-config";
+import { youTrackBaseUrl } from "../core/youtrack";
+import { defaultOperations, ISSUE_RE, unwrap } from "../core/youtrack-tools";
+import { withMarker, writeOnce, youTrackMarker, type OnceOutcome } from "../core/youtrack-writes";
+import { sliceIssuesFor } from "../fanout";
+import { appendObserved, type LedgerActor, type ReadRow } from "../ledger";
+import type { ForgeRunner } from "./exec";
+import { createGitHubForge } from "./github";
+import { createGitLabForge } from "./gitlab";
+import { deriveGhIssueFromBranch, deriveYouTrackIssueFromBranch } from "./pr-body";
+import type { ResolvedForge } from "./resolve";
+import type { Forge } from "./types";
+
+export type ForgeKind = "github" | "gitlab";
+/** What the body line says: a closing keyword, a reference, or a cross-tracker "Related to". */
+export type IssueRelation = "closes" | "refs" | "related";
+
+/** The PR's forge: where a same-forge issue reference closes. */
+export type PrForge = { kind: ForgeKind; repo: string; host: string };
+
+export type IssueLink = {
+  tracker: ForgeKind | "youtrack";
+  /** The issue number on a forge, the issue id on YouTrack. */
+  id: string;
+  /** The issue's repository when it is not the PR's own, else null. */
+  repo: string | null;
+  /** The issue's forge host when it is not the PR's, else null. */
+  host: string | null;
+  /** The issue's web URL when it is on another host or tracker, else null. */
+  url: string | null;
+  relation: IssueRelation;
+  source: "flag" | "fanout" | "branch";
+  /** The line the PR body carries for it. */
+  line: string;
+};
+
+export type IssueLinkPlan = {
+  links: IssueLink[];
+  /** The workspace tracker's `backlink`. */
+  backlink: boolean;
+  tracker: IssueTracker | null;
+  /** Config read leniently, or a link that could not be derived. */
+  warnings: string[];
+};
+
+/** An issue as named: its host and repo only when the name carries them. */
+type NamedRef = {
+  tracker: ForgeKind | "youtrack";
+  id: string;
+  repo: string | null;
+  host: string | null;
+};
+
+const DEFAULT_HOST: Record<ForgeKind, string> = { github: "github.com", gitlab: "gitlab.com" };
+
+const same = (left: string | null, right: string | null): boolean =>
+  (left ?? "").toLowerCase() === (right ?? "").toLowerCase();
+
+/**
+ * One `--issue` value: `#42`, `42`, `owner/repo#42`, `IRPT-74` or an issue
+ * URL. A bare or short form is an issue on `tracker`.
+ */
+export function parseIssueRef(
+  raw: string,
+  tracker: ForgeKind,
+): { ok: true; ref: NamedRef } | { ok: false; error: string } {
+  const value = raw.trim();
+  if (ISSUE_RE.test(value))
+    return { ok: true, ref: { tracker: "youtrack", id: value, repo: null, host: null } };
+  const short = /^(?:([\w.-]+(?:\/[\w.-]+)+))?#?(\d+)$/u.exec(value);
+  if (short && (short[1] === undefined || value.includes("#")))
+    return { ok: true, ref: { tracker, id: short[2], repo: short[1] ?? null, host: null } };
+  let url: URL | null = null;
+  try {
+    url = /^https?:\/\//iu.test(value) ? new URL(value) : null;
+  } catch {
+    url = null;
+  }
+  if (url) {
+    const pathname = url.pathname.replace(/\/+$/u, "");
+    const youtrack = /\/issues?\/([A-Z][A-Z0-9]*-\d+)(?:\/|$)/u.exec(pathname);
+    if (youtrack && ISSUE_RE.test(youtrack[1]))
+      return { ok: true, ref: { tracker: "youtrack", id: youtrack[1], repo: null, host: null } };
+    const gitlab = /^\/(.+?)\/-\/(?:issues|work_items)\/(\d+)$/u.exec(pathname);
+    const github = /^\/([^/]+\/[^/]+)\/issues\/(\d+)$/u.exec(pathname);
+    const found: [ForgeKind, RegExpExecArray] | null = gitlab
+      ? ["gitlab", gitlab]
+      : github
+        ? ["github", github]
+        : null;
+    if (found) {
+      const [kind, match] = found;
+      return {
+        ok: true,
+        ref: { tracker: kind, id: match[2], repo: match[1], host: url.host.toLowerCase() },
+      };
+    }
+  }
+  return {
+    ok: false,
+    error: `cannot read issue "${raw}" (use #42, owner/repo#42, IRPT-74 or an issue URL)`,
+  };
+}
+
+const issueUrl = (kind: ForgeKind, host: string, repo: string, id: string): string =>
+  `https://${host}/${repo}/${kind === "gitlab" ? "-/" : ""}issues/${id}`;
+
+/**
+ * Where a forge-tracker issue lives, its body line and its relation. The
+ * workspace's `issues.repo`/`issues.host` place a bare number when the
+ * tracker is not the PR's own repository.
+ */
+function placeRef(
+  ref: NamedRef,
+  forge: PrForge,
+  tracker: IssueTracker | null,
+  relation: "closes" | "refs",
+  youtrackBase: string | null,
+): Omit<IssueLink, "source"> | { error: string } {
+  if (ref.tracker === "youtrack") {
+    const url = youtrackBase ? `${youtrackBase.replace(/\/+$/u, "")}/issue/${ref.id}` : null;
+    return {
+      ...ref,
+      url,
+      relation: "related",
+      line: `Related to: ${url ?? ref.id}`,
+    };
+  }
+  const configured = tracker?.provider === ref.tracker;
+  const home = ref.tracker === forge.kind ? forge.host : DEFAULT_HOST[ref.tracker];
+  const host = ref.host ?? (configured ? tracker?.host : null) ?? home;
+  const repo =
+    ref.repo ??
+    (configured ? tracker?.repo : null) ??
+    (ref.tracker === forge.kind && same(host, forge.host) ? forge.repo : null);
+  if (!repo)
+    return {
+      error: `#${ref.id} is a ${ref.tracker} issue, but the PR is on ${forge.kind}: set issues.repo to the ${ref.tracker} project that holds it, or pass the issue URL`,
+    };
+  if (ref.tracker === forge.kind && same(host, forge.host)) {
+    const own = same(repo, forge.repo);
+    return {
+      tracker: ref.tracker,
+      id: ref.id,
+      repo: own ? null : repo,
+      host: null,
+      url: null,
+      relation,
+      line: `${relation === "refs" ? "Refs" : "Closes"} ${own ? "" : repo}#${ref.id}`,
+    };
+  }
+  const url = issueUrl(ref.tracker, host, repo, ref.id);
+  return {
+    tracker: ref.tracker,
+    id: ref.id,
+    repo,
+    host,
+    url,
+    relation: "related",
+    line: `Related to: ${url}`,
+  };
+}
+
+/** The workspace tracker, or null when none is configured or the config cannot resolve. */
+function trackerFor(cwd: string): IssueTracker | null {
+  const resolved = vcsConfig("resolve", cwd);
+  if (resolved.ok === false) return null;
+  return (resolved.issue_tracker as IssueTracker | null | undefined) ?? null;
+}
+
+/**
+ * The issues a PR from `branch` links and their body lines. Named issues
+ * (the flag, else the fanout slice) always link; the branch name is read
+ * only when the tracker has `link: true`, and a YouTrack id from it only
+ * when a base URL is known (unchanged from the branch-only behavior).
+ */
+export function planIssueLinks(
+  cwd: string,
+  input: {
+    issues: readonly string[];
+    refs: boolean;
+    branch: string | null;
+    forge: PrForge;
+  },
+  tracker: IssueTracker | null = trackerFor(cwd),
+): { ok: true; data: IssueLinkPlan } | { ok: false; error: string } {
+  const relation = input.refs ? "refs" : (tracker?.relation ?? "closes");
+  const youtrackBase = tracker?.baseUrl ?? youTrackBaseUrl();
+  const forgeTracker: ForgeKind =
+    tracker?.provider === "github" || tracker?.provider === "gitlab"
+      ? tracker.provider
+      : input.forge.kind;
+  const warnings = [...(tracker?.warnings ?? [])];
+  const named = input.issues.length ? input.issues : sliceIssuesFor(cwd, input.branch);
+  const source: IssueLink["source"] = input.issues.length ? "flag" : "fanout";
+  const refs: Array<{ ref: NamedRef; source: IssueLink["source"] }> = [];
+  for (const raw of named) {
+    const parsed = parseIssueRef(raw, forgeTracker);
+    if (!parsed.ok)
+      return {
+        ok: false,
+        error: source === "fanout" ? `fanout slice issue: ${parsed.error}` : parsed.error,
+      };
+    refs.push({ ref: parsed.ref, source });
+  }
+  let derived = false;
+  if (refs.length === 0 && tracker?.link && input.branch) {
+    const id =
+      tracker.provider === "youtrack"
+        ? youtrackBase
+          ? deriveYouTrackIssueFromBranch(input.branch)
+          : ""
+        : deriveGhIssueFromBranch(input.branch);
+    if (id) {
+      refs.push({
+        ref: { tracker: tracker.provider, id, repo: null, host: null },
+        source: "branch",
+      });
+      derived = true;
+    }
+  }
+  const seen = new Set<string>();
+  const links: IssueLink[] = [];
+  for (const { ref, source: from } of refs) {
+    const placed = placeRef(ref, input.forge, tracker, relation, youtrackBase);
+    if ("error" in placed) {
+      if (derived) {
+        warnings.push(`the branch issue is not linked: ${placed.error}`);
+        continue;
+      }
+      return { ok: false, error: placed.error };
+    }
+    const key = `${placed.tracker}:${placed.host ?? ""}:${placed.repo?.toLowerCase() ?? ""}#${placed.id}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    links.push({ ...placed, source: from });
+  }
+  return { ok: true, data: { links, backlink: tracker?.backlink === true, tracker, warnings } };
+}
+
+/** The body with each link's line appended once (a line already present is kept as is). */
+export function withIssueLines(
+  body: string,
+  links: ReadonlyArray<Pick<IssueLink, "line">>,
+): string {
+  const present = new Set(body.split(/\r?\n/u).map((line) => line.trim()));
+  const lines = links.map((link) => link.line).filter((line) => !present.has(line));
+  if (lines.length === 0) return body;
+  return body ? `${body}\n\n${lines.join("\n")}` : lines.join("\n");
+}
+
+/** One `pr.linked` row per link, for a PR this call opened. */
+export function recordIssueLinks(
+  cwd: string,
+  pr: { number: number; url: string; branch: string; base: string; head: string },
+  links: readonly IssueLink[],
+  context: { actor: LedgerActor; forge: ForgeKind; repo: string },
+): Array<{ issue: string; id: string } | { issue: string; error: string }> {
+  return links.map((link) => {
+    const row = appendObserved(cwd, {
+      type: "pr.linked",
+      actor: context.actor,
+      branch: pr.branch,
+      head: pr.head,
+      pr: pr.number,
+      base: pr.base,
+      url: pr.url,
+      forge: context.forge,
+      repo: context.repo,
+      tracker: link.tracker,
+      issue: link.id,
+      issueRepo: link.repo,
+      issueHost: link.host,
+      issueUrl: link.url,
+      relation: link.relation,
+      source: link.source,
+    });
+    return row.ok
+      ? { issue: label(link), id: String(row.value.id) }
+      : { issue: label(link), error: row.error };
+  });
+}
+
+/** `#42`, `owner/repo#42`, `IRPT-74`, or the URL of an issue on another forge. */
+export const label = (link: Pick<IssueLink, "tracker" | "id" | "repo" | "url">): string =>
+  link.tracker === "youtrack" ? link.id : (link.url ?? `${link.repo ?? ""}#${link.id}`);
+
+export type LinkedIssue = {
+  tracker: string;
+  issue: string;
+  repo: string | null;
+  url: string | null;
+  relation: string;
+  source: string;
+};
+
+/** The issues `pr.linked` rows record for PR `pr` of `repo` (the CLI's own rows only). */
+export function linkedIssues(
+  rows: readonly ReadRow[],
+  target: { pr: number; repo: string },
+): LinkedIssue[] {
+  const out = new Map<string, LinkedIssue>();
+  for (const row of rows) {
+    if (row.type !== "pr.linked" || row.observer !== "workit_cli" || row.pr !== target.pr) continue;
+    if (typeof row.repo !== "string" || row.repo.toLowerCase() !== target.repo.toLowerCase())
+      continue;
+    if (typeof row.issue !== "string" || typeof row.tracker !== "string") continue;
+    const repo = typeof row.issueRepo === "string" ? row.issueRepo : null;
+    const url = typeof row.issueUrl === "string" ? row.issueUrl : null;
+    out.set(`${row.tracker}:${url ?? repo ?? ""}#${row.issue}`, {
+      tracker: row.tracker,
+      issue: row.issue,
+      repo,
+      url,
+      relation:
+        typeof row.relation === "string"
+          ? row.relation
+          : row.tracker === "youtrack"
+            ? "related"
+            : "closes",
+      source: typeof row.source === "string" ? row.source : "flag",
+    });
+  }
+  return [...out.values()];
+}
+
+export type BacklinkOutcome = {
+  issue: string;
+  status: OnceOutcome["status"] | "skipped";
+  note?: string;
+};
+
+const defaultYouTrackComment = (
+  root: string,
+  issueId: string,
+  text: string,
+  marker: string,
+): Promise<OnceOutcome> =>
+  writeOnce(issueId, marker, "comments", async () => {
+    try {
+      return {
+        ok: true,
+        data: unwrap(await defaultOperations.postComment(issueId, withMarker(text, marker), root)),
+      };
+    } catch (error) {
+      return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+  });
+
+/**
+ * The forge an issue lives on: the PR's own, or another repository on the
+ * same forge host under the same verified credential. Null for another host:
+ * no account is verified there.
+ */
+function issueForge(
+  resolved: ResolvedForge,
+  link: IssueLink,
+  runner: ForgeRunner | undefined,
+): Forge | null {
+  if (link.tracker === "youtrack") return null;
+  if (link.repo === null && link.host === null) return resolved.forge;
+  const apiHost = resolved.forge.apiHost;
+  if (link.tracker !== resolved.forge.kind || !same(link.host ?? apiHost, apiHost)) return null;
+  const options = {
+    apiHost,
+    repo: link.repo ?? resolved.forge.repo,
+    runner: runner ?? resolved.runner,
+  };
+  return link.tracker === "github" ? createGitHubForge(options) : createGitLabForge(options);
+}
+
+/**
+ * The tracker backlink (`issues.backlink: true`): a comment with the PR URL
+ * on each linked issue, posted at most once: a marker naming the PR is read
+ * back first. Forge issues on the PR's host go through the workspace's
+ * verified credential; one on another forge host is skipped (no account is
+ * verified there). YouTrack goes through its API behind WORKFLOW_YT_WRITE=1,
+ * like `workit youtrack note`. A failure is reported per issue and never
+ * undoes the PR.
+ */
+export async function postBacklinks(
+  cwd: string,
+  resolved: ResolvedForge,
+  pr: { number: number; url: string },
+  links: readonly IssueLink[],
+  deps: { runner?: ForgeRunner; env?: NodeJS.ProcessEnv } = {},
+): Promise<BacklinkOutcome[]> {
+  const env = deps.env ?? process.env;
+  const noun = resolved.forge.kind === "github" ? `PR #${pr.number}` : `MR !${pr.number}`;
+  const text = `Linked from ${noun}: ${pr.url}`;
+  const out: BacklinkOutcome[] = [];
+  for (const link of links) {
+    const issue = label(link);
+    if (link.tracker === "youtrack") {
+      if (env.WORKFLOW_YT_WRITE !== "1") {
+        out.push({
+          issue,
+          status: "failed",
+          note: "YouTrack writes need WORKFLOW_YT_WRITE=1 (as for workit youtrack note)",
+        });
+        continue;
+      }
+      const marker = youTrackMarker({ operation: "pr.backlink", issueId: link.id, pr: pr.url });
+      if (!marker) {
+        out.push({
+          issue,
+          status: "failed",
+          note: "YouTrack credentials are unavailable (youtrack.json / youtrack.token)",
+        });
+        continue;
+      }
+      const outcome = await defaultYouTrackComment(cwd, link.id, text, marker);
+      out.push({
+        issue,
+        status: outcome.status,
+        ...("error" in outcome ? { note: outcome.error } : {}),
+      });
+      continue;
+    }
+    const forge = issueForge(resolved, link, deps.runner);
+    if (!forge) {
+      out.push({
+        issue,
+        status: "skipped",
+        note: `an issue on another forge host is not backlinked: no verified account for ${link.host ?? resolved.forge.apiHost}`,
+      });
+      continue;
+    }
+    const marker = `<!-- workit-backlink:${pr.url} -->`;
+    const number = Number(link.id);
+    const existing = forge.issueComments(number);
+    if (!existing.ok) {
+      out.push({ issue, status: "failed", note: existing.error });
+      continue;
+    }
+    if (existing.data.some((body) => body.includes(marker))) {
+      out.push({ issue, status: "already_done" });
+      continue;
+    }
+    const posted = forge.commentIssue(number, withMarker(text, marker));
+    out.push(
+      posted.ok ? { issue, status: "done" } : { issue, status: "failed", note: posted.error },
+    );
+  }
+  return out;
+}

package/src/forge/pr-body.ts

@@ -24,7 +24,7 @@ export function parseGhIssue(value: string): string {
 // skipped — a complete date anywhere in a segment (release-2024-01-15,
 // v2-2024-01-15-fix) — so no date digit ever closes an issue. Deliberate
 // numeric issue branches (feature/42-title, feature/2024-fix) keep linking.
-function deriveGhIssueFromBranch(branch: string): string {
+export function deriveGhIssueFromBranch(branch: string): string {
   for (const segment of branch.split("/")) {
     if (/^\d{4}-\d/.test(segment)) continue; // year-first date-like segment (incl. year-month)
     if (/\d{4}-\d{1,2}-\d{1,2}/.test(segment)) continue; // complete year-first date anywhere
@@ -35,6 +35,11 @@ function deriveGhIssueFromBranch(branch: string): string {
   return "";
 }
 
+/** A YouTrack id in the branch (feature/IRPT-740-x); anchored, 3+ digits so POSTGRES-16 or HTTP-3 never link. */
+export function deriveYouTrackIssueFromBranch(branch: string): string {
+  return /(?:^|\/|-)([A-Z]{2,}-\d{3,})\b/.exec(branch)?.[1] ?? "";
+}
+
 export function buildBody(
   body: string,
   branch: string,
@@ -48,12 +53,7 @@ export function buildBody(
 ): string {
   let line: string | null = null;
   if (linkIssues) {
-    let issue = ytIssue;
-    if (!issue && branch) {
-      // anchored prefix + \b boundary, 3+ digits so version-like tokens (POSTGRES-16, HTTP-3) never link
-      const m = /(?:^|\/|-)([A-Z]{2,}-\d{3,})\b/.exec(branch);
-      if (m) issue = m[1];
-    }
+    const issue = ytIssue || deriveYouTrackIssueFromBranch(branch);
     if (issue && baseUrl) line = `Related to: ${baseUrl.replace(/\/+$/, "")}/issue/${issue}`;
   } else if (ghLinkOnPr) {
     let issue = parseGhIssue(ghIssue);

package/src/forge/resolve.ts

@@ -53,6 +53,8 @@ export type ResolvedForge = {
   baseRemote: string;
   /** Absolute deadline (ms, `now()` clock) every API call is clamped to; null = none. */
   limits: { deadline: number | null };
+  /** The workspace credential's runner, clamped to `limits` (another repo on the same host). */
+  runner: ForgeRunner;
 };
 
 export type ResolveOptions = {
@@ -352,6 +354,7 @@ export function resolveForge(
     fork: baseRepo !== headRepo,
     baseRemote,
     limits,
+    runner,
   });
 }
 

package/src/forge/types.ts

@@ -217,4 +217,8 @@ export interface Forge {
   findRelease(tag: string): ForgeResult<ForgeRelease | null>;
   /** Publish a release on an existing tag (never creates the tag). */
   createRelease(input: CreateReleaseInput): ForgeResult<ForgeRelease>;
+  /** Bodies of the first page of comments on issue `n` of the base repository. */
+  issueComments(n: number): ForgeResult<string[]>;
+  /** Comment on issue `n` of the base repository (the PR backlink). */
+  commentIssue(n: number, body: string): ForgeResult<void>;
 }

package/src/host-session.ts

@@ -196,7 +196,9 @@ const tokenHash = (token: string): string => createHash("sha256").update(token).
  * Null when nothing was issued: already issued, or the write failed (fails open).
  */
 export function recordIssuedSession(cwd: string, lead: string, issued: string): string | null {
-  const token = randomBytes(18).toString("base64url");
+  // Hex, never base64url: a token that starts with "-" (1 in 64) breaks the
+  // `--token <token>` the hook prints, because the CLI parses it as a flag.
+  const token = randomBytes(18).toString("hex");
   try {
     migrateRepoIssued(cwd);
     const own = hash(issued);

package/src/ledger.ts

@@ -89,7 +89,12 @@ export type VerdictSurface = (typeof VERDICT_SURFACES)[number];
 export type Observer = "agent_asserted" | "workit_cli";
 
 /** Row types written by the CLI's own PR verbs (S10/S11); the only PR→branch source. */
-export const PR_ROW_TYPES: ReadonlySet<string> = new Set(["pr.created", "pr.status", "pr.merged"]);
+export const PR_ROW_TYPES: ReadonlySet<string> = new Set([
+  "pr.created",
+  "pr.status",
+  "pr.merged",
+  "pr.linked",
+]);
 
 /** Who wrote a row. Unverified: the environment says so (D18). */
 export type LedgerActor = { host: string; session: string | null; agentId: string | null };
@@ -2085,6 +2090,9 @@ export function summarizeRow(row: ReadRow): RowSummary {
     case "pr.merged":
       summary = `#${row.pr ?? "?"} ${text("method")} at ${(row.head ?? "?").slice(0, 12)}${text("mergeSha") ? ` -> ${text("mergeSha").slice(0, 12)}` : ""}`;
       break;
+    case "pr.linked":
+      summary = `#${row.pr ?? "?"} links ${text("tracker")} ${text("issueRepo") ? `${text("issueRepo")}` : ""}${text("tracker") === "youtrack" ? "" : "#"}${text("issue")} (${text("relation") || "closes"}, from ${text("source") || "?"})`;
+      break;
     case "merge.unverified":
       summary = `#${row.pr ?? "?"} unverified merge requested at ${(row.head ?? "?").slice(0, 12)} (reason: ${text("reason")})`;
       break;