@jals1212/ci-local-pi 0.1.1 → 0.3.0

package/CHANGELOG.md

@@ -6,6 +6,40 @@ add or change behaviour and a patch version fixes.
 
 ## Unreleased
 
+## 0.3.0
+
+### Changed
+
+- Status line: a `·` separates the name from the state, as other footer
+  integrations do (`🚦 ci-local · ✓ passed · 4m12s`, was
+  `🚦 ci-local ✓ passed · 4m12s`). (#45)
+
+## 0.2.0
+
+### Added
+
+- Tool `ci_local_run`: starts a run of the repository's own ci-local
+  (`node_modules/.bin`, else `PATH`) detached from Pi, for this session.
+  (#42, #43)
+  - It returns once the run is queued or started, or with ci-local's output
+    when it ends first (`--list`, a usage or config error, `--no-wait` on a
+    busy machine).
+  - No background job, so no job notice: the footer and the end card report
+    the run.
+  - A launch that ends after the tool returned, without the session ever
+    seeing its run, gets an end card of its own with the end of its output.
+  - Launch outputs live under `$TMPDIR` and are removed after a week.
+- Skill: starts runs with `ci_local_run` when present. (#42)
+
+### Changed
+
+- Status line: the state's glyph sits by the state, after the name
+  (`🚦 ci-local ✓ passed · 4m12s`, was `🚦 ✓ ci-local passed`). (#40)
+- Status line: a queued run says how many runs are ahead of it and which one
+  is running (`🚦 ci-local ◌ queued · 2 ahead (erp-ci running)`). It said
+  only `behind erp-ci`, the run at the head of the queue, so every waiting
+  session read the same. (#40)
+
 ## 0.1.1
 
 ### Changed

package/README.md

@@ -23,8 +23,8 @@ In a session opened inside a repository with `ci-local.config.sh` (with a
 literal `CI_PROJECT=`), it follows the events file of that project; it never
 runs ci-local or Docker itself:
 
-- **Status line**: `🚦 ◌ ci-local queued · behind erp-ci`, `🚦 ⧗ ci-local [3/8] lint · 2m05s`,
-  then `🚦 ✓ ci-local passed · 4m12s` or `🚦 ✗ ci-local failed at lint · 2m10s` until
+- **Status line**: `🚦 ci-local · ◌ queued · 2 ahead (erp-ci running)`, `🚦 ci-local · ⧗ [3/8] lint · 2m05s`,
+  then `🚦 ci-local · ✓ passed · 4m12s` or `🚦 ci-local · ✗ failed at lint · 2m10s` until
   the next run. A run already over when a session starts shows only while its
   result is undelivered, like an unread message: it ended with no session of
   the repository open. Once a session has shown it finished, a later session
@@ -73,9 +73,24 @@ runs ci-local or Docker itself:
   session starts is not announced.
 - **Tool `ci_local_status`**: the same three lines for the agent, without a
   shell.
-- **Skill `ci-local`**: how an agent runs and waits for ci-local (in the
-  background (quiet without a terminal), never two runs, read only the failing
-  step's log).
+- **Tool `ci_local_run`**: starts the repository's own ci-local
+  (`node_modules/.bin/ci-local`, else the one on `PATH`) with optional
+  arguments (`args`), detached from Pi: its own process group, no terminal,
+  stdout and stderr in a private file it names (under `$TMPDIR`, removed by a
+  launch a week later). The run records the
+  session's `PI_SESSION_ID`, so it is the session's own. The tool returns
+  once the run is queued or started (up to 15 seconds: a run of the same
+  project that still holds the events file keeps a new one silent until its
+  turn), or with its output when it ends first (`--list`, `--print-plan`, a
+  usage or config error, a busy machine with `--no-wait`). There is no
+  background job, so no job notice: the footer and the end card report the
+  run, and the hidden wake reaches an idle agent. A launch that ends after
+  the tool returned without the session ever seeing its run (no event, or
+  one replaced before the session read it) gets a failed end card with the
+  end of its output.
+- **Skill `ci-local`**: how an agent runs and waits for ci-local (with
+  `ci_local_run`, else in the background, quiet without a terminal; never two
+  runs; read only the failing step's log).
   Branch and merge policy stay the project's.
 
 The extension follows the file ci-local would write: `CI_LOCAL_EVENTS` from

package/extensions/ci-local.ts

@@ -1,9 +1,9 @@
 // Pi extension for @jals1212/ci-local: the state of this repository's
 // ci-local run in Pi's own UI, so neither the agent nor you write it by hand.
 //
-// - Status line: `🚦 ⧗ ci-local [3/8] lint · 2m05s`, `🚦 ◌ ci-local queued ·
-//   behind erp-ci`, then `🚦 ✓ ci-local passed · 4m12s` / `🚦 ✗ ci-local failed
-//   at lint` until the next run (🚦 is ci-local's own emoji, see BRAND).
+// - Status line: `🚦 ci-local · ⧗ [3/8] lint · 2m05s`, `🚦 ci-local · ◌ queued ·
+//   2 ahead (erp-ci running)`, then `🚦 ci-local · ✓ passed · 4m12s` / `🚦 ci-local ·
+//   ✗ failed at lint` until the next run (🚦 is ci-local's own emoji, see BRAND).
 //   A run already over when a session starts is shown only if no session
 //   showed its result yet, like a message not yet delivered (createStatusLine).
 // - Cards and the agent: only for runs this session started, as Gentle AI's job
@@ -24,6 +24,11 @@
 //   in a run gets it steered in; busy without a run (compacting), it waits. A
 //   failed delivery is tried again, never dropped.
 // - Tool `ci_local_status`: the same three lines, for the agent, without bash.
+// - Tool `ci_local_run`: starts the repository's own ci-local detached, named
+//   for this session, and returns once it is queued or started (or with its
+//   output when it ends first). No background job, so no job notice: the
+//   footer and the end card report the run. One that ends later before any
+//   event gets an end card of its own.
 //
 // It reads the events file each run writes (see README, "Following a run");
 // it never runs ci-local or Docker. The logic lives in ./core.js.
@@ -34,6 +39,7 @@ import { Box, Text } from '@earendil-works/pi-tui'
 import { Type } from 'typebox'
 
 import {
+  LAUNCH_WAIT_MS,
   WAKE_TEXT,
   cardContent,
   createDelivery,
@@ -41,9 +47,13 @@ import {
   createTracker,
   deliveryOptions,
   eventsFileFor,
+  exitCard,
   findProject,
+  launchReport,
+  launchRun,
   ownsRun,
   readRun,
+  waitForStart,
 } from './core.js'
 
 const KEY = 'ci-local'
@@ -63,11 +73,12 @@ type Card = { state: string; lines: string[] }
 /** A start card: the run, its stage ('starting', then 'started'), the --status block. */
 type StartCard = { key: string; phase: 'starting' | 'started'; lines: string[] }
 
-export function createCiLocalExtension() {
-  return (pi: ExtensionAPI) => ciLocal(pi)
+/** launchWaitMs: how long ci_local_run waits for the run's first event (LAUNCH_WAIT_MS). */
+export function createCiLocalExtension({ launchWaitMs = LAUNCH_WAIT_MS }: { launchWaitMs?: number } = {}) {
+  return (pi: ExtensionAPI) => ciLocal(pi, { launchWaitMs })
 }
 
-function ciLocal(pi: ExtensionAPI) {
+function ciLocal(pi: ExtensionAPI, { launchWaitMs }: { launchWaitMs: number }) {
   // Said at load, before any session starts, so a CLI 0.7.x bridge can see it
   // whatever the load order; session_shutdown takes it back (a reload without
   // this package must not find it still there).
@@ -78,6 +89,12 @@ function ciLocal(pi: ExtensionAPI) {
   // agent_start to agent_settled (in-run compaction and retries included).
   let delivery: ReturnType<typeof createDelivery> | undefined
   let runActive = false
+  // The runs ci_local_run started, by pid, until their run shows in the events
+  // file (seen) or they end. One that ends unseen, after the tool returned,
+  // gets an end card of its own (exitCard): no event will ever name it. Each
+  // belongs to the session that started it; another session drops it.
+  type Launch = ReturnType<typeof launchRun> & { seen: boolean; waiting: boolean; sessionId: string }
+  const launches = new Map<number, Launch>()
 
   pi.on('agent_start', async () => {
     runActive = true
@@ -134,6 +151,44 @@ function ciLocal(pi: ExtensionAPI) {
     },
   })
 
+  pi.registerTool({
+    name: 'ci_local_run',
+    label: 'ci-local run',
+    description:
+      "Start this repository's ci-local (its own node_modules/.bin/ci-local, else the one on PATH) detached, with optional arguments " +
+      '(e.g. ["--only", "lint"]; never --live), and return once it is queued or started. ' +
+      'Use it instead of bash or bash_background: no job notice, the footer follows the run and its end card ' +
+      'reaches you when it ends. Do not poll, sleep or start a second run to check it. ' +
+      'Commands that end at once (--list, --print-plan, --down) return their output.',
+    promptSnippet: 'ci_local_run: start a ci-local run of this repository; its end card reaches you when it ends',
+    parameters: Type.Object({
+      args: Type.Optional(Type.Array(Type.String(), { description: 'ci-local arguments, one per item' })),
+    }),
+    async execute(_id, params, signal, _onUpdate, ctx) {
+      const found = findProject(ctx.cwd)
+      if (!found) throw new Error(`no ci-local.config.sh with a literal CI_PROJECT at or above ${ctx.cwd}`)
+      const sessionId = ctx.sessionManager.getSessionId()
+      const launch = launchRun({ repo: found.repo, args: params.args ?? [], sessionId })
+      const tracked: Launch = Object.assign(launch, { seen: false, waiting: true, sessionId })
+      if (launch.pid !== undefined) launches.set(launch.pid, tracked)
+      const result = await waitForStart(launch, eventsFileFor(found.project, process.env, found.repo), { timeoutMs: launchWaitMs, signal })
+      tracked.waiting = false
+      if (result.kind === 'started') tracked.seen = true
+      if (result.kind === 'exited') {
+        if (launch.pid !== undefined) launches.delete(launch.pid)
+        if (launch.error) throw new Error(`cannot start ${launch.bin}: ${launch.error}`)
+      }
+      return { content: [{ type: 'text', text: launchReport(result, launch, found.project) }], details: { kind: result.kind, pid: launch.pid } }
+    },
+  })
+
+  /** Launches of an earlier session are that session's: not this one's to report. */
+  function dropLaunchesOfOtherSessions(sessionId: string) {
+    for (const [pid, launch] of launches) {
+      if (launch.sessionId !== sessionId) launches.delete(pid)
+    }
+  }
+
   function stop() {
     if (timer) clearInterval(timer)
     timer = undefined
@@ -161,6 +216,7 @@ function ciLocal(pi: ExtensionAPI) {
     // Whether each run seen in flight is this session's own (decided once: by the
     // session the run names, else by its process ancestry; see ownsRun).
     const sessionId = ctx.sessionManager.getSessionId()
+    dropLaunchesOfOtherSessions(sessionId)
     const owned = new Map<string, boolean>()
     const isOwn = (run: NonNullable<ReturnType<typeof readRun>>) => {
       if (!owned.has(run.key)) owned.set(run.key, ownsRun(run, { sessionId }))
@@ -181,6 +237,7 @@ function ciLocal(pi: ExtensionAPI) {
       }
       const { footer, changed } = statusLine.update(run)
       if (changed) ctx.ui.setStatus(KEY, footer)
+      settleLaunches(run)
       // Only this session's own runs get cards and reach the agent, as Gentle
       // AI's job notices go only to the session that started the job. Another
       // session's run in this repository shows in the status line alone. What
@@ -206,6 +263,21 @@ function ciLocal(pi: ExtensionAPI) {
       deliver()
     }
 
+    // The launches of ci_local_run: one whose run shows in the events is
+    // followed like any run; one that ended without its run ever showing here
+    // gets an end card of its own (exitCard), as no event will name it.
+    const settleLaunches = (run: ReturnType<typeof readRun>) => {
+      for (const [pid, launch] of launches) {
+        if (run?.state.pid === pid) launch.seen = true
+        if (launch.waiting || !launch.ended) continue
+        launches.delete(pid)
+        if (launch.seen) continue
+        const card = exitCard(launch)
+        ctx.ui.notify(`ci-local ended before this session saw its run · ${found.project}`, card.state.state === 'passed' ? 'info' : 'error')
+        ends.ended(card)
+      }
+    }
+
     // At most one delivery per tick: a failure is retried later (see createDelivery).
     const deliver = () => {
       let action

package/extensions/core.js

@@ -2,8 +2,24 @@
 // follows, the footer line, and when a run it watched has ended. The
 // rendering and the states are those of `ci-local --status` (status.js).
 
-import { spawnSync } from 'node:child_process'
-import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { spawn, spawnSync } from 'node:child_process'
+import {
+  closeSync,
+  existsSync,
+  fstatSync,
+  lstatSync,
+  mkdirSync,
+  mkdtempSync,
+  openSync,
+  readFileSync,
+  readdirSync,
+  readSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs'
+import { tmpdir } from 'node:os'
 import { dirname, isAbsolute, join } from 'node:path'
 
 import { BRAND, GLYPHS, alive, duration, lastRun, render, runState } from '@jals1212/ci-local/status'
@@ -268,27 +284,34 @@ export function createStatusLine({ file, sessionId, reason }) {
   }
 }
 
-/** One short line for the footer. */
+/** One short line for the footer: `🚦 ci-local · ✓ passed · 4m12s`. */
 export function footerText(state) {
+  // The state's glyph sits by the state, after the name.
+  return `${BRAND} ci-local · ${GLYPHS[state.state] ?? GLYPHS.stopped} ${stateText(state)}`
+}
+
+/** The state of a run in a few words, as the footer says it after its glyph. */
+export function stateText(state) {
   const time = duration(state.elapsedMs)
   switch (state.state) {
     case 'running':
-      return state.step
-        ? `${BRAND} ${GLYPHS.running} ci-local [${state.step.index}/${state.step.total}] ${state.step.step} · ${time}`
-        : `${BRAND} ${GLYPHS.running} ci-local running · ${time}`
+      return state.step ? `[${state.step.index}/${state.step.total}] ${state.step.step} · ${time}` : `running · ${time}`
     case 'starting':
-      return `${BRAND} ${GLYPHS.starting} ci-local starting · ${time}`
+      return `starting · ${time}`
     case 'queued': {
-      const behind = state.blockedBy?.project
-      const queued = `${BRAND} ${GLYPHS.queued} ci-local queued`
-      return behind ? `${queued} · behind ${behind}` : queued
+      // blockedBy names the run at the head of the queue (the one running), the
+      // same for every run waiting: how many are ahead tells them apart.
+      const running = state.blockedBy?.project ? `${state.blockedBy.project} running` : ''
+      if (!(state.ahead > 0)) return running ? `queued · ${running}` : 'queued'
+      const ahead = `queued · ${state.ahead} ahead`
+      return running ? `${ahead} (${running})` : ahead
     }
     case 'passed':
-      return `${BRAND} ${GLYPHS.passed} ci-local passed · ${time}`
+      return `passed · ${time}`
     case 'failed':
-      return state.fail ? `${BRAND} ${GLYPHS.failed} ci-local failed at ${state.fail.step} · ${time}` : `${BRAND} ${GLYPHS.failed} ci-local failed · ${time}`
+      return state.fail ? `failed at ${state.fail.step} · ${time}` : `failed · ${time}`
     default:
-      return `${BRAND} ${GLYPHS.stopped} ci-local stopped`
+      return 'stopped'
   }
 }
 
@@ -449,3 +472,187 @@ export function createDelivery({ isAlive = alive, now = Date.now } = {}) {
     },
   }
 }
+
+// ---------------------------------------------------------------- ci_local_run
+//
+// The ci_local_run tool starts a run itself, detached from Pi's tools, so no
+// background job announces its end: the footer follows it and the end card
+// (with its wake) reports it, as for any run this session starts. A run that
+// ends before its first event (a usage or config error, `--list`, a busy
+// machine with --no-wait) leaves no card: the tool reports it when it ends
+// while the tool waits, exitCard when it ends later.
+
+/** The directories of launch outputs, in the temporary directory. */
+const LAUNCH_PREFIX = 'ci-local-run-'
+
+/** How long a launch's output is kept: past it, the next launch removes it. */
+export const LAUNCH_OUTPUT_TTL_MS = 7 * 24 * 3600 * 1000
+
+/** Removes the launch outputs in `dir` older than `maxAgeMs`; never fails. */
+export function pruneLaunchOutputs({ dir = tmpdir(), maxAgeMs = LAUNCH_OUTPUT_TTL_MS, now = Date.now() } = {}) {
+  let names = []
+  try {
+    names = readdirSync(dir)
+  } catch {
+    return
+  }
+  for (const name of names) {
+    if (!name.startsWith(LAUNCH_PREFIX)) continue
+    const path = join(dir, name)
+    try {
+      const stat = lstatSync(path)
+      if (stat.isDirectory() && now - stat.mtimeMs > maxAgeMs) rmSync(path, { recursive: true, force: true })
+    } catch {
+      // Gone already, or not ours to remove: left alone.
+    }
+  }
+}
+
+/** The ci-local a repository runs: its own (node_modules/.bin), else the one on PATH. */
+export function ciLocalBin(repo) {
+  const local = join(repo, 'node_modules', '.bin', 'ci-local')
+  return existsSync(local) ? local : 'ci-local'
+}
+
+/**
+ * Starts ci-local in `repo` with `args`, detached (its own process group, no
+ * terminal, nothing Pi waits on), naming the session in PI_SESSION_ID so the
+ * run is this session's (ownsRun). Its stdout and stderr go to a private file
+ * (`output`). Once it ends, `ended` is true, with its exit status in `code`
+ * or the signal that killed it in `signal`; when it could not start at all,
+ * `error` says why and both are null. `exited` settles then.
+ */
+export function launchRun({ repo, args = [], sessionId, env = process.env, bin = ciLocalBin(repo) }) {
+  pruneLaunchOutputs()
+  const dir = mkdtempSync(join(tmpdir(), LAUNCH_PREFIX))
+  const output = join(dir, 'output.log')
+  const launch = { bin, output, pid: undefined, ended: false, code: null, signal: null, error: undefined, exited: undefined }
+  let child
+  try {
+    const fd = openSync(output, 'a', 0o600)
+    try {
+      child = spawn(bin, args, { cwd: repo, detached: true, stdio: ['ignore', fd, fd], env: { ...env, PI_SESSION_ID: sessionId } })
+    } finally {
+      closeSync(fd) // the child has its own copy
+    }
+  } catch (error) {
+    rmSync(dir, { recursive: true, force: true }) // nothing ran: no output to keep
+    throw error
+  }
+  launch.pid = child.pid
+  launch.exited = new Promise((resolve) => {
+    child.once('error', (error) => {
+      launch.error = error.message
+      launch.ended = true
+      resolve(launch)
+    })
+    child.once('exit', (code, signal) => {
+      Object.assign(launch, { code, signal, ended: true })
+      resolve(launch)
+    })
+  })
+  child.unref()
+  return launch
+}
+
+/** How long ci_local_run waits for the run's first event. */
+export const LAUNCH_WAIT_MS = 15_000
+
+/**
+ * Waits until the launched run shows in the events file (its pid in the last
+ * run: `started`, with the run), ends first (`exited`), or `timeoutMs` passes
+ * or `signal` aborts (`waiting`: a run of the same project may still own the
+ * events file, and this one writes nothing before its turn). The run itself
+ * is never stopped here.
+ */
+export async function waitForStart(launch, file, { timeoutMs = LAUNCH_WAIT_MS, pollMs = 250, signal } = {}) {
+  const deadline = Date.now() + timeoutMs
+  const aborted = new Promise((resolve) => signal?.addEventListener('abort', resolve, { once: true }))
+  for (;;) {
+    // Snapshot "has it exited?" first, then read the events. A run that wrote
+    // its events and exited in between is then found by its events (started),
+    // never taken for one that exited before writing any.
+    const ended = launch.ended
+    let run = null
+    try {
+      run = file ? readRun(file) : null
+    } catch {
+      // A half-written file: the next look reads it whole.
+    }
+    if (run && launch.pid !== undefined && run.state.pid === launch.pid) return { kind: 'started', run }
+    if (ended) return { kind: 'exited' }
+    if (Date.now() >= deadline || signal?.aborted) return { kind: 'waiting' }
+    await Promise.race([launch.exited, aborted, new Promise((resolve) => setTimeout(resolve, pollMs))])
+  }
+}
+
+/** How much of the end of a launch's output outputTail reads. */
+const TAIL_BYTES = 64 * 1024
+
+/** The last `count` lines of a launch's output, from its last TAIL_BYTES (none when it cannot be read). */
+export function outputTail(output, count = 20) {
+  let fd
+  try {
+    fd = openSync(output, 'r')
+    const size = fstatSync(fd).size
+    const length = Math.min(size, TAIL_BYTES)
+    const buffer = Buffer.alloc(length)
+    readSync(fd, buffer, 0, length, size - length)
+    const lines = buffer.toString('utf8').trimEnd().split('\n')
+    if (length < size) lines.shift() // cut mid-line
+    return lines.slice(-count)
+  } catch {
+    return []
+  } finally {
+    if (fd !== undefined) closeSync(fd)
+  }
+}
+
+/** How a launch ended, in a few words: `status 2`, or `killed by SIGTERM`. */
+const howEnded = ({ code, signal }) => (signal ? `killed by ${signal}` : `status ${code}`)
+
+/** The first line of ci_local_run's answer for a launch that ended before its run showed. */
+function endedLine(launch) {
+  if (launch.code === 0) return 'ci-local finished (status 0) without a run'
+  const verb = launch.signal ? 'was' : 'exited with'
+  return `ci-local ${verb} ${howEnded(launch)} before a run started`
+}
+
+/** What ci_local_run tells the agent of a launch and how it stands. */
+export function launchReport(result, launch, project) {
+  const where = `Output: ${launch.output}.`
+  const follow = 'The footer follows it and its end card reaches you when it ends: do not poll, sleep or run `ci-local --status`.'
+  if (result.kind === 'started')
+    return `ci-local started (pid ${launch.pid}) for ${project}: ${stateText(result.run.state)}. ${follow} ${where}`
+  if (result.kind === 'waiting')
+    return `ci-local launched (pid ${launch.pid}) for ${project}, no event yet: another run of ${project} may hold its events file until it ends. ${follow} ${where}`
+  const tail = outputTail(launch.output)
+  return [
+    `${endedLine(launch)}. ${where}`,
+    ...(tail.length ? ['', '```', ...tail, '```'] : []),
+  ].join('\n')
+}
+
+/**
+ * A launch that ended after ci_local_run returned without the session ever
+ * seeing its run (it wrote no event, or one the session never read before a
+ * later run took the events file), as a run for the end card
+ * (createDelivery): failed, with the end of its output, which says what
+ * happened either way.
+ */
+export function exitCard({ pid, code, signal = null, output, tail = outputTail(output, 10) }) {
+  // Status 0: its run passed, or it had no run to make; anything else failed.
+  const state = code === 0 ? 'passed' : 'failed'
+  return {
+    key: `launch:${pid}`,
+    state: { state, pid, pidStart: null },
+    block: {
+      code: code === 0 ? 0 : 1,
+      lines: [
+        `> ${BRAND} ${GLYPHS[state]} **ci-local** · ended before this session saw its run`,
+        `> ${howEnded({ code, signal })} · pid ${pid} · output \`${output}\``,
+        ...tail.map((line) => `> ${line}`),
+      ],
+    },
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jals1212/ci-local-pi",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Pi extension and skill for @jals1212/ci-local: the state of this repository's ci-local run in Pi's status line, cards and a read-only tool for the agent.",
   "license": "MIT",
   "author": "jals1212",

package/skills/ci-local/SKILL.md

@@ -4,7 +4,7 @@ description: "Trigger: ci-local, run CI locally, ci-local.config.sh, CI_PROJECT,
 license: MIT
 metadata:
   author: jals1212
-  version: "0.1.1"
+  version: "0.3.0"
 ---
 
 ## Activation Contract
@@ -14,7 +14,7 @@ Use when running, waiting on, reading, or configuring `ci-local` (`npx ci-local`
 ## Hard Rules
 
 - Run the repository's own ci-local (`npx ci-local`, `pnpm exec ci-local`), never a global install: the version is the repository's.
-- Launch a run in the background (`bash_background` or equivalent) and wait for its exit notice; never poll, never `sleep`.
+- Start a run with the `ci_local_run` tool when present: it returns once the run is queued or started, and its end card reaches you when it ends. Without it, launch in the background (`bash_background` or equivalent) and wait for its exit notice. Never poll, never `sleep`.
 - Unwatched runs are quiet: milestones and the summary on stdout, each step's output in its own log. From 0.5.0 that is the default without a terminal; before 0.5.0, add `--quiet`. Never add `--live` to a background run.
 - Do not touch the checkout while a run is in flight (no edits, no branch switch): the steps read it.
 - Never start a second run to "check" the first. Runs queue machine-wide by themselves (one Docker user at a time); a waiting run is normal, not a hang.
@@ -28,6 +28,7 @@ Use when running, waiting on, reading, or configuring `ci-local` (`npx ci-local`
 | --- | --- |
 | State of a run (queued, running, result) | `ci_local_status` tool if present; else `ci-local --status` (3 lines, no Docker) |
 | Pi extension active (footer shows `ci-local`) | Do not print waiting or completion blocks: the footer and the end card already do |
+| `ci_local_run` ended at once (`exited`) | Its output is the result: a usage or config error, `--list`, or a busy machine with `--no-wait` |
 | No extension | Paste the `ci-local --status` output once when the run starts and once when it ends |
 | Only some jobs | `--only JOBS` / `--skip TAGS`; a partial run never stands for the full one |
 | Inspect containers after a run | `--keep`, then `ci-local --down` |
@@ -37,7 +38,7 @@ Use when running, waiting on, reading, or configuring `ci-local` (`npx ci-local`
 ## Execution Steps
 
 1. Check the plan: `ci-local --list`.
-2. Start: `ci-local` in the background (`ci-local --quiet` before 0.5.0).
+2. Start: `ci_local_run` (arguments in `args`); without it, `ci-local` in the background (`ci-local --quiet` before 0.5.0).
 3. While waiting, keep working on something that does not touch the checkout, or report the `--status` block.
 4. On exit: status 0 passed, 1 failed, 2 usage/config error, 3 no turn (busy with `--no-wait`, or `CI_LOCAL_QUEUE_TIMEOUT` reached).
 5. Failed: open the failing step's log, fix, and run again; partial `--only` runs are fine while fixing, the final check is a full run.