@codyswann/lisa 4.67.0 → 4.68.0

package/all/copy-overwrite/scripts/lisa-self-update.mjs

@@ -27,7 +27,15 @@
  *    auto-merge with a merge method the repository allows.
  *
  * The pull request goes through every gate a human change does. Nothing here
- * merges, approves, or skips a check.
+ * merges, approves, or skips a check. A project that tracks work in GitHub
+ * Issues gets a fresh work item per update (trailer, PR line and backlink), so
+ * a traceability gate is satisfied rather than bypassed; elsewhere,
+ * `LISA_UPDATE_WORK_ITEM` names one.
+ *
+ * In Lisa's own repository (self mode, CodySwannGT/lisa#4331) the same flow
+ * moves Lisa's dependency on its published self after each release: no template
+ * apply, a caret floor, and a loop guard so a self-bump never chases the release
+ * its own merge cuts.
  * @module scripts/lisa-self-update
  */
 import { execFile } from "node:child_process";
@@ -41,6 +49,9 @@ export const LISA_PACKAGE = "@codyswann/lisa";
 /** Branch prefix every update pull request uses; supersession keys on it. */
 export const BRANCH_PREFIX = "lisa/update-";
 
+/** The manifest every package-manager decision reads. */
+const MANIFEST = "package.json";
+
 /** Flags this script accepts. Anything else is refused, never ignored. */
 const KNOWN_FLAGS = new Set(["--dry-run", "--help"]);
 
@@ -89,6 +100,63 @@ export function declaresLisa(manifest) {
   );
 }
 
+/**
+ * Whether this manifest IS Lisa — the repository that publishes the package.
+ *
+ * Lisa depends on a published copy of itself, and that pin is the one no other
+ * automation corrects: `lisa apply` deliberately skips the self-pin phase on
+ * its own manifest (CodySwannGT/lisa#3768). Self mode updates it the same way
+ * a host is updated, minus the template apply Lisa never runs on itself.
+ * @param {Record<string, any> | null} manifest Parsed package.json.
+ * @returns {boolean} True for Lisa's own repository.
+ */
+export function isSelfManifest(manifest) {
+  return manifest?.name === LISA_PACKAGE;
+}
+
+/** Subject of the commit a self-update makes; the loop guard keys on it. */
+export function selfBumpSubject(version) {
+  return `chore(deps): update ${LISA_PACKAGE} self-dependency to ${version}`;
+}
+
+/** A release-bot commit, in either form Lisa's release workflow has emitted. */
+const RELEASE_SUBJECT = /^chore\(release\): \S+ \[skip ci\](?: \[skip-cd\])?$/u;
+
+/** A self-update commit made by {@link selfBumpSubject}. */
+const SELF_BUMP_SUBJECT =
+  /^chore\(deps\): update @codyswann\/lisa self-dependency to \S+$/u;
+
+/**
+ * The loop guard. Every merge to Lisa's `main` cuts a release, so merging a
+ * self-bump publishes a NEWER version than the one it pinned — and an updater
+ * that chased it would open a bump, merge it, release, and bump again forever.
+ * When everything a release added since the pinned one is release commits and
+ * self-bumps, the two differ only by the pin itself, and the pin is current.
+ * @param {readonly string[]} subjects Non-merge commit subjects between the tags.
+ * @returns {boolean} True when the newer release carries nothing else.
+ */
+export function onlySelfBumps(subjects) {
+  return subjects.every(
+    subject => RELEASE_SUBJECT.test(subject) || SELF_BUMP_SUBJECT.test(subject)
+  );
+}
+
+/**
+ * The version Lisa should pin itself to. Its own `package.json` names the
+ * release `main` just cut; once npm serves that exact version it is the
+ * target, which beats waiting minutes for the cached `latest` pointer to move
+ * (CodySwannGT/lisa#3685). Until then, npm latest.
+ * @param {string | undefined} own Version in Lisa's own manifest.
+ * @param {boolean} ownPublished Whether npm serves that exact version.
+ * @param {string | null} npmLatest npm's `latest`.
+ * @returns {string | null} Target version.
+ */
+export function chooseSelfTarget(own, ownPublished, npmLatest) {
+  if (!own || !ownPublished) return npmLatest;
+  if (!npmLatest) return own;
+  return isOlder(own, npmLatest) ? npmLatest : own;
+}
+
 /**
  * Choose the package manager. `engines` is authoritative: a value of
  * `please-use-<pm>` names the only allowed manager, and any manager whose own
@@ -118,10 +186,12 @@ export function choosePackageManager(engines, lockfiles) {
  * The commands that install the current lockfile and bump Lisa.
  * @param {"bun" | "npm" | "pnpm" | "yarn"} manager Package manager.
  * @param {string} version Target version.
+ * @param {string} [range] Range operator to write, e.g. `^` for Lisa's own
+ *   caret floor; a host gets the exact version its manager records.
  * @returns {{install: string[], bump: string[]}} argv arrays.
  */
