@alecsibilia/luca 14.0.0-alpha.7 → 14.0.0-alpha.9

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @alecsibilia/luca
 
+## 14.0.0-alpha.9
+
+No changes in this release.
+
+## 14.0.0-alpha.8
+
+No changes in this release.
+
 ## 14.0.0-alpha.7
 
 No changes in this release.

package/board/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@luca/board",
-    "version": "14.0.0-alpha.7",
+    "version": "14.0.0-alpha.9",
     "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.7"
+export const LUCA_VERSION: string = "14.0.0-alpha.9"

package/board/server/reduce-board.ts

@@ -61,6 +61,8 @@ const STUCK_REASONS: Record<string, string> = {
     setup_change_needed:
         'An agent needs a test setup file changed; only you may change one.',
     crashed: 'The engine crashed in the same step again and again.',
+    undo_refused:
+        'Undoing its join would have rewound the run branch over other work.',
 }
 
 /**

package/board/shared/board-state.ts

@@ -3,7 +3,7 @@ import { z } from 'zod'
 /**
  * The board's view of one run, as the plugin's server keeps it and the side
  * panel reads it. Shared by both runtimes, so it holds only Zod schemas and
- * plain values. Words follow CONTEXT.md: ticket, blocked, gate, red check,
+ * plain values. Words follow GLOSSARY.md: ticket, blocked, gate, red check,
  * fix loop, ticket review, final review, lens, finding, stuck, skipped ticket,
  * limit wait, shadow mode.
  */

package/engine/core/decide-build.ts

