@alecsibilia/luca 14.0.0-alpha.12 → 14.0.0-alpha.13

package/CHANGELOG.md

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

package/board/package.json

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

package/engine/config/config-reload.ts

@@ -7,20 +7,24 @@ import type { EngineConfig } from './engine-config'
 /**
  * The config fields a resumed run takes from the repo's
  * `.luca/config.json` again (#516). They say how the engine builds a
- * checkout before its tests, not what the tests are, so a run can change
- * them halfway without making its earlier results wrong: a repo that swaps
- * a slow `prepare` for a fast cached one gets it on the next resume.
+ * checkout before its tests, or how long a test may run, not what the
+ * tests are, so a run can change them halfway without making its earlier
+ * results wrong: a repo that swaps a slow `prepare` for a fast cached one
+ * gets it on the next resume.
  *
  * - `prepare`: the command run before each test run in a checkout.
  * - `prepare_timeout_ms`: how long that command may run.
  * - `prepare_concurrency`: how many prepare runs may go at once. The
  *   prepare slots take the limit on each call (`prepareCheck`), so a new
  *   one counts from the next prepare run.
+ * - `test_timeout_ms`: how long each test command may run (#542). Each run
+ *   of a test command reads it then, so a new one counts from the next.
  */
 export const RELOADED_FIELDS = [
     'prepare',
     'prepare_timeout_ms',
     'prepare_concurrency',
+    'test_timeout_ms',
 ] as const
 
 /**
@@ -79,6 +83,11 @@ export const ConfigChangeSchema = z.discriminatedUnion('field', [
         from: positiveInt,
         to: positiveInt,
     }),
+    z.object({
+        field: z.literal('test_timeout_ms'),
+        from: positiveInt,
+        to: positiveInt,
+    }),
 ])
 
 export type ConfigChange = z.infer<typeof ConfigChangeSchema>
@@ -115,6 +124,11 @@ export const configChanges = ({
             from: current.prepare_concurrency ?? null,
             to: next.prepare_concurrency ?? null,
         },
+        {
+            field: 'test_timeout_ms',
+            from: current.test_timeout_ms ?? null,
+            to: next.test_timeout_ms ?? null,
+        },
     ]
     return all.filter(({ from, to }) => from !== to)
 }
@@ -139,6 +153,10 @@ const applyChange = ({
             return change.to === null
                 ? omit(config, 'prepare_concurrency')
                 : { ...config, prepare_concurrency: change.to }
+        case 'test_timeout_ms':
+            return change.to === null
+                ? omit(config, 'test_timeout_ms')
+                : { ...config, test_timeout_ms: change.to }
     }
 }
 

package/engine/config/engine-config.ts

@@ -7,6 +7,7 @@ import {
     DecisionModelIdSchema,
     type DecisionModelId,
 } from '../jev/jev-schemas'
+import { DEFAULT_COMMAND_TIMEOUT_MS } from '../shell/run-command'
 
 /**
  * The engine config file, relative to the root of the repo a run works on.
@@ -86,6 +87,11 @@ export const EngineConfigSchema = z.object({
      * engine's default (`DEFAULT_PREPARE_CONCURRENCY`, 1).
      */
     prepare_concurrency: z.number().int().positive().optional(),
+    /**
+     * How long each test command may run, in milliseconds; left out, the
+     * engine's default (`DEFAULT_COMMAND_TIMEOUT_MS`, 5 minutes).
+     */
+    test_timeout_ms: z.number().int().positive().optional(),
     test_file_patterns: z.array(z.string()).default(['**/*.test.ts']),
     test_setup_files: z.array(z.string()).default([]),
     rule_files: z.array(z.string()).default([]),
@@ -121,6 +127,17 @@ export const prepareTimeoutOf = ({
     config: EngineConfig
 }): number => config.prepare_timeout_ms ?? DEFAULT_PREPARE_TIMEOUT_MS
 
