@kabmo-labs/kabmo 0.0.1 → 0.2.0

package/src/server/lib/fs/listing.ts

@@ -17,9 +17,6 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { collectIgnoredPaths } from '@/server/lib/fs/git-ignore';
 
-/** Directory names never listed: build output and VCS metadata. */
-const NOISE_DIRS: Record<string, true> = { node_modules: true, '.git': true, dist: true, build: true };
-
 export interface DirectoryEntry {
   id: string;
   name: string;
@@ -30,13 +27,30 @@ export interface DirectoryEntry {
   ignored: boolean;
 }
 
-/** Read one directory, folders first then files, each marked ignored or not. */
+/**
+ * Read one directory, folders first then files, each marked ignored or not.
+ *
+ * EVERY entry is listed — `node_modules`, `.git`, `dist`, `build` and dot-files
+ * included. There is no name table: filtering by name cannot tell a dependency
+ * tree from a folder of release artifacts (`packages/android/dist` holds the
+ * built APKs), and it hid directories the user could not reach any other way.
+ * The panel's own signal for "this is untracked noise" is the `ignored` flag,
+ * which dims the row via `git check-ignore` instead of deleting it — and a tree
+ * that is expensive to expand costs nothing until someone expands it, because
+ * children are lazy.
+ */
 export async function listDirectoryEntries(dirPath: string, rootPath: string): Promise<DirectoryEntry[]> {
   const listed = (await fs.promises.readdir(dirPath))
-    .filter((child) => !NOISE_DIRS[child])
     .map((child) => {
       const full = path.join(dirPath, child);
-      return { child, full, rel: path.relative(rootPath, full) };
+      // POSIX spelling, because `rel` is not only a display value: it is the
+      // tree's id/key, the `fs:` topic's path, and the path handed to
+      // `git check-ignore` — which rejects a backslash outright, so on Windows
+      // every row came back un-dimmed and keyed `packages\android\dist`. The
+      // rest of the server states the same convention (`lib/fs/root.ts`,
+      // `lib/fs/transfer.ts`).
+      const rel = path.relative(rootPath, full).split(path.sep).join('/');
+      return { child, full, rel };
     });
 
   const ignored = await collectIgnoredPaths(rootPath, listed.map((entry) => entry.rel));

package/src/server/lib/lifecycle/restart.ts

@@ -20,9 +20,6 @@
  * launcher is what brings the new files up.
  */
 
-import { existsSync } from 'node:fs';
-import { join as joinPath } from 'node:path';
-
 import { resolveBunBin } from '@/server/lib/lifecycle/bun';
 import { packageDir } from '@/server/lib/fs/package-root';
 import { listInstanceRecords } from '@/server/lib/lifecycle/instance';
@@ -30,6 +27,7 @@ import { isCliManaged, resolveLaunchMode, unmanagedReason } from '@/server/lib/l
 import { capitalizeFirstLetter } from '@/shared/lib/chat/capitalize';
 import { loadAuthConfig } from '@/server/lib/auth/guard';
 import { PASSWORD_HANDOVER_ENV, PASSWORD_HANDOVER_STDIN, serializeHandover } from '@/shared/lib/auth/handover';
+import { copyAt, type InstalledCopy } from '@/server/lib/updates/installed-cli';
 import type { UpdateApplyResult } from '@/shared/types/updates';
 
 /**
@@ -87,11 +85,46 @@ function ownInstance(): { port: number; launchMode: string } | null {
   return { port, launchMode: resolveLaunchMode() };
 }
 
-/** `kabmo restart --port <port>` for the install this server runs from. */
-function restartCommand(port: number): string[] | null {
-  const cli = joinPath(PKG_ROOT, 'src', 'cli', 'kabmo.js');
-  if (!existsSync(cli)) return null;
-  return [resolveBunBin(), cli, 'restart', '--port', String(port)];
+/**
+ * The marker the TARGET copy reads its credential through.
+ *
+ * The rename renamed the variable too (`OMPCHAMBER_PASSWORD_HANDOVER` →
+ * `KABMO_PASSWORD_HANDOVER`), so a restart that set only one spelling would
+ * hand a payload to a CLI that never looks for it — and the replacement would
+ * come back with authentication silently disabled. Keyed by package name
+ * because that is the only fact about the target this process can read.
+ */
+const HANDOVER_ENV_BY_PACKAGE: Record<string, string> = {
+  'ompchamber': 'OMPCHAMBER_PASSWORD_HANDOVER',
+  '@kabmo-labs/kabmo': PASSWORD_HANDOVER_ENV,
+};
+
+export interface RestartInvocation {
+  /** argv for the detached helper: `<bun> <cli> restart --port <port>`. */
+  cmd: string[];
+  /** The variable that CLI reads its credential marker from. */
+  handoverEnv: string;
+  /** Package root the helper runs in. */
+  root: string;
+}
+
+/**
+ * How to restart the copy rooted at `root`.
+ *
+ * The CLI is that copy's OWN registered bin, resolved from its `package.json`,
+ * because the file name is not a constant across a rename: a renamed package
+ * ships only the bin it declares, so a hard-coded `kabmo.js` finds nothing in
+ * a copy that names it something else. Null when the root holds no runnable
+ * copy.
+ */
+export function restartInvocation(port: number, root: string): RestartInvocation | null {
+  const copy = copyAt(root);
+  if (!copy) return null;
+  return {
+    cmd: [resolveBunBin(), copy.cli, 'restart', '--port', String(port)],
+    handoverEnv: HANDOVER_ENV_BY_PACKAGE[copy.packageName] ?? PASSWORD_HANDOVER_ENV,
+    root: copy.root,
+  };
 }
 
 /**
@@ -127,7 +160,7 @@ export function withRestartPlan(result: UpdateApplyResult, plan: SelfRestartPlan
  * helper is detached so this process exiting does not take it down, and it
  * removes this port's record itself (`stopInstance`) before serving.
  */
-export function scheduleSelfRestart(purpose: SelfRestartPurpose = 'update'): SelfRestartPlan {
+export function scheduleSelfRestart(purpose: SelfRestartPurpose = 'update', installed: InstalledCopy | null = null): SelfRestartPlan {
   const self = ownInstance();
   if (!self) {
     const nextStep = purpose === 'restart' ? 'restart it yourself' : 'restart it yourself to apply the update';
@@ -138,11 +171,16 @@ export function scheduleSelfRestart(purpose: SelfRestartPurpose = 'update'): Sel
     return { restarting: false, message: skipRestartNote(self.launchMode, purpose) };
   }
 
-  const cmd = restartCommand(self.port);
-  if (!cmd) {
+  // The copy that must come back is the one the update INSTALLED. Falling back
+  // to this process's own root keeps `Restart` (which installs nothing) and a
+  // caller that could not read the install working as before.
+  const root = installed?.root ?? PKG_ROOT;
+  const invocation = restartInvocation(self.port, root);
+  if (!invocation) {
     const nextStep = purpose === 'restart' ? 'restart it yourself' : 'restart it yourself to apply the update';
-    return { restarting: false, message: `The kabmo CLI is missing from ${PKG_ROOT} — ${nextStep}.` };
+    return { restarting: false, message: `The CLI is missing from ${root} — ${nextStep}.` };
   }
+  const { cmd, handoverEnv } = invocation;
 
   // The replacement must come up with the SAME credential this process is
   // serving under. Without it, a restart silently disables authentication —
@@ -160,7 +198,7 @@ export function scheduleSelfRestart(purpose: SelfRestartPurpose = 'update'): Sel
     try {
       const child = Bun.spawn({
         cmd,
-        cwd: PKG_ROOT,
+        cwd: root,
         stdin: credential ? 'pipe' : 'ignore',
         stdout: 'inherit',
         stderr: 'inherit',
@@ -169,7 +207,7 @@ export function scheduleSelfRestart(purpose: SelfRestartPurpose = 'update'): Sel
         // CLI forwards it to the server it spawns, which is the only place it
         // is ever read.
         env: credential
-          ? { ...Bun.env, [PASSWORD_HANDOVER_ENV]: PASSWORD_HANDOVER_STDIN }
+          ? { ...Bun.env, [handoverEnv]: PASSWORD_HANDOVER_STDIN }
           : Bun.env,
       });
       if (credential && child.stdin) {

package/src/server/lib/omp/session/delete-flow.server.ts

@@ -0,0 +1,101 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The one session-removal sequence, shared by the single DELETE route and the
+ * batch route.
+ *
+ * The ORDER is the contract and it is enforced here, not by the callers:
+ *  1. refuse a pending `new-…` chat and an id that is not one path segment —
+ *     both name something other than the session they appear to;
+ *  2. refuse a session whose omp child is mid-turn (a run, a live subagent, or
+ *     a dialog the agent is blocked on) — the delete would kill work the user
+ *     can still see, and omp would flush the file back on shutdown anyway;
+ *  3. destroy the child and AWAIT its exit — omp writes session state on
+ *     shutdown and would otherwise recreate the transcript just removed;
+ *  4. purge side questions, then the transcript, artifacts and Kabmo rows.
+ *
+ * A batch that re-implemented any of this would drift from the single delete,
+ * and the drift would be silent: the route answers per-id verdicts either way.
+ */
+
+import { getRpcSession } from '@/server/lib/omp/rpc/session-registry';
+import { purgeSessionData } from '@/server/lib/omp/session/delete.server';
+import { purgeBtwForSession } from '@/server/lib/btw/purge.server';
+import { isSinglePathSegment } from '@/server/lib/fs/path-segment';
+import { isMockMode } from '@/server/mock.server';
+
+export interface SessionRemoval {
+  /** True when the session was removed (or would have been, in mock mode). */
+  ok: boolean;
+  /** HTTP status the single-session route answers with; batch callers use `error`. */
+  status: number;
+  code?: 'session_pending' | 'invalid_id' | 'session_busy' | 'not_found';
+  error?: string;
+  fileRemoved?: boolean;
+  artifactsRemoved?: boolean;
+  btwTopicsRemoved?: number;
+}
+
+/**
+ * Remove one session, in the documented order. Never throws: every failure is
+ * a verdict, because a batch has to keep going after one refused id.
+ */
+export async function removeSession(sessionId: string): Promise<SessionRemoval> {
+  if (sessionId.startsWith('new-')) {
+    return {
+      ok: false,
+      status: 400,
+      code: 'session_pending',
+      error: 'This chat has not been created yet.',
+    };
+  }
+  // The id names a directory under the sessions root and another under the btw
+  // root, so it must be exactly one path segment — see `isSinglePathSegment`
+  // for the `.` case that made this load-bearing.
+  if (!isSinglePathSegment(sessionId)) {
+    return { ok: false, status: 400, code: 'invalid_id', error: 'Invalid session id' };
+  }
+
+  try {
+    // A live child is the only other writer of the transcript. Busy means a
+    // turn, a live subagent, or a dialog omp is parked on.
+    const live = getRpcSession(sessionId);
+    if (live?.isAlive()) {
+      if (live.isBusy()) {
+        return {
+          ok: false,
+          status: 409,
+          code: 'session_busy',
+          error: 'This session is working. Stop the run before deleting it.',
+        };
+      }
+      await live.destroyAndWait();
+    }
+
+    // Side questions live outside the session file and are removed first: their
+    // children must be gone before the parent transcript they were snapshotted
+    // from disappears.
+    const btwTopicsRemoved = isMockMode() ? 0 : await purgeBtwForSession(sessionId);
+    const purged = await purgeSessionData(sessionId);
+    if (!purged.found) {
+      return { ok: false, status: 404, code: 'not_found', error: 'Session not found' };
+    }
+
+    return {
+      ok: true,
+      status: 200,
+      fileRemoved: purged.fileRemoved,
+      artifactsRemoved: purged.artifactsRemoved,
+      btwTopicsRemoved,
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      status: 500,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}

package/src/server/lib/updates/android-release.test.ts

@@ -0,0 +1,92 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { beforeEach, describe, expect, test } from 'bun:test';
+
+import {
+  fetchAndroidRelease,
+  resetAndroidReleaseCache,
+  versionFromAssetName,
+} from '@/server/lib/updates/android-release';
+
+/**
+ * The asset name is the only place the APK's version exists: the release TAG
+ * names the SERVER version, and the two move independently. A parser that read
+ * the tag would compare a server version against an APK version.
+ */
+describe('versionFromAssetName', () => {
+  test('reads the version the release workflow writes', () => {
+    expect(versionFromAssetName('kabmo-android-v1.2.3.apk')).toBe('1.2.3');
+  });
+
+  test('accepts a hand-uploaded name without the v', () => {
+    expect(versionFromAssetName('kabmo-android-1.2.3.apk')).toBe('1.2.3');
+  });
+
+  test('ignores anything that is not the APK', () => {
+    expect(versionFromAssetName('kabmo-android-v1.2.3.apk.zip')).toBeNull();
+    expect(versionFromAssetName('source.tar.gz')).toBeNull();
+    expect(versionFromAssetName('kabmo-android-latest.apk')).toBeNull();
+    expect(versionFromAssetName('')).toBeNull();
+  });
+});
+
+/** A fetch double that answers one body, and counts its calls. */
+function stubFetch(body: unknown, ok = true) {
+  const calls: string[] = [];
+  const impl = (async (input: string | URL | Request) => {
+    calls.push(String(input));
+    return {
+      ok,
+      json: async () => body,
+    } as Response;
+  }) as unknown as typeof fetch;
+  return { impl, calls };
+}
+
+describe('fetchAndroidRelease', () => {
+  // The cache is process-wide (see `resetAndroidReleaseCache`), so every case
+  // starts from a cold one or it reads the previous case's answer.
+  beforeEach(() => resetAndroidReleaseCache());
+
+  test('picks the APK asset and its version', async () => {
+    const { impl } = stubFetch({
+      html_url: 'https://github.com/kabmo-labs/kabmo/releases/tag/v9.9.9',
+      assets: [
+        { name: 'source.tar.gz', browser_download_url: 'https://x/src.tgz' },
+        {
+          name: 'kabmo-android-v1.2.3.apk',
+          browser_download_url: 'https://x/kabmo-android-v1.2.3.apk',
+        },
+      ],
+    });
+
+    const release = await fetchAndroidRelease(impl);
+    expect(release).toEqual({
+      url: 'https://x/kabmo-android-v1.2.3.apk',
+      latest: '1.2.3',
+      releaseUrl: 'https://github.com/kabmo-labs/kabmo/releases/tag/v9.9.9',
+    });
+  });
+
+  test('answers null for a release with no APK', async () => {
+    const { impl } = stubFetch({ html_url: 'https://x', assets: [{ name: 'notes.md' }] });
+    const release = await fetchAndroidRelease(impl);
+    expect(release).toEqual({ url: null, latest: null, releaseUrl: 'https://x' });
+  });
+
+  test('answers null when the probe fails', async () => {
+    // An offline box or a rate-limited GitHub must not take the sidebar down,
+    // and a failure must not be read as "no newer version" either — it is
+    // simply no offer.
+    const { impl } = stubFetch({}, false);
+    expect(await fetchAndroidRelease(impl)).toBeNull();
+  });
+
+  test('answers null when the body is malformed', async () => {
+    const { impl } = stubFetch({ assets: 'nope' });
+    expect(await fetchAndroidRelease(impl)).toBeNull();
+  });
+});

package/src/server/lib/updates/android-release.ts

@@ -0,0 +1,148 @@
+/**
+ * Which Android APK a browser should download, and whether this one is behind.
+ *
+ * The APK is NOT an npm package (see `.github/workflows/publish-android.yml`), so
+ * the npm probe that answers for the app and for `omp` cannot answer here. The
+ * only record of a published APK is the GitHub release asset, which means one
+ * unauthenticated REST read of the newest release.
+ *
+ * Two facts travel back, and they answer different questions:
+ *
+ * - `url` is the asset to download. It is resolved from the release's OWN asset
+ *   list rather than built as `releases/latest/download/<name>`, because that
+ *   path needs the asset name to match exactly and the name carries the tag
+ *   (`kabmo-android-v1.2.3.apk`) — a name built here would be a second copy of
+ *   the workflow's naming rule, and the first release that renames it 404s.
+ * - `latest` is the version that asset ships, read from the asset name. The
+ *   release TAG cannot be used: the APK is attached to the app's release, whose
+ *   tag names the SERVER version, and the two move independently.
+ *
+ * Failure is a normal answer here (`null`), never a throw: an offline box or a
+ * rate-limited GitHub must not take the sidebar down, and a button that appears
+ * because a probe failed would offer a download that does not exist.
+ */
+
+import { REPO } from '@/server/lib/updates/release-url';
+
+/** One published APK, as the console needs it. */
+export interface AndroidRelease {
+  /** Asset download URL, or null when the release carries no APK. */
+  url: string | null;
+  /** Version the asset name declares (`v1.2.3` → `1.2.3`), or null. */
+  latest: string | null;
+  /** The release page, for a "what changed" link. */
+  releaseUrl: string | null;
+}
+
+/** The asset-name prefix the release workflow writes. */
+const ASSET_PREFIX = 'kabmo-android-';
+
+/**
+ * `kabmo-android-v1.2.3.apk` → `1.2.3`.
+ *
+ * The `v` is optional because a hand-uploaded asset may omit it, and a version
+ * that cannot be read is not evidence of an update — the caller treats null as
+ * "no new version".
+ */
+export function versionFromAssetName(name: string): string | null {
+  if (!name.startsWith(ASSET_PREFIX) || !name.endsWith('.apk')) return null;
+  const middle = name.slice(ASSET_PREFIX.length, -'.apk'.length);
+  const version = middle.startsWith('v') ? middle.slice(1) : middle;
+  return /^\d+\.\d+\.\d+/.test(version) ? version : null;
+}
+
+/**
+ * The newest release's APK.
+ *
+ * One request, cached for five minutes on `globalThis` for the same reason the
+ * database handle is anchored there: `bun --hot` re-evaluates this module while
+ * the cache it would otherwise hold lives on. GitHub allows 60 unauthenticated
+ * reads an hour per address, and the sidebar asks on every mount.
+ */
+export async function fetchAndroidRelease(fetchImpl: typeof fetch = fetch): Promise<AndroidRelease | null> {
+  const cache = cacheSlot();
+  const now = Date.now();
+  if (cache.entry && now - cache.at < CACHE_MS) return cache.entry;
+
+  try {
+    const response = await fetchImpl(`${githubApiBase()}/repos/${REPO}/releases/latest`, {
+      headers: {
+        accept: 'application/vnd.github+json',
+        // GitHub rejects a request with no User-Agent.
+        'user-agent': 'kabmo-console',
+      },
+    });
+    if (!response.ok) return cache.entry ?? null;
+
+    const body = (await response.json()) as {
+      html_url?: unknown;
+      assets?: unknown;
+    };
+    // A body that is not the release document is a failed probe, not an empty
+    // release: answering `{url: null, latest: null}` here would be
+    // indistinguishable from "a release with no APK", and the caller would cache
+    // that mistake for five minutes.
+    if (!Array.isArray(body.assets)) return cache.entry ?? null;
+
+    const assets = body.assets;
+    const asset = assets
+      .map((entry) => (entry && typeof entry === 'object' ? (entry as Record<string, unknown>) : null))
+      .find((entry) => entry && typeof entry.name === 'string' && versionFromAssetName(entry.name) !== null);
+
+    const name = typeof asset?.name === 'string' ? asset.name : '';
+    const url = typeof asset?.browser_download_url === 'string' ? asset.browser_download_url : null;
+    const release: AndroidRelease = {
+      url,
+      latest: versionFromAssetName(name),
+      releaseUrl: typeof body.html_url === 'string' ? body.html_url : null,
+    };
+
+    cache.entry = release;
+    cache.at = now;
+    return release;
+  } catch {
+    // Keep the last good answer rather than replacing it with a failure: a
+    // momentary outage must not remove a download button that was valid.
+    return cache.entry ?? null;
+  }
+}
+
+const CACHE_MS = 5 * 60_000;
+
+/**
+ * Where the release read goes.
+ *
+ * Overridable for the same reason the npm probe honours `NPM_CONFIG_REGISTRY`: a
+ * test and a rehearsal need to exercise the real parsing against a stub instead
+ * of a live GitHub call, and hardcoding the host makes that impossible without
+ * intercepting `fetch` globally.
+ */
+function githubApiBase(): string {
+  const configured = Bun.env.KABMO_GITHUB_API ?? '';
+  return configured.trim().replace(/\/+$/, '') || 'https://api.github.com';
+}
+
+interface CacheSlot {
+  entry: AndroidRelease | null;
+  at: number;
+}
+
+function cacheSlot(): CacheSlot {
+  const host = globalThis as typeof globalThis & { __kabmoAndroidRelease?: CacheSlot };
+  host.__kabmoAndroidRelease ??= { entry: null, at: 0 };
+  return host.__kabmoAndroidRelease;
+}
+
+/**
+ * Drop the cached answer.
+ *
+ * The cache lives on `globalThis` so `bun --hot` cannot orphan it, which also
+ * means it outlives a test file: without this seam the second case in a suite
+ * reads the first case's answer and passes for the wrong reason (measured — the
+ * "malformed body" case returned the previous test's release). Production has no
+ * caller; it exists because the cache is process-wide by design.
+ */
+export function resetAndroidReleaseCache(): void {
+  cacheSlot().entry = null;
+  cacheSlot().at = 0;
+}

package/src/server/lib/updates/apply.ts

@@ -12,6 +12,7 @@ import { updateKabmo } from '@/server/lib/updates/install';
 import { applyOmpUpdate } from '@/server/lib/updates/omp';
 import { withUpdateSlot } from '@/server/lib/updates/single-flight';
 import { recycleStandbyProcesses } from '@/server/lib/omp/session/standby.server';
+import type { InstalledCopy } from '@/server/lib/updates/installed-cli';
 import type { UpdateApplyResult, UpdateTarget } from '@/shared/types/updates';
 
 /** A stage label or a line of command output, as the update produces it. */
@@ -27,6 +28,12 @@ export interface UpdateProgressHooks {
 export interface AppliedUpdate {
   result: UpdateApplyResult;
   updated: boolean;
+  /**
+   * The copy this run left on disk, when it knows. The restart that follows
+   * launches THIS one — the running process's own directory is the build the
+   * update just replaced, which is how a rename came back as the old product.
+   */
+  installed?: InstalledCopy | null;
 }
 
 /**
@@ -74,6 +81,7 @@ export async function applyUpdate(target: UpdateTarget, hooks: UpdateProgressHoo
           output: result.output || undefined,
         },
         updated: result.updated,
+        installed: result.installed,
       };
     }
 

package/src/server/lib/updates/install-steps.ts

@@ -0,0 +1,81 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Running one update step, and reading a child's output as it arrives.
+ *
+ * Split out of `./install` because the parent file sits at the repository's
+ * per-file ceiling and this half is a self-contained child-process concern: a
+ * synchronous probe used for git facts, one step runner, and the streaming
+ * drain both the Kabmo and the oh-my-pi update paths share.
+ */
+
+/** A client rebuild is slow, but a hung child is worse. */
+export const STEP_TIMEOUT_MS = 600_000;
+/** Cap on the captured output returned to the console. */
+export const OUTPUT_LIMIT = 20_000;
+
+export interface UpdateStep {
+  label: string;
+  cmd: string[];
+  cwd: string;
+}
+
+export function runSync(cmd: string[], cwd?: string): { ok: boolean; out: string } {
+  try {
+    const proc = Bun.spawnSync({
+      cmd,
+      cwd,
+      stdin: 'ignore',
+      stdout: 'pipe',
+      stderr: 'pipe',
+      timeout: 15_000,
+    });
+    return { ok: proc.exitCode === 0, out: proc.stdout.toString().trim() };
+  } catch {
+    return { ok: false, out: '' };
+  }
+}
+
+/**
+ * Drain a child's stdout/stderr, forwarding each chunk to `sink` as it arrives
+ * and returning the whole decoded text. Exported because the omp update path
+ * needs the same streaming read: buffering with `new Response(stream).text()`
+ * emits nothing until the process exits, which is exactly what makes an update
+ * look hung.
+ */
+export async function pumpStream(stream: ReadableStream<Uint8Array>, sink?: (chunk: string) => void): Promise<string> {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let text = '';
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    const chunk = decoder.decode(value, { stream: true });
+    if (chunk.length === 0) continue;
+    text += chunk;
+    sink?.(chunk);
+  }
+  return text;
+}
+
+export async function runStep(step: UpdateStep, onLine?: (chunk: string) => void): Promise<{ ok: boolean; exitCode: number | null; output: string }> {
+  const proc = Bun.spawn({
+    cmd: step.cmd,
+    cwd: step.cwd,
+    stdin: 'ignore',
+    stdout: 'pipe',
+    stderr: 'pipe',
+    timeout: STEP_TIMEOUT_MS,
+    env: { ...Bun.env, PAGER: 'cat', FORCE_COLOR: '0' },
+  });
+  const [stdout, stderr] = await Promise.all([pumpStream(proc.stdout, onLine), pumpStream(proc.stderr, onLine)]);
+  const exitCode = await proc.exited;
+  return { ok: exitCode === 0, exitCode, output: `${stdout}${stderr}`.trim() };
+}
+
+export function tail(text: string): string {
+  return text.length > OUTPUT_LIMIT ? `…\n${text.slice(-OUTPUT_LIMIT)}` : text;
+}