@@ -1254,13 +1254,16 @@ const notRemoved = ({
  * the run branch's tip, then its install) once every ticket it waits on has
  * pushed, and while no ticket waits to join, so it never builds on joined
  * commits whose gates have not passed yet. Approved tickets join one at a
- * time, in the order their reviews finally approved them. A clash or failed
+ * time, in the order their reviews finally approved them, except that one
+ * already joining finishes first. A clash or failed
  * gates after joining puts the ticket's change back on top of the run
- * branch to be fixed there (up to `MAX_REJOINS` times), then re-reviewed. A
- * stuck ticket ends the run: no ticket starts or moves on, and the worktrees
- * of pushed tickets are removed. Once every ticket pushed, the final review
- * looks at the whole run branch (`decideFinalReview`) before the PR opens; a
- * stuck final review ends the run with the run branch's worktree kept. In a
+ * branch to be fixed there (up to `MAX_REJOINS` times), then re-reviewed.
+ * While a stuck ticket's join is still on the run branch, no ticket starts
+ * or joins until it is undone (#519), so no join lands on top of a join
+ * that is going away. A stuck ticket ends the run: no ticket starts or
+ * moves on, and the worktrees of pushed tickets are removed. Once every
+ * ticket pushed, the final review looks at the whole run branch
+ * (`decideFinalReview`) before the PR opens; a stuck final review ends the run with the run branch's worktree kept. In a
  * repo with changesets, the run's changeset is written just before the PR
  * (`write_changeset`), once. Once
  * the PR is open, every worktree is removed. Branches and the journal stay.
@@ -1450,6 +1453,8 @@ const buildSteps = ({
         }
     }
 
+    // A ticket already on the run branch finishes its join first (#519): a
+    // retried ticket approved earlier never joins on top of it.
     const queue = sortBy(
         numbers.filter(
             (number) =>
@@ -1457,16 +1462,20 @@ const buildSteps = ({
                 !isStuck(number) &&
                 !skipped(number)
         ),
-        (number) => progress(number).approved_seq
+        [
+            (number) => progress(number).joined === null,
+            (number) => progress(number).approved_seq,
+        ]
     )
-    const joiner = queue[0] ?? null
-    // A stuck ticket's join is undone before any new ticket starts on it.
+    // A stuck ticket's join is undone before any new ticket starts on it
+    // or joins on top of it (#519): a join on top would be undone with it.
     const stuckJoinOnRunBranch = numbers.some(
         (number) =>
             isStuck(number) &&
             progress(number).joined?.ok === true &&
             progress(number).pushed === null
     )
+    const joiner = stuckJoinOnRunBranch ? null : (queue[0] ?? null)
 
     const steps = numbers.flatMap((number): BuildAction[] => {
         const ticket = snapshot.tickets[number]

package/engine/core/decide-stuck.ts

@@ -137,7 +137,9 @@ const awaitingReply = (progress: TicketProgress): boolean =>
 /**
  * The next steps of one stuck ticket: undo a join its stuck left on the run
  * branch (so no other ticket builds on it), tell the spec issue, then act
- * on the owner's reply. Nothing while it waits for one.
+ * on the owner's reply. Nothing while it waits for one. A ticket stuck
+ * because its undo was refused (`undo_refused`, #519) is never undone again
+ * before a reply: it is told at once, with its join left where it is.
  */
 export const stuckTicketSteps = ({
     spec_number,
@@ -151,7 +153,11 @@ export const stuckTicketSteps = ({
     const { stuck, joined } = progress
     if (stuck === null) return []
     const number = ticket.number
-    if (joined?.ok === true && progress.pushed === null) {
+    if (
+        joined?.ok === true &&
+        progress.pushed === null &&
+        stuck.reason !== 'undo_refused'
+    ) {
         const first_sha = joined.shas[0]
         if (first_sha !== undefined) {
             return [{ type: 'undo_join', ticket: number, first_sha }]

package/engine/core/execute-build.ts

@@ -949,11 +949,37 @@ const undoCutOffJoin = async ({
     await context.git.resetWorktree({ cwd: runBranch.path, to: sha })
 }
 
+/**
+ * The run branch commits an undo of `ticket`'s join may take (#519): its
+ * own joined commits, and those of any other ticket that joined and has not
+ * pushed (a later join on top goes with it, and replay clears that join
+ * too). A pushed ticket's commits never.
+ */
+const undoableCommits = ({
+    state,
+    ticket,
+}: {
+    state: RunState
+    ticket: number
+}): string[] =>
+    uniq(
+        Object.entries(state.tickets).flatMap(([number, progress]) => {
+            const { joined } = progress
+            if (!joined?.ok) return []
+            const own = Number(number) === ticket
+            return own || progress.pushed === null ? joined.shas : []
+        })
+    )
+
 /**
  * Undoes a ticket's join on the run branch, back to before `first_sha`, and
- * returns the commits undone. The undone join's install is still in the run
- * branch's `node_modules`, so when its commits changed dependency files the
- * lockfile's install runs there again.
+ * returns the commits undone. It never rewinds over other work (#519): it
+ * may only undo the ticket's own join and later joins not pushed yet
+ * (`undoableCommits`). When git refuses, the run branch is left alone, the
+ * ticket is stuck (`undo_refused`) with why, and it returns `null`, so the
+ * caller does nothing more. The undone joins' install is still in the run
+ * branch's `node_modules`, so when their commits changed dependency files
+ * the lockfile's install runs there again.
  */
 const undoJoin = async ({
     context,
@@ -963,20 +989,45 @@ const undoJoin = async ({
     context: BuildContext
     ticket: number
     first_sha: string
-}): Promise<string[]> => {
-    const { git, state, journal } = context
+}): Promise<string[] | null> => {
+    const { git, state, journal, launcher } = context
     const runBranch = need({ value: state.run_branch, what: 'run branch' })
     const joined = state.tickets[ticket]?.joined
-    const last = joined?.ok ? joined.shas.at(-1) : undefined
+    const tip = await git.head({ cwd: runBranch.path })
+    const undo = await git.undoReplay({
+        cwd: runBranch.path,
+        first_sha,
+        only: undoableCommits({ state, ticket }),
+    })
+    if (!undo.ok) {
+        // A stuck ticket's agents take no more follow-ups.
+        await closeSessions({
+            journal,
+            launcher,
+            sessions: openSessionsIn({ records: journal.read() }).filter(
+                (session) => session.ticket === ticket
+            ),
+        })
+        journal.append({
+            kind: 'ticket_stuck',
+            ticket,
+            role: null,
+            content: {
+                reason: 'undo_refused',
+                detail: `The engine went to undo this ticket's join on the run branch (from ${first_sha.slice(0, 7)}), but that would have rewound the run branch over other work, so the run branch was left alone:\n${undo.error}`,
+            },
+        })
+        return null
+    }
+    const { undone } = undo
     const undoneFiles =
-        last === undefined
+        undone.length === 0
             ? []
             : await git.filesBetween({
                   cwd: runBranch.path,
                   from: `${first_sha}^`,
-                  to: last,
+                  to: tip,
               })
-    const { undone } = await git.undoReplay({ cwd: runBranch.path, first_sha })
     // A redo whose first try undid the join before a crash finds nothing
     // left to undo: the commits it undid are the journaled join's.
     const named =
@@ -999,7 +1050,8 @@ const undoJoin = async ({
  * join first if asked (its gates failed), then resets the ticket's worktree
  * to the run branch's tip and applies the ticket's whole diff there,
  * uncommitted, with conflict markers in the files that clash. Journals the
- * clashed files split into tests and code.
+ * clashed files split into tests and code. A refused undo (#519) leaves the
+ * ticket stuck, and nothing is rebased.
  */
 const rebaseTicket = async ({
     context,
@@ -1025,6 +1077,8 @@ const rebaseTicket = async ({
                   ticket: action.ticket,
                   first_sha: action.undo_first_sha,
               })
+    // A refused undo left the run branch alone and the ticket stuck.
+    if (undone === null) return
     const onto = await git.head({ cwd: runBranch.path })
     const moved_files = await git.filesBetween({
         cwd: worktree.path,
@@ -1458,20 +1512,22 @@ export const executeBuildAction = async ({
             })
             return
         }
-        case 'undo_join':
+        case 'undo_join': {
+            const shas = await undoJoin({
+                context,
+                ticket: action.ticket,
+                first_sha: action.first_sha,
+            })
+            // A refused undo left the run branch alone and the ticket stuck.
+            if (shas === null) return
             journal.append({
                 kind: 'join_undone',
                 ticket: action.ticket,
                 role: null,
-                content: {
-                    shas: await undoJoin({
-                        context,
-                        ticket: action.ticket,
-                        first_sha: action.first_sha,
-                    }),
-                },
+                content: { shas },
             })
             return
+        }
         case 'retry_ticket':
             return retryTicket({ context, action })
         case 'report_stuck':

package/engine/core/stuck-text.ts

@@ -37,6 +37,8 @@ const REASON_LINES: Record<StuckReason, string> = {
     setup_change_needed:
         'An agent needs a test setup file changed, and only you may change one.',
     crashed: 'The engine crashed in the same step, again and again.',
+    undo_refused:
+        'Undoing its join would have rewound the run branch over other work, so the run branch was left alone.',
 }
 
 /** What the user could do, per reason; `n` is the ticket. */
@@ -75,6 +77,8 @@ const suggestion = ({
             return `Make that change yourself in the worktree, then reply ${retry}.`
         case 'crashed':
             return `Read the engine's log for why it crashed, fix what trips it, then reply ${retry} to take the step again with a fresh agent.`
+        case 'undo_refused':
+            return `Put the run branch back so this ticket's join is on top (or take its join off by hand), then reply ${retry}; or reply \`skip #${n}\`.`
     }
 }
 

package/engine/git/git-adapter.ts

@@ -134,14 +134,21 @@ export type GitAdapter = {
     }) => Promise<{ ok: true; shas: string[] } | { ok: false; error: string }>
     /**
      * Undoes a replay on the branch checked out at `cwd`: resets it hard to
-     * the commit before `first_sha`. Safe to run twice.
+     * the commit before `first_sha`. It never rewinds over other work
+     * (#519), so it refuses, with the branch left as it is, when
+     * `first_sha` is no commit (or has no parent), is not on the branch, or
+     * when any commit from `first_sha` up to the branch's tip is not in
+     * `only`. Safe to run twice: with the branch already at the commit
+     * before `first_sha`, it undoes nothing.
      *
-     * @returns The commits it undid, oldest first.
+     * @returns The commits it undid, oldest first, or why it refused.
      */
     undoReplay: (args: {
         cwd: string
         first_sha: string
-    }) => Promise<{ undone: string[] }>
+        /** The commits it may undo: any other on top of `first_sha` refuses. */
+        only: string[]
+    }) => Promise<{ ok: true; undone: string[] } | { ok: false; error: string }>
     /**
      * Moves a worktree's change onto another commit: resets the worktree at
      * `cwd` hard to `onto`, then applies the whole diff from `from` to `to`
@@ -535,16 +542,52 @@ export const createGitAdapter = ({
                 ),
             }
         },
-        undoReplay: async ({ cwd, first_sha }) => {
-            const before = `${first_sha}^`
+        undoReplay: async ({ cwd, first_sha, only }) => {
+            const short = first_sha.slice(0, 7)
+            const parent = await gitRun({
+                cwd,
+                args: [
+                    'rev-parse',
+                    '--verify',
+                    '--quiet',
+                    `${first_sha}^{commit}^`,
+                ],
+            })
+            if (parent.exit_code !== 0) {
+                return {
+                    ok: false,
+                    error: `Commit ${short} is not in the repo (or has no parent), so there is no join to undo.`,
+                }
+            }
+            const before = parent.stdout.trim()
+            const tip = await head({ cwd })
+            const ancestor = await gitRun({
+                cwd,
+                args: ['merge-base', '--is-ancestor', first_sha, 'HEAD'],
+            })
+            if (ancestor.exit_code !== 0) {
+                // Already undone, such as a redo after a crash.
+                if (tip === before) return { ok: true, undone: [] }
+                return {
+                    ok: false,
+                    error: `Commit ${short} is not on the branch, so undoing it (a reset to its parent) would rewind the branch over other work.`,
+                }
+            }
             const undone = lines(
                 await gitOk({
                     cwd,
                     args: ['rev-list', '--reverse', `${before}..HEAD`],
                 })
             )
+            const others = undone.filter((sha) => !only.includes(sha))
+            if (others.length > 0) {
+                return {
+                    ok: false,
+                    error: `Undoing ${short} would also undo other work on top of it: ${others.map((sha) => sha.slice(0, 7)).join(', ')}.`,
+                }
+            }
             await gitOk({ cwd, args: ['reset', '--quiet', '--hard', before] })
-            return { undone }
+            return { ok: true, undone }
         },
         rebaseWorktree: async ({ cwd, from, to, onto }) => {
             const folder = await mkdtemp(join(tmpdir(), 'luca-rebase-'))

package/engine/journal/journal-record.ts

@@ -684,7 +684,9 @@ export type RejoinCause = z.infer<typeof RejoinCauseSchema>
  * and `code` are the files that clashed (conflict markers left in them),
  * split by the config's test file patterns. `undone` are the run branch
  * commits the engine undid first (a join whose gates failed), and
- * `reinstall` says whether the worktree needs its install again.
+ * `reinstall` says whether the worktree needs its install again. As with
+ * `join_undone`, replay clears the join of any other ticket whose joined
+ * commits are among `undone` (#519).
  */
 const TicketRebasedEntrySchema = z.object({
     ...ENTRY_FIELDS,
@@ -751,6 +753,8 @@ const RunBranchPushedEntrySchema = z.object({
 /**
  * Why a ticket (or the final review) is stuck. A failed red check or gate is only stuck once its
  * fix loop reaches its cap, and a bad test only on its second bounce.
+ * `undo_refused`: undoing its join would have rewound the run branch over
+ * other work, so the engine left the run branch alone (#519).
  */
 export const StuckReasonSchema = z.enum([
     'agent_failed',
@@ -766,6 +770,7 @@ export const StuckReasonSchema = z.enum([
     'prepare_failed',
     'setup_change_needed',
     'crashed',
+    'undo_refused',
 ])
 
 export type StuckReason = z.infer<typeof StuckReasonSchema>
@@ -956,7 +961,11 @@ const FinalReviewRetriedEntrySchema = z.object({
 
 /**
  * A stuck ticket's join was undone on the run branch (its commits were
- * never pushed), so no other ticket builds on them.
+ * never pushed), so no other ticket builds on them. `shas` are every commit
+ * the undo took off the run branch, oldest first: the ticket's own join and
+ * any later, unpushed joins on top of it (#519). Replay clears the join of
+ * every ticket whose joined commits are among them, not only this one's, so
+ * those tickets join again on the run branch as it is now.
  */
 const JoinUndoneEntrySchema = z.object({
     ...ENTRY_FIELDS,

package/engine/journal/replay.ts

@@ -1208,6 +1208,18 @@ const applyRecord = ({
                 state: { ...next, run_notes: notesAfter({ state, record }) },
                 record,
             })
+        case 'join_undone':
+            return undoneJoinsAfter({
+                state: applyTicketRecord({ state: next, record }),
+                ticket: record.ticket,
+                shas: record.content.shas,
+            })
+        case 'ticket_rebased':
+            return undoneJoinsAfter({
+                state: applyTicketRecord({ state: next, record }),
+                ticket: record.ticket,
+                shas: record.content.undone,
+            })
         // Always the final review's (see finalRecordOf above).
         case 'final_review_started':
         case 'lens_started':
@@ -2278,8 +2290,8 @@ const retriedChange = ({
  * - in a review fix round, the round starts over as round 1 with fresh
  *   fixers, so the user's changes are gated, committed, and re-reviewed;
  * - a leftover scan, a failed install, a failed prepare command at the
- *   baseline, a reviewer's failed tries, a failed join, or a step crashes
- *   cut off just run again.
+ *   baseline, a reviewer's failed tries, a failed join, a refused undo of
+ *   its join (#519), or a step crashes cut off just run again.
  */
 const resumedProgress = ({
     progress,
@@ -2320,6 +2332,7 @@ const resumedProgress = ({
         reason === 'prepare_failed' ||
         reason === 'join_failed' ||
         reason === 'join_gates_failed' ||
+        reason === 'undo_refused' ||
         reason === 'crashed' ||
         reviewerFailed
     ) {
@@ -2564,6 +2577,41 @@ const closedSessionAfter = ({
     }
 }
 
+/**
+ * The other tickets whose joins an undo took off the run branch (#519): an
+ * undo resets the run branch to before the undone ticket's join, so any
+ * join on top of it goes too. Each such ticket's join and join gates are
+ * cleared, as its own undo would, so it joins again on the run branch as it
+ * is now, and a stuck one is never undone a second time. Its push, stuck,
+ * and reply are kept.
+ */
+const undoneJoinsAfter = ({
+    state,
+    ticket,
+    shas,
+}: {
+    state: RunState
+    /** The ticket whose join was undone. */
+    ticket: number | null
+    /** Every commit the undo took off the run branch. */
+    shas: string[]
+}): RunState => {
+    if (shas.length === 0) return state
+    return {
+        ...state,
+        tickets: mapValues(state.tickets, (progress, number) => {
+            const { joined } = progress
+            const taken =
+                Number(number) !== ticket &&
+                joined?.ok === true &&
+                joined.shas.some((sha) => shas.includes(sha))
+            return taken
+                ? { ...progress, joined: null, join_gates: null }
+                : progress
+        }),
+    }
+}
+
 const applyTicketRecord = ({
     state,
     record,

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.7",
+    "version": "14.0.0-alpha.9",
     "license": "Apache-2.0",
     "author": "Alec Sibilia <sibilia.alec@gmail.com>",
     "homepage": "https://github.com/asibilia/luca-framework#readme",

package/skills/luca-unstick/SKILL.md

@@ -72,6 +72,7 @@ Find the stuck reason: `ticket_stuck` (a ticket), `final_review_stuck` (the fina
 | `leftovers_found` | The leftover scan found files that must not be committed (a report file, a nested git repo). | Delete or move those files out of the worktree (they're not the ticket's work), then `retry #n`. |
 | `setup_change_needed` | An agent needs a test setup file changed, and only a person may do that. | Read what it asks for. If it's right, make that change yourself in the worktree (ask the owner first: this one isn't a test file), then `retry #n`. |
 | `crashed` | The engine crashed in the same step, again and again. | That's an engine bug, not the ticket (see below). |
+| `undo_refused` | The ticket's join is still on the run branch, but undoing it would have rewound the run branch over other work (its join isn't on the branch, or other commits sit on top of it), so Luca left the run branch alone. Nothing new starts or joins until it's sorted (#519). | Look at the run branch's log next to the joins in the journal. Put the run branch back so the ticket's join is on top, or take its join off by hand (ask the owner first), then `retry #n`. Or `skip #n`. |
 | `run_budget` | The whole run used up its budget of tokens. | Look at what used them (a ticket stuck in fix loops?). A bare `retry` gives one more full budget; `stop` ends the run. |
 | `pull_request_failed` | Every ticket is done, but `gh pr create` failed, so the run's PR didn't open. The run branch is pushed, and the PR's full text is in the run folder's `pull-request.md`. | Read `gh`'s error. A GitHub or sign-in hiccup: a bare `retry` opens the PR. If you open it by hand from the run branch first, `retry` reuses it and never opens a second one. |