@alecsibilia/luca 14.0.0-alpha.10 → 14.0.0-alpha.11

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @alecsibilia/luca
 
+## 14.0.0-alpha.11
+
+No changes in this release.
+
 ## 14.0.0-alpha.10
 
 No changes in this release.

package/README.md

@@ -49,7 +49,7 @@ After a run, type `/luca-retro` the same way to look back on it: it reads the ru
 | `luca init` | Sets up this computer, once (safe to run again): MuninnDB and its Claude Code entry, the board in Paseo with its engine and Bun paths, the planning skills (`to-spec`, `to-tickets`, `setup-matt-pocock-skills`, `grilling`, `domain-modeling`), and Luca's own `/luca-unstick` and `/luca-retro` skills. It asks before turning on Paseo's plugins, and leaves skills you already have alone (it only replaces its own two). `--skip-skills` skips the planning skills. Inside a git repo, it then runs `luca setup` for that repo. |
 | `luca setup` | Gets the repo in this folder ready: the labels a run needs (and the `release:*` labels when the repo uses changesets), `.luca/config.json` (a new one gets the repo's GitHub name as its vault; an existing vault is kept), and a check of GitHub sub-issues and dependencies. `--base <branch>` names the base branch. |
 | `luca doctor` | Checks this computer, this repo when you're in one, and what v13 left behind. Each problem comes with its exact fix. `luca doctor --fix` fixes what's safe without asking: it never deletes (v13 files go to a dated backup folder) and never commits, and it lists the repo files to commit. |
-| `luca upgrade` | Moves to the newest Luca on your channel: `alpha` stays on `alpha`, and it never goes back to v13. It refuses while any run is going (stuck runs and limit waits count) and lists them. A run that crashed, with no engine running it, doesn't stop it: upgrade says how to resume it on the new version. Then it reloads the board, copies the new `/luca-unstick` and `/luca-retro` skills, and says when to run `/reload-skills`. |
+| `luca upgrade` | Moves to the newest Luca on your channel: `alpha` stays on `alpha`, and it never goes back to v13. It refuses while any run is going (stuck runs and limit waits count) and lists them. A run that crashed, with no engine running it, doesn't stop it: upgrade says how to resume it on the new version. Then the version it just installed finishes the job with its own code: it reloads the board, copies its skills (every one it ships, new ones included), and says when to run `/reload-skills`. |
 | `luca upgrade --to <version>` | Installs that exact version, an older one too, to go back when a version breaks. |
 
 `init`, `setup`, and `upgrade` end with their part of `luca doctor`'s checks.
@@ -92,7 +92,7 @@ This is the one package that goes to npm. It's TypeScript source with no build a
 | ------ | ---------- |
 | `engine/` | The engine's source, from [`packages/engine/src`](../engine/src). Both bins point into it. |
 | `board/` | The board plugin's folder, from [`packages/board`](../board): `paseo-plugin.json`, its entry points, its client, server, and shared code, and its own `package.json`, so Paseo can install it as a folder source. |
-| `skills/` | Luca's own Claude Code skills, `luca-unstick` and `luca-retro`, from [`packages/engine/skills`](../engine/skills). `luca init` and `luca upgrade` copy them to `~/.claude/skills`. |
+| `skills/` | Luca's own Claude Code skills, `luca-unstick` and `luca-retro`, from [`packages/engine/skills`](../engine/skills). `luca init` and `luca upgrade` copy every folder in it with a `SKILL.md` to `~/.claude/skills`. |
 | `LICENSE` | The repo's license. |
 
 Test files and test helpers stay out. The engine and the board stay private workspace packages, and this package lists every package they import at runtime as its own dependency.

package/board/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@luca/board",
-    "version": "14.0.0-alpha.10",
+    "version": "14.0.0-alpha.11",
     "private": true,
     "type": "module"
 }

package/board/server/luca-version.ts

@@ -1,2 +1,2 @@
 /** The Luca version of this board, stamped when the package was packed. */
-export const LUCA_VERSION: string = "14.0.0-alpha.10"
+export const LUCA_VERSION: string = "14.0.0-alpha.11"

package/engine/cli/computer-adapters-real.ts

@@ -400,7 +400,7 @@ const PackageJsonSchema = z.looseObject({
 })
 
 /** The package a file belongs to: the nearest package.json with a name. */
