@alecsibilia/luca 14.0.0-alpha.34 → 14.0.0-alpha.35

package/CHANGELOG.md

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

package/board/package.json

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

package/engine/core/execute-build.ts

@@ -275,6 +275,9 @@ export const executeBuildAction = async ({
                 exclusive: action.exclusive,
             })
         case 'join_run_branch': {
+            // Already joined: its commits are on the run branch, and its
+            // join keeps the record of which ones are its own (#719).
+            if (state.tickets[action.ticket]?.joined?.ok === true) return
             const worktree = ticketWorktree({ state, ticket: action.ticket })
             const runBranch = need({
                 value: state.run_branch,

package/engine/core/execute.ts

@@ -83,9 +83,10 @@ type InFlight = { action: EngineAction; done: Promise<void> }
  * only alone, once everything in flight has settled; and one action on
  * the run branch at a time (a new worktree, a join, its gates, a push, a
  * rebase). A stop action waits for everything in flight, then the journal is
- * read again. If an action throws (such as a launcher stop), the rest are
- * let finish, then the first error is thrown. `max_steps` counts the actions
- * started.
+ * read again. A step that ends while the engine decides makes it decide
+ * again, so no step runs twice from a stale decision (#719). If an action
+ * throws (such as a launcher stop), the rest are let finish, then the first
+ * error is thrown. `max_steps` counts the actions started.
  *
  * With `jev`, the decision model is asked around each step in **shadow
  * mode** and its answers are journaled but never acted on (see
@@ -350,8 +351,21 @@ export const runEngine = async ({
             // and no fix round goes to a closed one.
             await closeFinished({ all: false })
             const records = journal.read()
+            const readWhile = [...inFlight.keys()]
             const crashes = crashesIn(records)
             const decided = await decideNow(records)
+            // A step that ended while the engine decided freed its key, but
+            // the decision was made from records where it had not ended: it
+            // would run that step again, such as a second join (#719).
+            // Decide again from the journal as it is now. The journal tells
+            // first: `step_ended` is written before the key is freed.
+            const endedSince = journal
+                .read()
+                .slice(records.length)
+                .some(({ kind }) => kind === 'step_ended')
+            if (endedSince || readWhile.some((key) => !inFlight.has(key))) {
+                continue
+            }
             const actions = redosFirst({ actions: decided.actions, crashes })
             const stop = actions.find((action) => stops.has(action.type))
             if (stop !== undefined && inFlight.size === 0) {

package/engine/core/live-file.ts

@@ -107,6 +107,12 @@ const LiveFeedEntrySchema = z.object({
 /** The whole live file, as each write has it. */
 export const LiveFileSchema = z.object({
     written_at: z.string(),
+    /**
+     * The engine's pid (#727), so `/luca-watch` and `/luca-unstick` can
+     * tell a live engine from a stopped one whatever the file's age.
+     * Missing in files from older engines.
+     */
+    pid: z.number().int().optional(),
     /** The run's first plan-usage reading, as its `rate_limit_event` sent it. */
     plan_usage: z.record(z.string(), z.unknown()).nullable(),
     agents: z.array(LiveAgentSchema),
@@ -203,6 +209,7 @@ export const createLiveFile = ({ file }: { file: string }) => {
         changed = false
         const live: LiveFile = {
             written_at: new Date(at).toISOString(),
+            pid: process.pid,
             plan_usage,
             agents: [...agents].map(([key, agent]) => ({
                 ...agent,

package/engine/testing/unstick-fixtures.ts

@@ -0,0 +1,77 @@
+import { mkdir } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import {
+    gatesRun,
+    implemented,
+    intakePassed,
+    practiceTicket,
+    runBranchCreated,
+    stuckReported,
+    ticketStuck,
+    ticketWorktreeCreated,
+} from './build-fixtures'
+import { recordsFrom } from './intake-fixtures'
+
+import type { JournalEntry } from '../journal/journal-record'
+
+/**
+ * Journals for the `/luca-unstick` helper's tests (`stuck-summary*.test.ts`),
+ * written to disk as the engine writes them.
+ */
+
+export const UNSTICK_TICKETS = [
+    practiceTicket({ number: 11, title: 'Add sum' }),
+    practiceTicket({ number: 12, title: 'Add product' }),
+]
+
+/** Ticket #11 stuck on a bad test, reported on the spec. */
+export const stuckOnBadTest = (): JournalEntry[] => [
+    ...intakePassed({ tickets: UNSTICK_TICKETS }),
+    runBranchCreated(),
+    ticketWorktreeCreated({ ticket: 11 }),
+    implemented({
+        ticket: 11,
+        outcome: 'bad_test',
+        reason: 'It pins build addresses.',
+    }),
+    gatesRun({ ticket: 11, target: 'ticket', ok: false }),
+    ticketStuck({ ticket: 11, reason: 'bad_test', detail: 'Sent back twice.' }),
+    stuckReported({ ticket: 11 }),
+]
+
+/** A run's journal to write: its entries, repo, and first seq. */
+export type UnstickRun = {
+    /** The runs folder. */
+    dir: string
+    run_id?: string
+    entries: JournalEntry[]
+    repo?: string
+    first_seq?: number
+}
+
+/**
+ * Writes a run's journal to the runs folder `dir`, its seqs starting at
+ * `first_seq` and its `run_started` naming `repo`, and returns its path.
+ */
+export const writeRunFile = async ({
+    dir,
+    run_id = 'run-1',
+    entries,
+    repo = '/repos/app',
+    first_seq = 1,
+}: UnstickRun): Promise<string> => {
+    const records = recordsFrom({ entries }).map((record) => ({
+        ...(record.kind === 'run_started'
+            ? { ...record, content: { ...record.content, repo } }
+            : record),
+        seq: record.seq + first_seq - 1,
+    }))
+    await mkdir(join(dir, run_id), { recursive: true })
+    const file = join(dir, run_id, 'journal.jsonl')
+    await Bun.write(
+        file,
+        records.map((record) => JSON.stringify(record)).join('\n') + '\n'
+    )
+    return file
+}

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.34",
+    "version": "14.0.0-alpha.35",
     "license": "Apache-2.0",
     "author": "Alec Sibilia <sibilia.alec@gmail.com>",
     "homepage": "https://github.com/asibilia/luca-framework#readme",
@@ -36,8 +36,8 @@
     },
     "dependencies": {
         "@anthropic-ai/claude-agent-sdk": "0.3.273",
-        "@getpaseo/client": "0.9.1",
-        "@getpaseo/plugin": "0.9.1",
+        "@getpaseo/client": "0.14.0",
+        "@getpaseo/plugin": "0.14.0",
         "@modelcontextprotocol/sdk": "1.30.0",
         "lodash": "^4.17.21",
         "zod": "^4.3.6"

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

@@ -10,6 +10,7 @@
  * are installed.
  */
 import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
 
 /** Every journal record kind the helper reads. */
 export const KINDS_READ = [
@@ -459,14 +460,57 @@ export const registryEntry = ({
     }
 }
 
-/** Whether a run's engine is running now, from `ps`; `null` when unknown. */
+/**
+ * A live file written at most this long ago means a live engine: the
+ * board's `LIVE_STALE_MS` (`packages/board/shared/board-state-live.ts`).
+ * The engine writes it at least every 5 seconds while it runs.
+ */
+export const LIVE_STALE_MS = 60_000
+
+/** What a run's live file says of its engine: when it was written, and its pid. */
+export type LiveFacts = {
+    written_at: string
+    /** `null` in a file from an engine older than #727. */
+    pid: number | null
+}
+
+/**
+ * Whether a run's engine is running now; `null` when unknown. It runs when
+ * a command line from `ps` names the run, or its live file shows it. An
+ * engine started with `luca-run --spec <n>` and no `--run-id` names no run
+ * id (#727), so only its live file shows it. When the file names the
+ * engine's pid, it runs exactly while `alive(pid)`, however old the file
+ * (a laptop asleep) or fresh (an engine that just stopped). A file with no
+ * pid counts while written at most `LIVE_STALE_MS` from `now`, either way,
+ * as the board checks.
+ */
 export const engineRunning = ({
     run_id,
     command_lines,
+    live,
+    alive,
+    now,
 }: {
     run_id: string
     command_lines: string[] | null
+    /** The run's live file (`readLiveFile`), or `null`. */
+    live: LiveFacts | null
+    alive: (pid: number) => boolean
+    now: number
 }): boolean | null => {
+    if (live !== null) {
+        if (live.pid !== null) {
+            if (alive(live.pid)) return true
+        } else {
+            const written = Date.parse(live.written_at)
+            if (
+                Number.isFinite(written) &&
+                Math.abs(now - written) <= LIVE_STALE_MS
+            ) {
+                return true
+            }
+        }
+    }
     if (command_lines === null) return null
     return command_lines.some((line) => {
         const tokens = line.split(/\s+/)
@@ -480,6 +524,43 @@ export const engineRunning = ({
     })
 }
 
+/**
+ * Run `run_id`'s live file (`live.json`, kept by the engine while it runs):
+ * its `written_at` and the engine's `pid`, or `null` when it is missing or
+ * unreadable.
+ */
+export const readLiveFile = ({
+    runs_dir,
+    run_id,
+}: {
+    runs_dir: string
+    run_id: string
+}): LiveFacts | null => {
+    const file = join(runs_dir, run_id, 'live.json')
+    if (!existsSync(file)) return null
+    try {
+        const live: unknown = JSON.parse(readFileSync(file, 'utf8'))
+        if (!isObject(live) || typeof live.written_at !== 'string') return null
+        return {
+            written_at: live.written_at,
+            pid: typeof live.pid === 'number' ? live.pid : null,
+        }
+    } catch {
+        return null
+    }
+}
+
+/** Whether process `pid` is alive: signal 0 checks without sending. */
+export const pidAlive = (pid: number): boolean => {
+    try {
+        process.kill(pid, 0)
+        return true
+    } catch (error) {
+        // EPERM: it's alive, just not ours to signal.
+        return isObject(error) && error.code === 'EPERM'
+    }
+}
+
 /** Every process's command line, or `null` when `ps` fails. */
 export const commandLines = (): string[] | null => {
     const ps = Bun.spawnSync(['ps', '-axww', '-o', 'command='])

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

@@ -40,6 +40,8 @@ import {
     numberOr,
     objectOf,
     openStuck,
+    pidAlive,
+    readLiveFile,
     readRecords,
     registryEntry,
     repoOfUrl,
@@ -54,7 +56,9 @@ export {
     cutOffSteps,
     engineRunning,
     KINDS_READ,
+    LIVE_STALE_MS,
     openStuck,
+    readLiveFile,
     readRecords,
     registryEntry,
     repoOfUrl,
@@ -539,7 +543,13 @@ const main = async () => {
             records,
             ticket: args.ticket,
             registry,
-            running: engineRunning({ run_id, command_lines: commandLines() }),
+            running: engineRunning({
+                run_id,
+                command_lines: commandLines(),
+                live: readLiveFile({ runs_dir: args.runs_dir, run_id }),
+                alive: pidAlive,
+                now: Date.now(),
+            }),
             log_tail: logTail(registry?.log_path ?? null),
         })
     )

package/skills/luca-watch/SKILL.md

@@ -55,7 +55,7 @@ It polls the journal every five seconds and prints one JSON line, `{ "event", "l
 
 - `stuck`: a `stuck_reported`; `detail` is its comment body. Run the summary for the actual reason (from `ticket_stuck`, `final_review_stuck`, or `run_stuck`), then sections 3 to 5.
 - `ended`: the run is over (a `run_ended`, or an older run's `pull_request_opened`, `intake_refused`, `nothing_to_do`, `stop` reply, or a billing or crash `run_stopped`). Report the outcome in one line, with the PR URL when present, log it, and stop.
-- `engine_gone`: no live engine names the run. Section 6. The helper answers `engine_gone` at once while no engine is live, so after an engine-gone handoff (including a failed or used-up resume) log it and stop; the owner starts `/luca-watch` again after resuming the run.
+- `engine_gone`: no live engine names the run, and the run's live file (`live.json`) shows none: the pid it names is not running, or, from an older engine with no pid, it is over a minute old. Section 6. The helper answers `engine_gone` at once while no engine is live, so after an engine-gone handoff (including a failed or used-up resume) log it and stop; the owner starts `/luca-watch` again after resuming the run.
 - `quiet`: five quiet minutes. Call it again with the same cursor and stay in the loop. Don't log quiet polls.
 - `error`: a missing journal, an unknown run, an invalid cursor, or bad arguments (exit code 2) stop the watcher, with a handoff. A process-inspection error (the process list kept failing) comes back only after the helper's five-minute wait, during which it still returns new journal records; it gets one serious handoff per changed error plus seq. Then call the helper again and keep processing journal events, but never resume without reliable process evidence. Any other journal-read error: try again on the next loop, and hand it off after three consecutive failures.
 

package/skills/luca-watch/scripts/wait-for-change.ts

@@ -13,7 +13,8 @@
  * - `ended`: the oldest ending after the cursor (`run_ended`, or a legacy
  *   one: `pull_request_opened`, `intake_refused`, `nothing_to_do`, a `stop`
  *   reply, a billing or crash `run_stopped`), or one before it.
- * - `engine_gone`: no live engine names the run, and it has not ended.
+ * - `engine_gone`: no live engine names the run, its live file shows no
+ *   live engine, and it has not ended.
  * - `quiet`: five minutes with none of these. Call it again.
  * - `error`: the journal can't be read; or the process list kept failing
  *   until the quiet deadline, while the journal still showed nothing new.
@@ -23,7 +24,7 @@
  * skipped. A missing journal, an unknown run, an invalid cursor or bad
  * arguments print an `error` line and exit 2; every other event exits 0.
  *
- * It only reads: the journal and the process list. It imports nothing but
+ * It only reads: the journal, the run's live file, and the process list. It imports nothing but
  * Bun's and Node's own modules, since it runs from
  * `~/.claude/skills/luca-watch/`, where no packages are installed.
  */
@@ -185,6 +186,58 @@ const engineLive = ({
         )
     })
 
+/** The engine's live file in a run folder: `LIVE_FILE` in `src/core/live-file.ts`. */
+const LIVE_FILE = 'live.json'
+
+/**
+ * A live file written at most this long ago means a live engine: the
+ * board's `LIVE_STALE_MS` (`packages/board/shared/board-state-live.ts`).
+ * The engine writes it at least every 5 seconds while it runs.
+ */
+export const LIVE_STALE_MS = 60_000
+
+/**
+ * Whether run `run_id`'s live file shows a live engine (#727). An engine
+ * started with `luca-run --spec <n>` and no `--run-id` makes the run id
+ * itself, so no command line names it; its live file still shows it. When
+ * the file names the engine's pid, the engine is live exactly while that
+ * pid is in `processes`, however old the file (a laptop asleep) or fresh
+ * (an engine that just stopped). A file from an older engine, with no pid,
+ * counts while it was written at most `LIVE_STALE_MS` from `now`, either
+ * way, as the board checks. A missing or unreadable file shows nothing.
+ */
+const liveFileLive = async ({
+    runs_dir,
+    run_id,
+    processes,
+    now,
+}: {
+    runs_dir: string
+    run_id: string
+    processes: ProcessRow[]
+    now: number
+}): Promise<boolean> => {
+    try {
+        const live: unknown = await Bun.file(
+            join(runs_dir, run_id, LIVE_FILE)
+        ).json()
+        if (!isObject(live)) return false
+        if (typeof live.pid === 'number') {
+            return processes.some(({ pid }) => pid === live.pid)
+        }
+        const written_at =
+            typeof live.written_at === 'string'
+                ? Date.parse(live.written_at)
+                : Number.NaN
+        return (
+            Number.isFinite(written_at) &&
+            Math.abs(now - written_at) <= LIVE_STALE_MS
+        )
+    } catch {
+        return false
+    }
+}
+
 /** `pid` and every parent above it, from `processes`. Pure. */
 const ancestorPids = ({
     pid,
@@ -274,7 +327,15 @@ export const waitForChange = async ({
             const own = own_pids.flatMap((pid) =>
                 ancestorPids({ pid, processes: rows })
             )
-            if (!engineLive({ run_id, processes: rows, own_pids: own })) {
+            if (
+                !engineLive({ run_id, processes: rows, own_pids: own }) &&
+                !(await liveFileLive({
+                    runs_dir,
+                    run_id,
+                    processes: rows,
+                    now: now(),
+                }))
+            ) {
                 return {
                     event: 'engine_gone',
                     last_seq: highest,