-export function packageCommands(manager, version) {
-  const spec = `${LISA_PACKAGE}@${version}`;
+export function packageCommands(manager, version, range = "") {
+  const spec = `${LISA_PACKAGE}@${range}${version}`;
   const table = {
     bun: {
       install: ["bun", "install", "--frozen-lockfile"],
@@ -269,7 +339,7 @@ export function supersededPullRequests(open, branch) {
  * Commit message, with the optional standing work-item trailer.
  * @param {string} subject Conventional subject.
  * @param {string} body Paragraph explaining the change.
- * @param {string | undefined} workItem `LISA_UPDATE_WORK_ITEM`, if set.
+ * @param {string | undefined} workItem The update's work item, if any.
  * @returns {string} Full message.
  */
 export function commitMessage(subject, body, workItem) {
@@ -280,26 +350,88 @@ export function commitMessage(subject, body, workItem) {
 /**
  * Pull request body, written for a non-technical reader.
  * @param {{from: string, to: string}} plan The update.
- * @param {string | undefined} workItem Standing work item, if configured.
+ * @param {string | undefined} workItem The update's work item, if any.
+ * @param {boolean} [selfMode] Whether this is Lisa updating itself.
  * @returns {string} Markdown body.
  */
-export function pullRequestBody(plan, workItem) {
+export function pullRequestBody(plan, workItem, selfMode = false) {
+  const what = selfMode
+    ? `This updates the copy of Lisa that Lisa itself is built and checked with, from **${plan.from}** to **${plan.to}**, so its own checks run the guardrails it ships.`
+    : `This updates Lisa, the project's engineering guardrails, from **${plan.from}** to **${plan.to}**.`;
+  const contents = selfMode
+    ? "It was opened automatically after a release. It contains one commit, the dependency bump; Lisa does not apply its own templates to itself."
+    : "It was opened automatically by the scheduled Lisa Update workflow. It contains two commits: the dependency bump, and the template changes Lisa applies for the new version.";
   const lines = [
-    `This updates Lisa, the project's engineering guardrails, from **${plan.from}** to **${plan.to}**.`,
+    what,
     "",
-    "It was opened automatically by the scheduled Lisa Update workflow. It contains two commits: the dependency bump, and the template changes Lisa applies for the new version. It goes through every check a normal change does and merges itself only when they all pass.",
+    `${contents} It goes through every check a normal change does and merges itself only when they all pass.`,
     "",
     `Release notes: https://github.com/CodySwannGT/lisa/releases/tag/v${plan.to}`,
   ];
-  if (!workItem) {
+  if (workItem) {
+    lines.push("", `Work-Item: ${workItem}`);
+  } else {
     lines.push(
       "",
-      'If this project requires every change to reference a work item, set the repository variable `LISA_UPDATE_WORK_ITEM` to a standing work item (for example a "Keep Lisa current" ticket) so future update pull requests carry it.'
+      "If this project requires every change to reference a work item and does not track work in GitHub Issues, set the repository variable `LISA_UPDATE_WORK_ITEM` to an open work item for the next update. Projects that track work in GitHub Issues get a fresh work item for each update automatically."
     );
   }
   return `${lines.join("\n")}\n`;
 }
 
+/**
+ * Labels for a per-update work item, from the project's own lifecycle config.
+ *
+ * A fresh item per update, never a standing one: merging into the production
+ * branch completes the item it names, so a standing item is closed by the first
+ * update and refuses every later one.
+ * @param {Record<string, any> | null} config Parsed `.lisa.config.json`.
+ * @returns {{ready: string, claimed: string, repo: string} | null} Labels, or
+ *   null when the project does not track work in GitHub Issues.
+ */
+export function workItemLabels(config) {
+  if (config?.tracker !== "github" || !config.github?.repo) return null;
+  const build = config.github.labels?.build ?? {};
+  return {
+    ready: build.ready ?? "status:ready",
+    claimed: build.claimed ?? "status:in-progress",
+    repo: `repo:${config.github.repo}`,
+  };
+}
+
+/**
+ * Body of a per-update work item, written for a non-technical reader.
+ * @param {{from: string, to: string}} plan The update.
+ * @param {boolean} selfMode Whether this is Lisa updating itself.
+ * @returns {string} Markdown body.
+ */
+export function workItemBody(plan, selfMode) {
+  const subject = selfMode
+    ? "the copy of Lisa this repository builds with"
+    : "Lisa";
+  return [
+    "Filed by: lisa-self-update (automated).",
+    "",
+    "## Context / Business Value",
+    "",
+    `Lisa ${plan.to} is published and this repository uses ${plan.from}. Keeping ${subject} current means the newest guardrails and fixes apply here.`,
+    "",
+    "## Acceptance Criteria",
+    "",
+    "```gherkin",
+    "Scenario: the update lands",
+    `  Given ${subject} is ${plan.from}`,
+    "  When the update pull request merges after every required check passes",
+    `  Then ${subject} is ${plan.to}`,
+    "```",
+    "",
+    "## Target Backend Environment",
+    "",
+    "None — no runtime behavior change: config-only",
+    "",
+  ].join("\n");
+}
+
 /**
  * Proof the full apply ran for the target version.
  * @param {Record<string, any> | null} receipt Parsed `.lisa/apply-receipt.json`.
@@ -330,6 +462,51 @@ function readJson(file) {
   }
 }
 
+/** Variables that can carry the GitHub credential; never inherited by default. */
+const TOKEN_VARS = ["LISA_UPDATE_TOKEN", "GH_TOKEN", "GITHUB_TOKEN"];
+
+/**
+ * An environment with every GitHub credential removed.
+ * @param {NodeJS.ProcessEnv} env Source environment.
+ * @returns {NodeJS.ProcessEnv} A copy without credentials.
+ */
+export function withoutToken(env) {
+  return Object.fromEntries(
+    Object.entries(env).filter(([key]) => !TOKEN_VARS.includes(key))
+  );
+}
+
+/**
+ * The environment one command runs with: the credential reaches only the
+ * commands that talk to GitHub. Installs, the bump and the apply run without
+ * it, because they execute dependency lifecycle scripts, and a compromised
+ * release must not be able to read a token that can push and merge. `gh` gets
+ * `GH_TOKEN`; git fetch and push get an auth header through git's environment
+ * config (never argv, which other processes can read); the work-item backlink
+ * shells out to `gh`.
+ * @param {readonly string[]} argv Command and arguments.
+ * @param {NodeJS.ProcessEnv | undefined} env Environment the caller supplied.
+ * @param {string | undefined} token GitHub credential, if any.
+ * @returns {NodeJS.ProcessEnv} The environment to spawn with.
+ */
+export function commandEnv(argv, env, token) {
+  const base = withoutToken(env ?? process.env);
+  if (!token) return base;
+  const talksToGithub =
+    argv[0] === "gh" || (argv[0] === "node" && argv.includes("backlink"));
+  if (talksToGithub) return { ...base, GH_TOKEN: token };
+  if (argv[0] === "git" && (argv[1] === "fetch" || argv[1] === "push")) {
+    const basic = Buffer.from(`x-access-token:${token}`).toString("base64");
+    return {
+      ...base,
+      GIT_CONFIG_COUNT: "1",
+      GIT_CONFIG_KEY_0: "http.https://github.com/.extraheader",
+      GIT_CONFIG_VALUE_0: `AUTHORIZATION: basic ${basic}`,
+    };
+  }
+  return base;
+}
+
 /**
  * Run a command, inheriting nothing but the environment given.
  * @param {string[]} argv Command and arguments.
@@ -343,7 +520,7 @@ export function runCommand(argv, options) {
       argv.slice(1),
       {
         cwd: options.cwd,
-        env: options.env ?? process.env,
+        env: options.env ?? withoutToken(process.env),
         maxBuffer: 64 * 1024 * 1024,
       },
       (error, stdout, stderr) => {
@@ -367,18 +544,31 @@ export function runCommand(argv, options) {
  * @returns {Promise<object>} Facts.
  */
 async function gatherFacts(ctx) {
-  const manifest = readJson(path.join(ctx.root, "package.json"));
-  const declares = declaresLisa(manifest);
-  if (!declares) return { declares, manifest };
+  const manifest = readJson(path.join(ctx.root, MANIFEST));
+  const selfMode = isSelfManifest(manifest);
+  const declares = selfMode || declaresLisa(manifest);
+  if (!declares) return { declares, manifest, selfMode };
   const manager = choosePackageManager(
     manifest.engines,
     LOCKFILES.map(([file]) => file).filter(file =>
       existsSync(path.join(ctx.root, file))
     )
   );
-  const latest = await ctx
-    .run(["npm", "view", LISA_PACKAGE, "version"], { cwd: ctx.root })
-    .catch(() => null);
+  // probe-direction: neutral — an unanswered registry query yields no target,
+  // and planUpdate turns that into a reported skip; nothing is gated on it.
+  const view = spec =>
+    ctx
+      .run(["npm", "view", spec, "version"], { cwd: ctx.root })
+      .catch(() => null);
+  const npmLatest = await view(LISA_PACKAGE);
+  const latest = selfMode
+    ? chooseSelfTarget(
+        manifest.version,
+        (await view(`${LISA_PACKAGE}@${manifest.version}`)) ===
+          manifest.version,
+        npmLatest
+      )
+    : npmLatest;
   if (!ctx.dryRun) {
     ctx.log(`Installing the current lockfile with ${manager}…`);
     await ctx.run(packageCommands(manager, latest ?? "latest").install, {
@@ -387,9 +577,189 @@ async function gatherFacts(ctx) {
   }
   const installed =
     readJson(
-      path.join(ctx.root, "node_modules", "@codyswann", "lisa", "package.json")
+      path.join(ctx.root, "node_modules", "@codyswann", "lisa", MANIFEST)
     )?.version ?? null;
-  return { declares, manifest, manager, latest, installed };
+  return { declares, manifest, manager, latest, installed, selfMode };
+}
+
+/**
+ * Apply the loop guard to a self-update plan (see {@link onlySelfBumps}).
+ *
+ * A missing tag is an error, never a pass: an unreadable range cannot show the
+ * newer release is only a self-bump, and treating it as one would stop Lisa
+ * updating itself with nothing saying so.
+ * @param {object} ctx Context.
+ * @param {{from: string, to: string}} plan The planned update.
+ * @returns {Promise<boolean>} True when the pin is effectively current.
+ */
+async function pinIsEffectivelyCurrent(ctx, plan) {
+  await ctx.run(["git", "fetch", "--tags", "--quiet", "origin"], {
+    cwd: ctx.root,
+  });
+  const log = await ctx.run(
+    ["git", "log", "--no-merges", "--format=%s", `v${plan.from}..v${plan.to}`],
+    { cwd: ctx.root }
+  );
+  return onlySelfBumps(log.split("\n").filter(Boolean));
+}
+
+/**
+ * Create a fresh work item for this update when the project tracks work in
+ * GitHub Issues and none was supplied. Filed into the ready role, then claimed,
+ * as every work item is. Jira and Linear projects use `LISA_UPDATE_WORK_ITEM`.
+ * @param {object} ctx Context.
+ * @param {{from: string, to: string}} plan The update.
+ * @param {boolean} selfMode Whether this is Lisa updating itself.
+ * @returns {Promise<string | undefined>} `owner/repo#N`, or undefined.
+ */
+async function resolveWorkItem(ctx, plan, selfMode) {
+  if (ctx.workItem) return ctx.workItem;
+  const labels = workItemLabels(
+    readJson(path.join(ctx.root, ".lisa.config.json"))
+  );
+  if (!labels) return undefined;
+  const title = selfMode
+    ? `Update Lisa's own self-dependency to ${plan.to}`
+    : `Update Lisa to ${plan.to}`;
+  const url = await ctx.run(
+    [
+      "gh",
+      "issue",
+      "create",
+      "--repo",
+      ctx.repo,
+      "--title",
+      title,
+      "--body",
+      workItemBody(plan, selfMode),
+      "--label",
+      "type:Task",
+      "--label",
+      labels.repo,
+      "--label",
+      labels.ready,
+    ],
+    { cwd: ctx.root }
+  );
+  const number = /\/issues\/(\d+)$/u.exec(url)?.[1];
+  if (!number)
+    throw new Error(
+      `lisa-self-update: could not read the work item created at ${url}.`
+    );
+  await ctx.run(
+    [
+      "gh",
+      "issue",
+      "edit",
+      number,
+      "--repo",
+      ctx.repo,
+      "--remove-label",
+      labels.ready,
+      "--add-label",
+      labels.claimed,
+    ],
+    { cwd: ctx.root }
+  );
+  ctx.log(`Filed work item ${ctx.repo}#${number} for this update.`);
+  return `${ctx.repo}#${number}`;
+}
+
+/**
+ * Post the managed `[lisa-pr-link]` backlink from the work item to the PR,
+ * through the project's own work-item tool so its format never drifts.
+ * @param {object} ctx Context.
+ * @param {string} url Pull request URL.
+ * @returns {Promise<void>} Resolves once the backlink is posted.
+ */
+async function backlink(ctx, url) {
+  const tool = [
+    "scripts/lisa-work-item.mjs",
+    "all/copy-overwrite/scripts/lisa-work-item.mjs",
+  ].find(candidate => existsSync(path.join(ctx.root, candidate)));
+  if (!tool) {
+    ctx.log(
+      "No lisa-work-item.mjs here, so the work item was not backlinked to the pull request."
+    );
+    return;
+  }
+  await ctx.run(
+    ["node", tool, "backlink", "--ref", ctx.workItem, "--pr-url", url],
+    { cwd: ctx.root }
+  );
+}
+
+/**
+ * The open pull request already carrying this update, if any. Checked before
+ * anything is filed or built, so a re-run reuses it instead of duplicating it.
+ * @param {object} ctx Context.
+ * @param {string} branch Update branch.
+ * @returns {Promise<string>} Its URL, or "".
+ */
+function openUpdatePullRequest(ctx, branch) {
+  return ctx.run(
+    [
+      "gh",
+      "pr",
+      "list",
+      "--repo",
+      ctx.repo,
+      "--head",
+      branch,
+      "--state",
+      "open",
+      "--json",
+      "url",
+      "--jq",
+      '.[0].url // ""',
+    ],
+    { cwd: ctx.root }
+  );
+}
+
+/**
+ * Self mode's single commit: bump the caret floor, prove the install, commit.
+ * Lisa never applies its own templates to itself, so there is no apply step.
+ * @param {object} ctx Context.
+ * @param {{from: string, to: string}} plan The update.
+ * @param {string} manager Package manager.
+ * @returns {Promise<void>} Resolves when the commit exists.
+ */
+async function buildSelfBump(ctx, plan, manager) {
+  const { root, run, workItem } = ctx;
+  await run(packageCommands(manager, plan.to, "^").bump, { cwd: root });
+  const installed = readJson(
+    path.join(root, "node_modules", "@codyswann", "lisa", MANIFEST)
+  )?.version;
+  if (installed !== plan.to) {
+    throw new Error(
+      `lisa-self-update: the bump installed ${installed ?? "nothing"}, not ${plan.to}.`
+    );
+  }
+  await run(
+    [
+      "git",
+      "add",
+      MANIFEST,
+      ...LOCKFILES.map(([file]) => file).filter(file =>
+        existsSync(path.join(root, file))
+      ),
+    ],
+    { cwd: root }
+  );
+  await run(
+    [
+      "git",
+      "commit",
+      "-m",
+      commitMessage(
+        selfBumpSubject(plan.to),
+        `Moves the copy of Lisa this repository builds and checks with from ${plan.from} to ${plan.to}.`,
+        workItem
+      ),
+    ],
+    { cwd: root }
+  );
 }
 
 /**
@@ -397,11 +767,16 @@ async function gatherFacts(ctx) {
  * @param {object} ctx Context.
  * @param {{from: string, to: string, branch: string}} plan The update.
  * @param {string} manager Package manager.
- * @returns {Promise<void>} Resolves when both commits exist.
+ * @param {boolean} [selfMode] Whether this is Lisa updating itself.
+ * @returns {Promise<void>} Resolves when the commits exist.
  */
-async function buildBranch(ctx, plan, manager) {
+async function buildBranch(ctx, plan, manager, selfMode = false) {
   const { root, run, workItem } = ctx;
   await run(["git", "checkout", "-B", plan.branch], { cwd: root });
+  if (selfMode) {
+    await buildSelfBump(ctx, plan, manager);
+    return;
+  }
   await run(packageCommands(manager, plan.to).bump, { cwd: root });
   await run(["git", "add", "-A"], { cwd: root });
   await run(
@@ -454,49 +829,51 @@ async function buildBranch(ctx, plan, manager) {
  * @param {string} base Base branch.
  * @returns {Promise<string>} The pull request URL.
  */
-async function publish(ctx, plan, base) {
-  const { root, run, repo, log, workItem } = ctx;
+async function publish(ctx, plan, base, selfMode = false) {
+  const { root, run, repo, workItem } = ctx;
   await run(["git", "push", "--force", "-u", "origin", plan.branch], {
     cwd: root,
   });
-  const existing = await run(
+  const title = selfMode
+    ? selfBumpSubject(plan.to)
+    : `chore(deps): update Lisa to ${plan.to}`;
+  const url = await run(
     [
       "gh",
       "pr",
-      "list",
+      "create",
       "--repo",
       repo,
+      "--base",
+      base,
       "--head",
       plan.branch,
-      "--state",
-      "open",
-      "--json",
-      "url",
-      "--jq",
-      '.[0].url // ""',
+      "--title",
+      title,
+      "--body",
+      pullRequestBody(plan, workItem, selfMode),
     ],
     { cwd: root }
   );
-  const url =
-    existing ||
-    (await run(
-      [
-        "gh",
-        "pr",
-        "create",
-        "--repo",
-        repo,
-        "--base",
-        base,
-        "--head",
-        plan.branch,
-        "--title",
-        `chore(deps): update Lisa to ${plan.to}`,
-        "--body",
-        pullRequestBody(plan, workItem),
-      ],
-      { cwd: root }
-    ));
+  if (workItem) await backlink(ctx, url);
+  await closeSupersededPullRequests(ctx, plan, url);
+  await armAutoMerge(ctx, url);
+  return url;
+}
+
+/**
+ * Close every other open update pull request as superseded by `url`.
+ *
+ * Runs for a newly opened AND a reused pull request: a run that stopped after
+ * `gh pr create` would otherwise leave older update PRs open forever, because
+ * every later run takes the reuse path.
+ * @param {object} ctx Context.
+ * @param {{to: string, branch: string}} plan The update.
+ * @param {string} url The pull request carrying this update.
+ * @returns {Promise<void>} Resolves once every superseded PR is closed.
+ */
+async function closeSupersededPullRequests(ctx, plan, url) {
+  const { root, run, repo, log } = ctx;
   const open = JSON.parse(
     await run(
       [
@@ -532,21 +909,31 @@ async function publish(ctx, plan, base) {
     );
     log(`Closed superseded pull request #${number}.`);
   }
+}
+
+/**
+ * Arm auto-merge with the first method the repository allows, or say why not.
+ * @param {object} ctx Context.
+ * @param {string} url Pull request URL.
+ * @returns {Promise<void>} Resolves once armed or reported.
+ */
+async function armAutoMerge(ctx, url) {
   const settings = JSON.parse(
-    await run(["gh", "api", `repos/${repo}`], { cwd: root })
+    await ctx.run(["gh", "api", `repos/${ctx.repo}`], { cwd: ctx.root })
   );
   const flag = chooseMergeFlag(settings);
   if (flag) {
-    await run(["gh", "pr", "merge", url, "--auto", flag], { cwd: root });
-    log(
+    await ctx.run(["gh", "pr", "merge", url, "--auto", flag], {
+      cwd: ctx.root,
+    });
+    ctx.log(
       `Auto-merge armed (${flag}); the pull request merges when its checks pass.`
     );
   } else {
-    log(
+    ctx.log(
       "Auto-merge is not enabled for this repository, so the pull request stays open for someone to merge once its checks pass."
     );
   }
-  return url;
 }
 
 /**
@@ -564,12 +951,16 @@ async function checkoutBase(ctx, base) {
 
 /**
  * Run the whole flow.
- * @param {{root: string, repo: string, dryRun: boolean, workItem?: string, run?: typeof runCommand, log?: (line: string) => void, defaultBranch?: string}} options Options.
+ * @param {{root: string, repo: string, dryRun: boolean, workItem?: string, token?: string, run?: typeof runCommand, log?: (line: string) => void, defaultBranch?: string}} options Options.
  * @returns {Promise<number>} Exit code.
  */
 export async function main(options) {
   const ctx = {
-    run: runCommand,
+    run: (argv, opts) =>
+      runCommand(argv, {
+        ...opts,
+        env: commandEnv(argv, opts?.env, options.token),
+      }),
     log: line => console.log(line),
     ...options,
   };
@@ -584,17 +975,34 @@ export async function main(options) {
     ctx.log(`lisa-self-update: nothing to do — ${plan.reason}`);
     return 0;
   }
+  if (facts.selfMode && (await pinIsEffectivelyCurrent(ctx, plan))) {
+    ctx.log(
+      `lisa-self-update: nothing to do — the self-dependency is effectively current: ${plan.to} differs from ${plan.from} only by release and self-bump commits.`
+    );
+    return 0;
+  }
   ctx.log(
     `lisa-self-update: Lisa ${plan.from} → ${plan.to}; branch ${plan.branch} into ${base}.`
   );
   if (ctx.dryRun) {
+    const steps = facts.selfMode
+      ? "bump the self-dependency (no template apply)"
+      : "run the full apply";
     ctx.log(
-      `Dry run: would bump with ${facts.manager}, run the full apply, commit, push ${plan.branch}, open a pull request into ${base}, close older ${BRANCH_PREFIX}* pull requests and arm auto-merge.`
+      `Dry run: would bump with ${facts.manager}, ${steps}, commit, push ${plan.branch}, open a pull request into ${base}, close older ${BRANCH_PREFIX}* pull requests and arm auto-merge.`
     );
     return 0;
   }
-  await buildBranch(ctx, plan, facts.manager);
-  const url = await publish(ctx, plan, base);
+  const existing = await openUpdatePullRequest(ctx, plan.branch);
+  if (existing) {
+    ctx.log(`lisa-self-update: ${existing} already carries this update.`);
+    await closeSupersededPullRequests(ctx, plan, existing);
+    await armAutoMerge(ctx, existing);
+    return 0;
+  }
+  ctx.workItem = await resolveWorkItem(ctx, plan, facts.selfMode);
+  await buildBranch(ctx, plan, facts.manager, facts.selfMode);
+  const url = await publish(ctx, plan, base, facts.selfMode);
   ctx.log(`lisa-self-update: update pull request ${url}`);
   return 0;
 }
@@ -620,6 +1028,9 @@ export async function runCli() {
       repo,
       dryRun: flags.dryRun,
       workItem: process.env.LISA_UPDATE_WORK_ITEM || undefined,
+      // The workflow passes LISA_UPDATE_TOKEN; a hand run may rely on GH_TOKEN,
+      // or on neither, in which case gh and git use their own stored login.
+      token: process.env.LISA_UPDATE_TOKEN || process.env.GH_TOKEN || undefined,
       defaultBranch: process.env.LISA_DEFAULT_BRANCH || undefined,
     });
   } catch (error) {