+/**
+ * Each test command's time limit (#542): the config's `test_timeout_ms`,
+ * else the engine's default for any command. It holds for every run of a
+ * test command (baseline, red check, gates); types and lint keep the default.
+ *
+ * @example
+ * testTimeoutOf({ config: { ...config, test_timeout_ms: 900_000 } }) // 900_000
+ */
+export const testTimeoutOf = ({ config }: { config: EngineConfig }): number =>
+    config.test_timeout_ms ?? DEFAULT_COMMAND_TIMEOUT_MS
+
 /**
  * How many prepare runs may go at once when the config doesn't say: 1. A
  * build is often heavy on the CPU, so builds at the same time only slow each

package/engine/core/execute-build.ts

@@ -19,7 +19,11 @@ import {
     type AgentRole,
     type RoleResult,
 } from '../agents/role-results'
-import { bunTestCommands, type EngineConfig } from '../config/engine-config'
+import {
+    bunTestCommands,
+    testTimeoutOf,
+    type EngineConfig,
+} from '../config/engine-config'
 import { checkAlreadyDone } from '../gates/already-done-check'
 import { prepareCheck, runGates, shellCheck } from '../gates/gate-runner'
 import { endedText } from '../gates/gate-schemas'
@@ -291,6 +295,7 @@ const runRedCheck = async ({
         cwd: path,
         commands: bunTestCommands(context),
         test_files,
+        timeout_ms: testTimeoutOf({ config: context.config }),
         report_file: await reportFile({
             context,
             ticket: action.ticket,
@@ -409,6 +414,7 @@ const checkAlreadyDoneIn = async ({
                       onlyTestFiles({ command, files: runnable })
                   ),
                   test_files: runnable,
+                  timeout_ms: testTimeoutOf({ config: context.config }),
                   report_file: await reportFile({
                       context,
                       ticket: action.ticket,
@@ -1394,6 +1400,7 @@ export const executeBuildAction = async ({
                 cwd: path,
                 commands: bunTestCommands(context),
                 test_files: await testFilesIn({ context, cwd: path }),
+                timeout_ms: testTimeoutOf({ config: context.config }),
                 report_file: await reportFile({
                     context,
                     ticket: action.ticket,

package/engine/gates/gate-runner.ts

@@ -1,27 +1,21 @@
 import type { GateCheck, GateName } from './gate-schemas'
 import { PREPARE_SLOTS } from './prepare-slots'
-import { reportFileFor, runTests } from './test-runner'
+import { reportFileFor, runTests, TEST_TIMEOUT_HINT } from './test-runner'
 
 import {
     prepareConcurrencyOf,
     prepareTimeoutOf,
     testCommands,
+    testTimeoutOf,
     type EngineConfig,
 } from '../config/engine-config'
 import {
     clipOutput,
     DEFAULT_COMMAND_TIMEOUT_MS,
     runShell,
+    timedOutLine,
 } from '../shell/run-command'
 
-/** A time limit in words: `30 minutes`, `1 minute`, `0.3 seconds`. */
-const durationText = (ms: number): string => {
-    const [amount, unit] =
-        ms >= 60_000 ? [ms / 60_000, 'minute'] : [ms / 1000, 'second']
-    const rounded = Math.round(amount * 10) / 10
-    return `${rounded} ${unit}${rounded === 1 ? '' : 's'}`
-}
-
 /**
  * Runs one shell command as a named check: `ok` on exit 0, with the clipped
  * output only when it failed. One that runs past `timeout_ms` is stopped,
@@ -50,7 +44,7 @@ export const shellCheck = async ({
     const result = await runShell({ command, cwd, timeout_ms: limit })
     const ok = result.exit_code === 0
     const timedOut = result.timed_out
-        ? `Timed out after ${durationText(limit)}, so the engine stopped it and everything it started.${timeout_hint === undefined ? '' : ` ${timeout_hint}`}\n`
+        ? timedOutLine({ timeout_ms: limit, hint: timeout_hint })
         : ''
     return {
         name,
@@ -106,6 +100,8 @@ export const prepareCheck = async ({
  * types, lint. All must pass. Unset gates are left out; intake refuses a
  * config with no test command. A `bun` test command runs with bun's JUnit
  * reporter; a `pass_fail` one runs as written and is judged by its exit code.
+ * Each test command gets the config's time limit (see `testTimeoutOf`);
+ * types and lint get the engine's default.
  *
  * With an `install` command (see `installCommand`), the engine runs it first,
  * as the `install` check. A failed install stops there: the other gates
@@ -152,11 +148,20 @@ export const runGates = async ({
         if (!prepared.ok) return { ok: false, checks }
     }
     const { types, lint } = config.checks
+    const timeout_ms = testTimeoutOf({ config })
     for (const [index, { run: command, results }] of testCommands({
         config,
     }).entries()) {
         if (results === 'pass_fail') {
-            checks.push(await shellCheck({ name: 'test', command, cwd }))
+            checks.push(
+                await shellCheck({
+                    name: 'test',
+                    command,
+                    cwd,
+                    timeout_ms,
+                    timeout_hint: TEST_TIMEOUT_HINT,
+                })
+            )
             continue
         }
         const run = await runTests({
@@ -164,6 +169,7 @@ export const runGates = async ({
             command,
             test_files,
             report_file: reportFileFor({ report_file, index }),
+            timeout_ms,
         })
         checks.push({
             name: 'test',

package/engine/gates/test-runner.ts

@@ -2,7 +2,7 @@ import { existsSync } from 'node:fs'
 
 import type { TestCase, TestRun } from './gate-schemas'
 
-import { clipOutput, runShell } from '../shell/run-command'
+import { clipOutput, runShell, timedOutLine } from '../shell/run-command'
 
 const decode = (text: string): string =>
     text
@@ -83,6 +83,13 @@ export const testFilesAmong = ({
 
 const NO_TEST_FILES = /0 test files matching|No tests found!/
 
+/**
+ * How to give a test command longer, for the timed-out message. Every test
+ * command says the same, whatever its kind (#542).
+ */
+export const TEST_TIMEOUT_HINT =
+    'To give it longer, raise `test_timeout_ms` in `.luca/config.json`.'
+
 /**
  * Runs the engine config's test command with bun's JUnit reporter, so each
  * test case's outcome is known. The command must be a `bun test` command; the
@@ -90,22 +97,29 @@ const NO_TEST_FILES = /0 test files matching|No tests found!/
  *
  * A repo with no test files counts as a pass: `bun test` exits 1 there, but a
  * baseline with nothing to break is fine.
+ *
+ * One that runs past `timeout_ms` (see `testTimeoutOf`) is stopped, with
+ * everything it started, and fails; its output starts by saying so, and how
+ * to give it longer (#542).
  */
 export const runTests = async ({
     cwd,
     command,
     test_files,
     report_file,
+    timeout_ms,
 }: {
     cwd: string
     command: string
     /** The worktree's test files, to spot files that produced no results. */
     test_files: string[]
     report_file: string
+    timeout_ms: number
 }): Promise<TestRun> => {
     const shell = await runShell({
         command: `${command} --reporter=junit --reporter-outfile='${report_file}'`,
         cwd,
+        timeout_ms,
     })
     const output = `${shell.stdout}\n${shell.stderr}`
     const noTestFiles = NO_TEST_FILES.test(output)
@@ -124,7 +138,7 @@ export const runTests = async ({
         files_without_results: test_files.filter(
             (file) => !withResults.has(file)
         ),
-        output: clipOutput({ text: output }),
+        output: `${shell.timed_out ? timedOutLine({ timeout_ms, hint: TEST_TIMEOUT_HINT }) : ''}${clipOutput({ text: output })}`,
     }
 }
 
@@ -176,18 +190,21 @@ export const reportFileFor = ({
  * empty passing run.
  *
  * @example
- * const run = await runBunTests({ cwd, commands: ['bun test'], test_files, report_file })
+ * const run = await runBunTests({ cwd, commands: ['bun test'], test_files, report_file, timeout_ms: testTimeoutOf({ config }) })
  */
 export const runBunTests = async ({
     cwd,
     commands,
     test_files,
     report_file,
+    timeout_ms,
 }: {
     cwd: string
     commands: string[]
     test_files: string[]
     report_file: string
+    /** Each command's time limit (see `runTests`). */
+    timeout_ms: number
 }): Promise<TestRun> => {
     const runs: TestRun[] = []
     for (const [index, command] of commands.entries()) {
@@ -197,6 +214,7 @@ export const runBunTests = async ({
                 command,
                 test_files,
                 report_file: reportFileFor({ report_file, index }),
+                timeout_ms,
             })
         )
     }

package/engine/shell/run-command.ts

@@ -172,6 +172,32 @@ export const runShell = ({
 }): Promise<CommandResult> =>
     runCommand({ cmd: ['sh', '-c', command], cwd, timeout_ms })
 
+/** A time limit in words: `30 minutes`, `1 minute`, `0.3 seconds`. */
+export const durationText = (ms: number): string => {
+    const [amount, unit] =
+        ms >= 60_000 ? [ms / 60_000, 'minute'] : [ms / 1000, 'second']
+    const rounded = Math.round(amount * 10) / 10
+    return `${rounded} ${unit}${rounded === 1 ? '' : 's'}`
+}
+
+/**
+ * The line a timed-out command's output starts with: how long it had, that
+ * the engine stopped it, then `hint`, if any.
+ *
+ * @example
+ * timedOutLine({ timeout_ms: 300_000, hint: 'To give it longer, raise `test_timeout_ms`.' })
+ * // 'Timed out after 5 minutes, so the engine stopped it and everything it started. To give it longer, raise `test_timeout_ms`.\n'
+ */
+export const timedOutLine = ({
+    timeout_ms,
+    hint,
+}: {
+    timeout_ms: number
+    /** How to give the command longer. */
+    hint?: string
+}): string =>
+    `Timed out after ${durationText(timeout_ms)}, so the engine stopped it and everything it started.${hint === undefined ? '' : ` ${hint}`}\n`
+
 /** Keeps the start and end of long output, for the journal and prompts. */
 export const clipOutput = ({
     text,

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.12",
+    "version": "14.0.0-alpha.13",
     "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

@@ -64,7 +64,7 @@ Find the stuck reason: `ticket_stuck` (a ticket), `final_review_stuck` (the fina
 | `nothing_new_to_test` | The test-writer found nothing to test. | Two cases. (a) The ticket changes no behavior: add the `refactor` label to the ticket, then `retry #n` (a label change starts it over as a refactor). (b) The work is already on the base branch: check the commit it names is really there (`git log --oneline <base> -- <file>`). If nothing else in the run is left to build, reply `stop`, then offer to close the ticket with a comment naming the commit. If other tickets still build, reply `retry #n`: on Luca 14.0.0-alpha.2 or newer, a fresh test-writer can answer "already done", and the engine checks it and closes the ticket itself. |
 | `red_check_failed` | The new tests don't fail the way they should, after every fix round (or a test update left a criterion with no test). | Read the red check's problems. Usually a criterion is vague, or a "new" test already passes. Make the ticket's criteria clearer (a text change starts it over), or fix the tests in the worktree (step 4). Then `retry #n`. |
 | `agent_failed` | An agent failed on every try it had. | Read the last failed try. A guard failure means it wrote a file its role may not (such as a report file); a result failure means bad output. If the cause is in the ticket (unclear, too big), fix the ticket and `retry #n`. If it looks like the model had a bad day, `retry #n`. If it keeps failing the same way, it may be an engine bug (see below). |
-| `gates_failed` | The checks (tests, types, lint) still fail after every fix round. | Read the failing check's output. If it's a real bug in the ticket's code, fix it in the worktree only if it's small and clear, else make the ticket clearer; then `retry #n`. If the check fails on `main` too (a flaky or broken test), fix that first. |
+| `gates_failed` | The checks (tests, types, lint) still fail after every fix round. | Read the failing check's output. If it's a real bug in the ticket's code, fix it in the worktree only if it's small and clear, else make the ticket clearer; then `retry #n`. If the check fails on `main` too (a flaky or broken test), fix that first. If a test check's output starts with "Timed out", the tests ran out of time (5 minutes by default): raise `test_timeout_ms` in `.luca/config.json`. A run takes the new value when it resumes. |
 | `changes_requested` | The ticket review still asks for changes after every fix round. | Read the open findings. If they matter, fix them in the worktree (or clarify the ticket) and `retry #n`. If they can wait, `skip #n` keeps the rest of the run going. |
 | `join_failed` | The ticket still clashes with the run branch after every rebase. | `retry #n` puts it on the run branch's tip again (uncommitted edits in its worktree are replaced). If two tickets keep fighting over the same lines, `skip #n` and build it in a later run. |
 | `join_gates_failed` | The checks fail once the ticket joins the run branch. Its join was undone, so the run branch is safe. | Usually two tickets that pass alone but break together. `retry #n` fixes it on top of the run branch. |