-const packageOf = async (
+export const packageOf = async (
     file: string
 ): Promise<{ name: string; version: string | null } | null> => {
     for (let dir = dirname(file); ; dir = dirname(dir)) {

package/engine/cli/computer-checks.ts

@@ -329,8 +329,8 @@ const checkPlanningSkills = async ({ home }: { home: string }) => {
 }
 
 /**
- * Luca's own skills (#504): each is in `~/.claude/skills`, and its files
- * are the ones the installed Luca ships.
+ * Luca's own skills (#504): each one in the installed Luca's skills folder
+ * (#529) is in `~/.claude/skills`, and its files are the ones it ships.
  */
 const checkLucaSkills = async ({
     home,
@@ -342,10 +342,9 @@ const checkLucaSkills = async ({
     luca_version: string
 }) => {
     const drift = await skillDrift({ home, skills_dir })
-    const unshipped = drift.filter(({ unshipped }) => unshipped)
-    if (unshipped.length > 0) {
+    if (drift.length === 0) {
         return problem({
-            detail: `Luca's folder ${skills_dir} has no ${unshipped.map(({ skill }) => skill).join(', ')} skill.`,
+            detail: `Luca's folder ${skills_dir} has no skills.`,
             fix: `Reinstall Luca: bun add -g ${LUCA_PACKAGE}@alpha`,
         })
     }

package/engine/cli/luca-skills.ts

@@ -5,20 +5,22 @@ import type { StepEnd } from './board-in-paseo'
 import { reason } from './doctor-checks'
 
 /**
- * Luca's own Claude Code skills: `/luca-unstick` (#504) and `/luca-retro`
- * (#514). They ship in the package's `skills/` folder, next to `engine/`
- * and `board/` (`packages/engine/skills/` in the repo). `luca init` and `luca upgrade`
- * copy them to `~/.claude/skills/<skill>/`, so they work in any repo and
- * any Paseo chat, and `luca doctor` checks the copy is the one the
- * installed Luca ships (`luca doctor --fix` copies it again).
+ * Luca's own Claude Code skills, such as `/luca-unstick` (#504) and
+ * `/luca-retro` (#514). They ship in the package's `skills/` folder, next
+ * to `engine/` and `board/` (`packages/engine/skills/` in the repo). `luca
+ * init` and `luca upgrade` copy them to `~/.claude/skills/<skill>/`, so
+ * they work in any repo and any Paseo chat, and `luca doctor` checks the
+ * copy is the one the installed Luca ships (`luca doctor --fix` copies it
+ * again).
+ *
+ * Which skills there are comes from that folder, not a list in the code
+ * (#529): every folder in it with a `SKILL.md`. So a skill new in a
+ * release is copied and checked even by code from before it.
  *
  * A copy writes every file the skill ships (not its tests), over Luca's own
  * earlier copy. It never deletes, and never touches other skills.
  */
 
-/** Luca's own skills, by folder name. */
-export const LUCA_SKILLS = ['luca-unstick', 'luca-retro']
-
 /** Test files stay in the repo: they aren't part of a skill. */
 const isTestFile = (path: string) => /\.test\.[cm]?[jt]sx?$/.test(path)
 
@@ -26,6 +28,31 @@ const isTestFile = (path: string) => /\.test\.[cm]?[jt]sx?$/.test(path)
 export const claudeSkillsDir = ({ home }: { home: string }): string =>
     join(home, '.claude', 'skills')
 
+/**
+ * Luca's own skills in `skills_dir`, by folder name, sorted: each folder
+ * with a `SKILL.md`. None when the folder is missing.
+ *
+ * @example
+ * await lucaSkills({ skills_dir }) // ['luca-retro', 'luca-unstick']
+ */
+export const lucaSkills = async ({
+    skills_dir,
+}: {
+    skills_dir: string
+}): Promise<string[]> => {
+    try {
+        const manifests = await Array.fromAsync(
+            new Bun.Glob('*/SKILL.md').scan({
+                cwd: skills_dir,
+                onlyFiles: true,
+            })
+        )
+        return manifests.map((manifest) => dirname(manifest)).toSorted()
+    } catch {
+        return []
+    }
+}
+
 /**
  * The files one skill ships, relative to its folder in `skills_dir`,
  * sorted: every file but tests. None when the folder is missing.
@@ -57,8 +84,6 @@ export const skillFiles = async ({
 /** How one installed skill differs from the one Luca ships. */
 export type SkillDrift = {
     skill: string
-    /** Luca's install folder has no files for it. */
-    unshipped: boolean
     /** Shipped files the installed copy lacks. */
     missing: string[]
     /** Shipped files whose installed copy has other content. */
@@ -67,7 +92,8 @@ export type SkillDrift = {
 
 /**
  * How each of Luca's skills in `~/.claude/skills` differs from the ones in
- * `skills_dir`; a skill that matches has empty lists. Read-only.
+ * `skills_dir`; a skill that matches has empty lists. None when
+ * `skills_dir` has no skills. Read-only.
  */
 export const skillDrift = async ({
     home,
@@ -77,7 +103,7 @@ export const skillDrift = async ({
     skills_dir: string
 }): Promise<SkillDrift[]> => {
     const drift: SkillDrift[] = []
-    for (const skill of LUCA_SKILLS) {
+    for (const skill of await lucaSkills({ skills_dir })) {
         const files = await skillFiles({ skills_dir, skill })
         const missing: string[] = []
         const changed: string[] = []
@@ -94,7 +120,7 @@ export const skillDrift = async ({
                 changed.push(file)
             }
         }
-        drift.push({ skill, unshipped: files.length === 0, missing, changed })
+        drift.push({ skill, missing, changed })
     }
     return drift
 }
@@ -107,7 +133,7 @@ export const skillDrift = async ({
  *
  * @example
  * await installLucaSkills({ home: homedir(), skills_dir, prefix: '[luca init]', log: console.log })
- * // [luca init] Luca's skills: installed /luca-unstick, /luca-retro in ~/.claude/skills
+ * // [luca init] Luca's skills: installed /luca-retro, /luca-unstick in ~/.claude/skills
  */
 export const installLucaSkills = async ({
     home,
@@ -125,17 +151,15 @@ export const installLucaSkills = async ({
         return { ok, message }
     }
     try {
+        const drift = await skillDrift({ home, skills_dir })
+        if (drift.length === 0) {
+            return say({
+                message: `${prefix} Luca's skills: Luca's folder ${skills_dir} has none. Reinstall Luca.`,
+                ok: false,
+            })
+        }
         const written: string[] = []
-        for (const { skill, unshipped, missing, changed } of await skillDrift({
-            home,
-            skills_dir,
-        })) {
-            if (unshipped) {
-                return say({
-                    message: `${prefix} Luca's skills: ${skill} isn't in Luca's folder ${skills_dir}. Reinstall Luca.`,
-                    ok: false,
-                })
-            }
+        for (const { skill, missing, changed } of drift) {
             for (const file of [...missing, ...changed]) {
                 const target = join(claudeSkillsDir({ home }), skill, file)
                 await mkdir(dirname(target), { recursive: true })

package/engine/cli/upgrade-command.ts

@@ -11,25 +11,45 @@
  * board in Paseo, keeping its settings, and ends with `luca doctor`'s
  * computer checks. See `runUpgrade`.
  *
+ * Those last steps run in the version just installed (#529): upgrade
+ * hands off to it, as
+ *
+ *   luca upgrade --finish [--board-before <fingerprint>]
+ *
+ * which only Luca runs. It doesn't check for going runs or install
+ * anything: it reloads the board, copies Luca's skills, and runs the
+ * checks, with its own code. See `finishUpgrade`.
+ *
  * Exits 0 when done, 1 when it refused or a step failed, 2 on bad flags.
  */
+import { realpath } from 'node:fs/promises'
 import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
 
 import { z } from 'zod'
 
+import type { Paseo } from './computer-adapters'
 import {
     claudeOf,
     computerOf,
     lucaInstall,
     muninnHealth,
     muninnOf,
+    packageOf,
     paseoOf,
 } from './computer-adapters-real'
 import { computerChecks } from './computer-checks'
 import { reason } from './doctor-checks'
 import { defaultRegistryPath } from './going-runs'
 import { listProcesses } from './live-runs'
-import { runUpgrade, type BunGlobal, type NpmRegistry } from './upgrade'
+import {
+    runUpgrade,
+    type BunGlobal,
+    type HandOff,
+    type NewInstall,
+    type NpmRegistry,
+} from './upgrade'
+import { finishUpgrade } from './upgrade-finish'
 
 import { LUCA_PACKAGE } from '../config/luca-version'
 import { defaultRunsDir } from '../journal/journal'
@@ -77,36 +97,204 @@ const bunOf = ({ home }: { home: string }): BunGlobal => ({
     },
 })
 
-/** The `--to` version, `null` without it, or `undefined` on bad flags. */
-const parseTo = (argv: string[]): string | null | undefined => {
-    if (argv.length === 0) return null
-    const [flag, version] = argv
-    return flag === '--to' &&
-        argv.length === 2 &&
-        version !== undefined &&
-        version !== '' &&
-        !version.startsWith('-')
-        ? version
-        : undefined
+/**
+ * The new install's file older Luca looks for (see `upgrade-finish.ts`):
+ * next to its `luca.ts` when it can run `luca upgrade --finish`.
+ */
+const FINISH_MODULE = 'upgrade-finish.ts'
+
+/**
+ * The new install's `luca` entry, when it is `version` of Luca and can
+ * finish an upgrade; otherwise why not, in one sentence without a period.
+ * Finds it the way the PATH does: the `luca` in Bun's global commands
+ * folder (`bun pm bin -g`), which `bun add -g` points at the new install.
+ * Read-only.
+ *
+ * @example
+ * await findNewInstall({ bin_dir: '/Users/me/.bun/bin', version: '14.0.0-alpha.11' })
+ * // { ok: true, entry: '/Users/me/.bun/install/global/node_modules/@alecsibilia/luca/engine/cli/luca.ts' }
+ */
+export const findNewInstall = async ({
+    bin_dir,
+    version,
+}: {
+    bin_dir: string
+    version: string
+}): Promise<{ ok: true; entry: string } | { ok: false; why: string }> => {
+    const entry = await realpath(join(bin_dir, 'luca')).catch(() => null)
+    if (entry === null) {
+        return {
+            ok: false,
+            why: `Bun's global commands folder ${bin_dir} has no luca`,
+        }
+    }
+    const found = await packageOf(entry)
+    if (found?.name !== LUCA_PACKAGE || found.version !== version) {
+        const what =
+            found === null ? entry : `${found.name}@${found.version ?? '?'}`
+        return {
+            ok: false,
+            why: `The luca in ${bin_dir} is ${what}, not ${LUCA_PACKAGE}@${version}`,
+        }
+    }
+    if (!(await Bun.file(join(dirname(entry), FINISH_MODULE)).exists())) {
+        return {
+            ok: false,
+            why: `Luca ${version} can't finish an upgrade itself`,
+        }
+    }
+    return { ok: true, entry }
 }
 
+/**
+ * Runs `luca upgrade --finish` from `entry` with `bun_path`, its output
+ * going straight to this terminal; resolves to its exit code. Throws when
+ * it can't be started.
+ */
+export const handOff = async ({
+    bun_path,
+    entry,
+    board_before,
+    cwd,
+}: {
+    bun_path: string
+    entry: string
+    board_before: string | null
+    cwd: string
+}): Promise<HandOff> => {
+    const child = Bun.spawn({
+        cmd: [
+            bun_path,
+            entry,
+            'upgrade',
+            '--finish',
+            ...(board_before === null ? [] : ['--board-before', board_before]),
+        ],
+        cwd,
+        stdio: ['inherit', 'inherit', 'inherit'],
+    })
+    return { handed_off: true, exit_code: await child.exited }
+}
+
+/**
+ * The install `bun add -g` just made: found with `findNewInstall`, and
+ * handed the last steps with `handOff`. When it isn't found, or can't
+ * finish, says why, and this process runs them.
+ */
+const newInstallOf = ({ home }: { home: string }): NewInstall => ({
+    finish: async ({ version, board_before }) => {
+        const bin = await runCommand({
+            cmd: [process.execPath, 'pm', 'bin', '-g'],
+            cwd: home,
+            timeout_ms: 30_000,
+        })
+        if (bin.exit_code !== 0) {
+            return {
+                handed_off: false,
+                why: `Bun didn't say where its global commands are (bun pm bin -g exited ${bin.exit_code})`,
+            }
+        }
+        const found = await findNewInstall({
+            bin_dir: bin.stdout.trim(),
+            version,
+        })
+        if (!found.ok) return { handed_off: false, why: found.why }
+        return handOff({
+            bun_path: process.execPath,
+            entry: found.entry,
+            board_before,
+            cwd: home,
+        })
+    },
+})
+
+/** What `luca upgrade`'s flags ask for. */
+export type UpgradeArgs =
+    /** `luca upgrade [--to <version>]`; `to` is `null` without `--to`. */
+    | { finish: false; to: string | null }
+    /** `luca upgrade --finish [--board-before <fingerprint>]`, from an older Luca. */
+    | { finish: true; board_before: string | null }
+
+/** A flag's value: not empty and not another flag. */
+const isValue = (value: string | undefined): value is string =>
+    value !== undefined && value !== '' && !value.startsWith('-')
+
+/**
+ * The flags after `upgrade`, or `undefined` when they're bad. Pure.
+ *
+ * @example
+ * parseUpgradeArgs({ argv: ['--to', '14.0.0-alpha.3'] }) // { finish: false, to: '14.0.0-alpha.3' }
+ * parseUpgradeArgs({ argv: ['--finish'] }) // { finish: true, board_before: null }
+ */
+export const parseUpgradeArgs = ({
+    argv,
+}: {
+    argv: string[]
+}): UpgradeArgs | undefined => {
+    const [flag, value, ...rest] = argv
+    if (flag === undefined) return { finish: false, to: null }
+    if (flag === '--to' && isValue(value) && rest.length === 0) {
+        return { finish: false, to: value }
+    }
+    if (flag === '--finish' && value === undefined) {
+        return { finish: true, board_before: null }
+    }
+    if (flag === '--finish' && value === '--board-before') {
+        const [board_before, ...extra] = rest
+        if (isValue(board_before) && extra.length === 0) {
+            return { finish: true, board_before }
+        }
+    }
+    return undefined
+}
+
+/** Doctor's computer checks of the Luca on disk now. */
+const computerChecksOf =
+    ({ home, paseo }: { home: string; paseo: Paseo }) =>
+    async () =>
+        computerChecks({
+            home,
+            // Read again: an install changes the version on disk.
+            ...(await lucaInstall()),
+            computer: computerOf({ home }),
+            muninn: muninnOf({ home }),
+            muninn_health: muninnHealth,
+            claude: claudeOf({ home }),
+            paseo,
+        })
+
 /** Runs `luca upgrade` with the flags after `upgrade`; returns the exit code. */
 export const upgradeCommand = async ({
     argv,
 }: {
     argv: string[]
 }): Promise<number> => {
-    const to = parseTo(argv)
-    if (to === undefined) {
+    const args = parseUpgradeArgs({ argv })
+    if (args === undefined) {
         console.error(UPGRADE_USAGE)
         return 2
     }
     const home = homedir()
     const paseo = paseoOf({ client_id: 'luca-upgrade' })
+    const log = (line: string) => {
+        console.log(line)
+    }
     try {
         const { luca_version, ...install } = await lucaInstall()
+        if (args.finish) {
+            const end = await finishUpgrade({
+                version: luca_version,
+                board_before: args.board_before,
+                home,
+                paseo,
+                ...install,
+                computer_checks: computerChecksOf({ home, paseo }),
+                log,
+            })
+            return end.ok ? 0 : 1
+        }
         const end = await runUpgrade({
-            to,
+            to: args.to,
             home,
             installed_version: luca_version,
             runs_dir: defaultRunsDir(),
@@ -119,20 +307,9 @@ export const upgradeCommand = async ({
             bun: bunOf({ home }),
             paseo,
             ...install,
-            computer_checks: async () =>
-                computerChecks({
-                    home,
-                    // Read again: the install changed the version on disk.
-                    ...(await lucaInstall()),
-                    computer: computerOf({ home }),
-                    muninn: muninnOf({ home }),
-                    muninn_health: muninnHealth,
-                    claude: claudeOf({ home }),
-                    paseo,
-                }),
-            log: (line) => {
-                console.log(line)
-            },
+            new_install: newInstallOf({ home }),
+            computer_checks: computerChecksOf({ home, paseo }),
+            log,
         })
         return end.ok ? 0 : 1
     } catch (error) {

package/engine/cli/upgrade-finish.ts

@@ -0,0 +1,149 @@
+import { readdir } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import { setUpBoard } from './board-in-paseo'
+import type { PaseoPlugins } from './computer-adapters'
+import {
+    formatChecks,
+    hasProblem,
+    reason,
+    type DoctorCheck,
+} from './doctor-checks'
+import { installLucaSkills } from './luca-skills'
+
+/**
+ * The last steps of `luca upgrade`, after `bun add -g` (#529): reload the
+ * board, say when `/reload-skills` is needed, copy Luca's own skills, and
+ * run doctor's computer checks.
+ *
+ * They run in the newly installed Luca, not the one that installed it:
+ * `luca upgrade` hands off to the new install's `luca upgrade --finish`,
+ * so the board setup, the skills, and the checks are the new version's.
+ *
+ * Older Luca looks for this file next to the new install's `luca.ts` to
+ * tell whether the new install can finish an upgrade. Don't rename or move
+ * it.
+ */
+
+/** How upgrade ended; `message` is the last line it printed. */
+export type UpgradeEnd = { ok: boolean; message: string }
+
+/**
+ * A fingerprint of every file in `dir` but its `node_modules`, or `null`
+ * when it can't be read. Short, so it fits on a command line.
+ */
+export const boardFingerprint = async (dir: string): Promise<string | null> => {
+    const lines: string[] = []
+    const walk = async (at: string): Promise<void> => {
+        const entries = await readdir(at, { withFileTypes: true })
+        for (const entry of entries) {
+            const path = join(at, entry.name)
+            if (entry.isDirectory()) {
+                if (entry.name !== 'node_modules') await walk(path)
+            } else if (entry.isFile()) {
+                const bytes = await Bun.file(path).arrayBuffer()
+                lines.push(`${path}\t${Bun.hash(bytes)}`)
+            }
+        }
+    }
+    try {
+        await walk(dir)
+    } catch {
+        return null
+    }
+    return Bun.hash(lines.sort().join('\n')).toString(36)
+}
+
+/**
+ * Runs `luca upgrade`'s last steps for the installed `version`: reloads
+ * the board with its settings kept and its paths rewritten, says to run
+ * `/reload-skills` when the board's files differ from `board_before`,
+ * copies Luca's skills, then prints `computer_checks`. Ends with "Luca
+ * <version> is installed." Never throws.
+ *
+ * @example
+ * const end = await finishUpgrade({ version: '14.0.0-alpha.11', board_before, home, paseo, board_dir, skills_dir, engine_path, bun_path, computer_checks, log: console.log })
+ */
+export const finishUpgrade = async ({
+    version,
+    board_before,
+    home,
+    paseo,
+    board_dir,
+    skills_dir,
+    engine_path,
+    bun_path,
+    computer_checks,
+    log,
+}: {
+    /** The version just installed. */
+    version: string
+    /** The board folder's fingerprint before the install, or `null` when unknown. */
+    board_before: string | null
+    /** The home folder, whose `.claude/skills` gets Luca's own skills. */
+    home: string
+    paseo: PaseoPlugins
+    /** The board folder inside Luca's install folder. */
+    board_dir: string
+    /** The skills folder inside Luca's install folder. */
+    skills_dir: string
+    /** The real path of the installed `luca-run`. */
+    engine_path: string
+    /** Bun's own path. */
+    bun_path: string
+    /** Doctor's computer checks of the new install; none when not given. */
+    computer_checks?: () => Promise<DoctorCheck[]>
+    log: (line: string) => void
+}): Promise<UpgradeEnd> => {
+    const say = ({ message, ok }: UpgradeEnd): UpgradeEnd => {
+        log(`[luca upgrade] ${message}`)
+        return { ok, message }
+    }
+    try {
+        const board = await setUpBoard({
+            command: 'luca upgrade',
+            paseo,
+            // Upgrade only reloads; `luca init` asks to turn plugins on.
+            ask: async () => false,
+            board_dir,
+            engine_path,
+            bun_path,
+            log,
+        })
+        if (board.ok) {
+            const after = await boardFingerprint(board_dir)
+            if (
+                board_before === null ||
+                after === null ||
+                board_before !== after
+            ) {
+                log(
+                    "[luca upgrade] The board's files changed: run /reload-skills in a Paseo chat so its slash commands are up to date."
+                )
+            }
+        }
+        const skills = await installLucaSkills({
+            home,
+            skills_dir,
+            prefix: '[luca upgrade]',
+            log,
+        })
+        const end = say({
+            message: !board.ok
+                ? `Luca ${version} is installed, but the board wasn't reloaded. Run luca init to fix it.`
+                : !skills.ok
+                  ? `Luca ${version} is installed, but its skills weren't copied. Run luca doctor --fix to fix it.`
+                  : `Luca ${version} is installed.`,
+            ok: board.ok && skills.ok,
+        })
+        const checks = (await computer_checks?.()) ?? []
+        for (const line of formatChecks({ checks })) log(line)
+        return { ...end, ok: end.ok && !hasProblem({ checks }) }
+    } catch (error) {
+        // Such as computer checks that threw.
+        return say({
+            message: `Luca ${version} is installed, but its last steps failed: ${reason(error)}`,
+            ok: false,
+        })
+    }
+}

package/engine/cli/upgrade.ts

@@ -1,18 +1,13 @@
-import { readdir } from 'node:fs/promises'
-import { join } from 'node:path'
-
-import { setUpBoard } from './board-in-paseo'
 import type { PaseoPlugins } from './computer-adapters'
-import {
-    formatChecks,
-    hasProblem,
-    reason,
-    type DoctorCheck,
-} from './doctor-checks'
+import { reason, type DoctorCheck } from './doctor-checks'
 import { describeRun, goingRuns } from './going-runs'
 import type { ListProcesses } from './live-runs'
-import { installLucaSkills } from './luca-skills'
 import { resumeCommand } from './run-modes'
+import {
+    boardFingerprint,
+    finishUpgrade,
+    type UpgradeEnd,
+} from './upgrade-finish'
 
 import { LUCA_PACKAGE } from '../config/luca-version'
 
@@ -35,12 +30,20 @@ import { LUCA_PACKAGE } from '../config/luca-version'
  * 4. Reloads the board in Paseo, keeping its settings, and rewrites its
  *    engine and Bun paths (see `setUpBoard`).
  * 5. Says when `/reload-skills` is needed: when the board's files changed.
- * 6. Copies Luca's own skills (`/luca-unstick`, `/luca-retro`) from the new
- *    install into `~/.claude/skills` (see `installLucaSkills`).
+ * 6. Copies Luca's own skills (every one in the new install's `skills/`)
+ *    into `~/.claude/skills` (see `installLucaSkills`).
  * 7. Ends with doctor's computer checks (see `computerChecks`).
  *
- * npm's registry, Bun, Paseo, `ps`, and the computer checks are adapters,
- * so tests use fakes.
+ * Steps 4-7 (`finishUpgrade`) run in the new install, not in this process
+ * (#529): this process runs the old version's code, which doesn't know
+ * what the new version's board setup, skills, and checks are. So after
+ * step 3 upgrade hands off to the new install's `luca upgrade --finish`,
+ * passes its exit code through, and doesn't run them itself. A new install
+ * that can't finish (a version from before #529, such as a downgrade's)
+ * gets them from this process, as before.
+ *
+ * npm's registry, Bun, Paseo, `ps`, the new install, and the computer
+ * checks are adapters, so tests use fakes.
  */
 
 /** npm's registry lookups for `@alecsibilia/luca`. */
@@ -55,8 +58,28 @@ export type BunGlobal = {
     addGlobal: (args: { spec: string }) => Promise<void>
 }
 
-/** How upgrade ended; `message` is the last line it printed. */
-export type UpgradeEnd = { ok: boolean; message: string }
+export type { UpgradeEnd }
+
+/** How handing the last steps to the new install went. */
+export type HandOff =
+    /** The new install ran them; it exited with `exit_code`. */
+    | { handed_off: true; exit_code: number }
+    /** The new install can't run them, and `why` (one sentence, no period). */
+    | { handed_off: false; why: string }
+
+/** The newly installed Luca. */
+export type NewInstall = {
+    /**
+     * Runs `luca upgrade --finish` in the new install of `version`, which
+     * prints its own lines; or says why it can't. Throws when the new
+     * install couldn't be started.
+     */
+    finish: (args: {
+        version: string
+        /** The board folder's fingerprint before the install. */
+        board_before: string | null
+    }) => Promise<HandOff>
+}
 
 /** The first version of new Luca; without `--to`, nothing older is installed. */
 const FIRST_NEW_MAJOR = 14
@@ -124,40 +147,15 @@ export const channelTarget = ({
     return { ok: true, version }
 }
 
-/**
- * A fingerprint of every file in `dir` but its `node_modules`, or `null`
- * when it can't be read.
- */
-const fingerprint = async (dir: string): Promise<string | null> => {
-    const lines: string[] = []
-    const walk = async (at: string): Promise<void> => {
-        const entries = await readdir(at, { withFileTypes: true })
-        for (const entry of entries) {
-            const path = join(at, entry.name)
-            if (entry.isDirectory()) {
-                if (entry.name !== 'node_modules') await walk(path)
-            } else if (entry.isFile()) {
-                const bytes = await Bun.file(path).arrayBuffer()
-                lines.push(`${path}\t${Bun.hash(bytes)}`)
-            }
-        }
-    }
-    try {
-        await walk(dir)
-    } catch {
-        return null
-    }
-    return lines.sort().join('\n')
-}
-
 /**
  * Runs `luca upgrade`: refuses while a run is going, picks the version,
- * installs it with Bun, reloads the board with its settings kept and its
- * paths rewritten, then prints `computer_checks`. Never throws: a refusal,
- * a failed step, or a check that is a problem ends it with `ok: false`.
+ * installs it with Bun, then hands the last steps to `new_install` (see
+ * `finishUpgrade`), or runs them here when it can't take them. Never
+ * throws: a refusal, a failed step, or a check that is a problem ends it
+ * with `ok: false`.
  *
  * @example
- * const end = await runUpgrade({ to: null, home: homedir(), installed_version: lucaVersion(), runs_dir: defaultRunsDir(), registry_path, list_processes: listProcesses, npm, bun, paseo, board_dir, skills_dir, engine_path, bun_path, computer_checks, log: console.log })
+ * const end = await runUpgrade({ to: null, home: homedir(), installed_version: lucaVersion(), runs_dir: defaultRunsDir(), registry_path, list_processes: listProcesses, npm, bun, paseo, board_dir, skills_dir, engine_path, bun_path, new_install, computer_checks, log: console.log })
  */
 export const runUpgrade = async ({
     to,
@@ -173,6 +171,7 @@ export const runUpgrade = async ({
     skills_dir,
     engine_path,
     bun_path,
+    new_install,
     computer_checks,
     log,
 }: {
@@ -198,9 +197,11 @@ export const runUpgrade = async ({
     engine_path: string
     /** Bun's own path. */
     bun_path: string
+    /** The install `bun add -g` makes, which finishes the upgrade. */
+    new_install: NewInstall
     /**
      * Doctor's computer checks of the new install, run after the board
-     * reload; none when not given.
+     * reload when this process runs the last steps; none when not given.
      */
     computer_checks?: () => Promise<DoctorCheck[]>
     log: (line: string) => void
@@ -253,47 +254,48 @@ export const runUpgrade = async ({
             })
         }
 
-        const before = await fingerprint(board_dir)
+        const before = await boardFingerprint(board_dir)
         const spec = `${LUCA_PACKAGE}@${version}`
         log(`[luca upgrade] installing ${spec} (from ${installed_version})`)
         await bun.addGlobal({ spec })
         log(`[luca upgrade] installed ${spec}`)
 
-        const board = await setUpBoard({
-            command: 'luca upgrade',
+        let hand_off: HandOff
+        try {
+            hand_off = await new_install.finish({
+                version,
+                board_before: before,
+            })
+        } catch (error) {
+            return say({
+                message: `Luca ${version} is installed, but Luca couldn't start it to finish the upgrade (${reason(error)}). Run luca init to finish: it reloads the board and copies Luca's skills.`,
+                ok: false,
+            })
+        }
+        if (hand_off.handed_off) {
+            // The new install printed its own lines, its last one included.
+            return hand_off.exit_code === 0
+                ? { ok: true, message: `Luca ${version} is installed.` }
+                : say({
+                      message: `Luca ${version} is installed, but its last steps failed (exit ${hand_off.exit_code}). See above for what to fix.`,
+                      ok: false,
+                  })
+        }
+        log(
+            `[luca upgrade] ${hand_off.why}, so Luca ${installed_version} does the last steps.`
+        )
+        return await finishUpgrade({
+            version,
+            board_before: before,
+            home,
             paseo,
-            // Upgrade only reloads; `luca init` asks to turn plugins on.
-            ask: async () => false,
             board_dir,
+            skills_dir,
             engine_path,
             bun_path,
+            computer_checks,
             log,
         })
-        if (board.ok) {
-            const after = await fingerprint(board_dir)
-            if (before === null || after === null || before !== after) {
-                log(
-                    "[luca upgrade] The board's files changed: run /reload-skills in a Paseo chat so its slash commands are up to date."
-                )
-            }
-        }
-        const skills = await installLucaSkills({
-            home,
-            skills_dir,
-            prefix: '[luca upgrade]',
-            log,
-        })
-        const end = say({
-            message: !board.ok
-                ? `Luca ${version} is installed, but the board wasn't reloaded. Run luca init to fix it.`
-                : !skills.ok
-                  ? `Luca ${version} is installed, but its skills weren't copied. Run luca doctor --fix to fix it.`
-                  : `Luca ${version} is installed.`,
-            ok: board.ok && skills.ok,
-        })
-        const checks = (await computer_checks?.()) ?? []
-        for (const line of formatChecks({ checks })) log(line)
-        return { ...end, ok: end.ok && !hasProblem({ checks }) }
     } catch (error) {
         // Such as a failed `bun add -g` or registry lookup.
         return say({ message: reason(error), ok: false })

package/engine/testing/checkouts-fixtures.ts

@@ -0,0 +1,48 @@
+import { mkdir, symlink } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import { $ } from 'bun'
+
+/** The folders a skill helper can be started from, for one repo and none. */
+export type Checkouts = {
+    /** The main checkout: where a run's `run_started` repo points. */
+    main: string
+    /** A `git worktree add` of the main checkout. */
+    worktree: string
+    /** A folder inside the main checkout. */
+    subfolder: string
+    /** A symlink to the main checkout. */
+    link: string
+    /** A folder in no git repo. */
+    outside: string
+}
+
+/**
+ * Real throwaway checkouts under `dir`: a git repo with one commit, a
+ * worktree of it, a subfolder, a symlink to it, and a folder outside git.
+ * For the `/luca-unstick` and `/luca-retro` helpers' repo lookup, which must
+ * find the same runs from each of them.
+ *
+ * @example
+ * const { main, worktree } = await makeCheckouts({ dir })
+ */
+export const makeCheckouts = async ({
+    dir,
+}: {
+    dir: string
+}): Promise<Checkouts> => {
+    const main = join(dir, 'app')
+    const worktree = join(dir, 'app-worktree')
+    const subfolder = join(main, 'src', 'deep')
+    const link = join(dir, 'app-link')
+    const outside = join(dir, 'not-git')
+    await mkdir(subfolder, { recursive: true })
+    await mkdir(outside, { recursive: true })
+    await Bun.write(join(subfolder, 'a.txt'), 'a\n')
+    await $`git init -q -b main && git add -A && git -c user.name=t -c user.email=t@t -c commit.gpgsign=false commit -qm init`
+        .cwd(main)
+        .quiet()
+    await $`git worktree add -q -b side ${worktree}`.cwd(main).quiet()
+    await symlink(main, link)
+    return { main, worktree, subfolder, link, outside }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@alecsibilia/luca",
     "description": "Luca: turns a spec on GitHub Issues into a reviewed pull request, run from Paseo with Claude Code",
-    "version": "14.0.0-alpha.10",
+    "version": "14.0.0-alpha.11",
     "license": "Apache-2.0",
     "author": "Alec Sibilia <sibilia.alec@gmail.com>",
     "homepage": "https://github.com/asibilia/luca-framework#readme",

package/skills/luca-retro/SKILL.md

@@ -20,7 +20,7 @@ Run the helper from the repo's folder. It only reads.
 bun ~/.claude/skills/luca-retro/scripts/retro-summary.ts [run id ...]
 ```
 
-- No run id: it sums up this repo's newest finished run (one that opened its PR, was stopped, or had nothing to do). If that isn't the one the owner means, ask.
+- No run id: it sums up this repo's newest finished run (one that opened its PR, was stopped, or had nothing to do), found from the main checkout, any of its worktrees, or a subfolder. If that isn't the one the owner means, ask.
 - Several run ids: it sums up each, then lists the patterns that repeat across them. A repeat ranks higher.
 - It prints the run's spec, repo, Luca versions, and how it ended; then what got stuck and how long the owner took to reply, fix loops that hit their cap, leftover scan hits, agents out of turns, "No open agent session" failures, Jev calls that failed, checks and tests that failed again and again, setup changes agents asked for, joins that clashed, replies, the agents' assumptions, the findings fixers declined, slow steps, and tokens. Every line names its journal seq (`#123`).
 

package/skills/luca-retro/scripts/retro-summary.ts

@@ -27,9 +27,9 @@
  * own fixtures, and every kind in `KINDS_READ` against the journal's kinds,
  * so the two can't drift apart unseen.
  */
-import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { existsSync, readdirSync, readFileSync, realpathSync } from 'node:fs'
 import { homedir } from 'node:os'
-import { dirname, join, resolve } from 'node:path'
+import { basename, dirname, join, resolve } from 'node:path'
 
 /** Every journal record kind this script reads. */
 export const KINDS_READ = [
@@ -1185,7 +1185,7 @@ export const repoRuns = ({
     repos: string[]
 }): RunChoice[] => {
     if (!existsSync(runs_dir)) return []
-    const want = new Set(repos.map((repo) => resolve(repo)))
+    const want = new Set(repos.map(realPath))
     return readdirSync(runs_dir)
         .map((run_id) => ({
             run_id,
@@ -1197,7 +1197,7 @@ export const repoRuns = ({
             const started = records.find((r) => r.kind === 'run_started')
             return (
                 started !== undefined &&
-                want.has(resolve(text(started.content.repo) || '/'))
+                want.has(realPath(text(started.content.repo) || '/'))
             )
         })
         .map(({ run_id, records }) => ({
@@ -1258,14 +1258,36 @@ export const parseArgs = ({
 }
 
 /**
- * The current folder's repo: its git top folder, and, in a worktree, the
- * main checkout's too (a run's repo is the main checkout). The folder
- * itself outside git.
+ * A path with its symlinks followed (`/tmp` is `/private/tmp` on macOS), or
+ * just made absolute when it doesn't exist.
  */
-const currentRepos = (): string[] => {
+const realPath = (path: string): string => {
+    try {
+        return realpathSync(path)
+    } catch {
+        return resolve(path)
+    }
+}
+
+/**
+ * The repos a run started from `cwd` may name, real paths, main first: the
+ * main checkout (a run's repo is the main checkout), then the git top folder
+ * (a worktree's own, or a subfolder's repo). Outside git, `cwd` itself. A
+ * bare repo or a submodule has no `<checkout>/.git` common dir, so it adds
+ * no main checkout, only its top folder.
+ *
+ * Its twin is `currentRepos` in `luca-unstick/scripts/stuck-summary.ts`: each skill folder is installed
+ * to `~/.claude/skills/` on its own, so they can't share a file. Keep the two
+ * the same; a test in each pins it.
+ *
+ * @example
+ * currentRepos({ cwd: '/code/app-worktree' }) // ['/code/app', '/code/app-worktree']
+ */
+export const currentRepos = ({ cwd }: { cwd: string }): string[] => {
     const git = (...args: string[]) => {
-        const out = Bun.spawnSync(['git', ...args])
-        return out.exitCode === 0 ? out.stdout.toString().trim() : null
+        const out = Bun.spawnSync(['git', '-C', cwd, ...args])
+        const said = out.stdout.toString().trim()
+        return out.exitCode === 0 && said !== '' ? said : null
     }
     const top = git('rev-parse', '--show-toplevel')
     const common = git(
@@ -1273,10 +1295,12 @@ const currentRepos = (): string[] => {
         '--path-format=absolute',
         '--git-common-dir'
     )
-    return [
-        top ?? process.cwd(),
-        ...(common === null ? [] : [dirname(common)]),
-    ].filter((repo, index, all) => all.indexOf(repo) === index)
+    const main =
+        common !== null && basename(common) === '.git' ? dirname(common) : null
+    return [main, top ?? cwd]
+        .filter((repo) => repo !== null)
+        .map(realPath)
+        .filter((repo, index, all) => all.indexOf(repo) === index)
 }
 
 const main = () => {
@@ -1287,7 +1311,10 @@ const main = () => {
     })
     let run_ids = args.run_ids
     if (run_ids.length === 0) {
-        const repos = args.repo === null ? currentRepos() : [args.repo]
+        const repos =
+            args.repo === null
+                ? currentRepos({ cwd: process.cwd() })
+                : [args.repo]
         const runs = repoRuns({ runs_dir: args.runs_dir, repos })
         const pick = newestFinished({ runs })
         if (pick === null) {

package/skills/luca-unstick/SKILL.md

@@ -25,7 +25,7 @@ bun ~/.claude/skills/luca-unstick/scripts/stuck-summary.ts <run id> <ticket numb
 Pass the ticket as a bare number (`134`, not `#134`): in the shell, `#` starts a comment, so `#134` would be lost. Leave out what you weren't given.
 
 - With a run id, it sums up that run. With a ticket too, only that ticket (and the run itself).
-- With no run id, it lists this repo's runs, newest first, and sums up the newest one that waits on a reply. If that isn't the one the owner means, ask.
+- With no run id, it lists this repo's runs (from the main checkout, any of its worktrees, or a subfolder), newest first, and sums up the newest one that waits on a reply. If that isn't the one the owner means, ask.
 - It prints: the spec, its owner, the repo (`owner/repo`), the Luca version the run is on, the run branch, whether the engine is running now, how the board saw it end, and, for each stuck thing, the stuck reason and detail, the worktree, the agent's last result (such as a `bad_test` with its file, test, and reason), the last failed checks with the end of their output, and the replies since.
 
 Where things live, if you need more:

package/skills/luca-unstick/scripts/stuck-summary.ts

@@ -20,9 +20,9 @@
  * engine's own fixtures, and every kind in `KINDS_READ` against the
  * journal's kinds, so the two can't drift apart unseen.
  */
-import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { existsSync, readdirSync, readFileSync, realpathSync } from 'node:fs'
 import { homedir } from 'node:os'
-import { join, resolve } from 'node:path'
+import { basename, dirname, join, resolve } from 'node:path'
 
 /** Every journal record kind this script reads. */
 export const KINDS_READ = [
@@ -761,17 +761,18 @@ export type RunChoice = {
 
 /**
  * The runs of `repo` in `runs_dir`, newest first, with how many things
- * wait on a reply in each. A run's repo is its `run_started` repo.
+ * wait on a reply in each. A run's repo is its `run_started` repo; it
+ * matches any of `repos`, symlinks followed.
  */
 export const repoRuns = ({
     runs_dir,
-    repo,
+    repos,
 }: {
     runs_dir: string
-    repo: string
+    repos: string[]
 }): RunChoice[] => {
     if (!existsSync(runs_dir)) return []
-    const want = resolve(repo)
+    const want = new Set(repos.map(realPath))
     return readdirSync(runs_dir)
         .map((run_id) => ({
             run_id,
@@ -783,7 +784,7 @@ export const repoRuns = ({
             const started = records.find((r) => r.kind === 'run_started')
             return (
                 started !== undefined &&
-                resolve(text(started.content.repo) || '/') === want
+                want.has(realPath(text(started.content.repo) || '/'))
             )
         })
         .map(({ run_id, records }) => ({
@@ -939,10 +940,50 @@ const watchReply = async ({
     }
 }
 
-/** The git repo the current folder is in, or the folder itself. */
-const currentRepo = (): string => {
-    const top = Bun.spawnSync(['git', 'rev-parse', '--show-toplevel'])
-    return top.exitCode === 0 ? top.stdout.toString().trim() : process.cwd()
+/**
+ * A path with its symlinks followed (`/tmp` is `/private/tmp` on macOS), or
+ * just made absolute when it doesn't exist.
+ */
+const realPath = (path: string): string => {
+    try {
+        return realpathSync(path)
+    } catch {
+        return resolve(path)
+    }
+}
+
+/**
+ * The repos a run started from `cwd` may name, real paths, main first: the
+ * main checkout (a run's repo is the main checkout), then the git top folder
+ * (a worktree's own, or a subfolder's repo). Outside git, `cwd` itself. A
+ * bare repo or a submodule has no `<checkout>/.git` common dir, so it adds
+ * no main checkout, only its top folder.
+ *
+ * Its twin is `currentRepos` in `luca-retro/scripts/retro-summary.ts`: each skill folder is installed
+ * to `~/.claude/skills/` on its own, so they can't share a file. Keep the two
+ * the same; a test in each pins it.
+ *
+ * @example
+ * currentRepos({ cwd: '/code/app-worktree' }) // ['/code/app', '/code/app-worktree']
+ */
+export const currentRepos = ({ cwd }: { cwd: string }): string[] => {
+    const git = (...args: string[]) => {
+        const out = Bun.spawnSync(['git', '-C', cwd, ...args])
+        const said = out.stdout.toString().trim()
+        return out.exitCode === 0 && said !== '' ? said : null
+    }
+    const top = git('rev-parse', '--show-toplevel')
+    const common = git(
+        'rev-parse',
+        '--path-format=absolute',
+        '--git-common-dir'
+    )
+    const main =
+        common !== null && basename(common) === '.git' ? dirname(common) : null
+    return [main, top ?? cwd]
+        .filter((repo) => repo !== null)
+        .map(realPath)
+        .filter((repo, index, all) => all.indexOf(repo) === index)
 }
 
 const main = async () => {
@@ -966,13 +1007,18 @@ const main = async () => {
     }
     let run_id = args.run_id
     if (run_id === null) {
-        const repo = args.repo ?? currentRepo()
-        const runs = repoRuns({ runs_dir: args.runs_dir, repo })
+        const repos =
+            args.repo === null
+                ? currentRepos({ cwd: process.cwd() })
+                : [args.repo]
+        const runs = repoRuns({ runs_dir: args.runs_dir, repos })
         if (runs.length === 0) {
-            console.log(`No Luca runs of ${repo} in ${args.runs_dir}.`)
+            console.log(
+                `No Luca runs of ${repos.join(' or ')} in ${args.runs_dir}.`
+            )
             return
         }
-        console.log(`Runs of ${repo}, newest first:`)
+        console.log(`Runs of ${repos[0]}, newest first:`)
         for (const run of runs.slice(0, 10)) {
             console.log(
                 `- ${run.run_id}: spec #${run.spec ?? '?'}, started ${run.started}, ${run.over ? 'over' : 'not over'}, ${run.stuck} waiting on a reply`