@linxiraos/pi-utils 1.1.5 → 1.1.7

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## [Unreleased]
 
+## [1.1.7] - 2026-09-01
+
+- 同步上游 OMP v18.0.11（`b8ce33a58911c26bed1d84f0db9a5e2e727c49a2`）。
+
+## [1.1.6] - 2026-08-30
+
+- 同步上游 OMP v18.0.10（`33cc6b9a043a`）。
+- 同步上游 OMP v18.0.9（`cc14e04f075d`）。
+
 ## [1.1.5] - 2026-08-26
 
 - 同步上游 OMP v18.0.5 / v18.0.6：新增 browsers / json 工具，SHA-2/SHA-3 在 ARM64 上加速。

package/README.md

@@ -17,6 +17,7 @@ Shared utilities for [Zeta](https://github.com/Linxira-OS/linxira-zeta) packages
 | `fs-error` | Errno guards (`isEnoent` and friends) |
 | `env` / `worker-host` | Environment plumbing and side-effect-free worker-host entry contract (`workerHostEntry`) |
 | `abortable` / `async` | AbortSignal-aware stream/promise helpers |
+| `math-delimiters` | LaTeX span/block delimiter grammar (offsets only) shared by the TUI and collab-web renderers |
 | `peek-file` | Read the first N bytes of a file with pooled buffers |
 | `frontmatter`, `glob`, `mime`, `temp`, `format`, `color`, `snowflake`, `tab-spacing`, `path-tree`, `sanitize-text` | Smaller single-purpose helpers |
 

package/dist/types/acp/transport.d.ts

@@ -55,6 +55,13 @@ export declare class RequestError extends Error {
     static authRequired(data?: unknown, additionalMessage?: string): RequestError;
     /** Creates a resource-not-found error. */
     static resourceNotFound(uri?: string): RequestError;
+    /**
+     * Creates a session-busy error: the agent/session is already processing, so the
+     * request can be retried once idle (steer/follow-up/wait) instead of treating it
+     * as a fault. `message` carries the caller's user-facing wording; `data` should
+     * keep the stable discriminator shape (`reason: "session_busy"`).
+     */
+    static sessionBusy(message: string, data?: unknown): RequestError;
     /** Converts this error into a JSON-RPC result. */
     toResult(): {
         error: ErrorResponse;

package/dist/types/async.d.ts

@@ -17,4 +17,6 @@ export declare class AsyncDrain<T> {
     constructor(delayMs?: number);
     /** Queue `value`; `hnd` receives the whole batch when the window closes. */
     push(value: T, hnd: (values: T[]) => Promise<void> | void): Promise<void>;
+    /** Runs the pending batch handler immediately and returns its completion promise. */
+    flush(): Promise<void>;
 }

package/dist/types/color.d.ts

@@ -82,6 +82,40 @@ export declare function adjustHsv(hex: string, adj: HSVAdjustment): string;
  * Convert HSL (h: 0-360, s: 0-1, l: 0-1) to a CSS hex string.
  */
 export declare function hslToHex(h: number, s: number, l: number): string;
+export interface OKLCH {
+    /** Perceptual lightness (0-1) */
+    l: number;
+    /** Chroma (0 = gray; sRGB peaks around 0.37) */
+    c: number;
+    /** Hue in degrees (0-360) */
+    h: number;
+}
+/**
+ * Convert a hex color to OKLCH (perceptual lightness/chroma/hue).
+ *
+ * Unlike HSL, equal `l`/`c` values look equally bright and colorful across
+ * hues, so carrying them between colors preserves the palette's "weight".
+ */
+export declare function hexToOklch(hex: string): OKLCH;
+/**
+ * The sRGB gamut cusp for an OKLCH hue: the lightness/chroma point where the
+ * hue reaches its maximum chroma inside sRGB.
+ *
+ * The cusp lightness varies wildly per hue (yellow ≈ 0.97, blue ≈ 0.45), so
+ * transferring absolute OKLCH lightness/chroma between hues distorts
+ * vividness; normalize against the cusp instead. See `getSessionAccentHex`.
+ */
+export declare function oklchCusp(h: number): {
+    l: number;
+    c: number;
+};
+/**
+ * Convert OKLCH to a CSS hex string, gamut-mapping by chroma reduction.
+ *
+ * Out-of-gamut inputs keep their lightness and hue while chroma is bisected
+ * down until the color fits sRGB, matching CSS Color 4's recommended intent.
+ */
+export declare function oklchToHex(oklch: OKLCH): string;
 /**
  * Perceptual luma (gamma-encoded BT.709 weights over raw sRGB), normalized to 0..1.
  *

package/dist/types/dirs.d.ts

@@ -1,16 +1,16 @@
 /**
- * Centralized path helpers for omp config directories.
+ * Centralized path helpers for zeta config directories.
  *
  * Uses PI_CONFIG_DIR (default ".zeta") for the config root and
  * PI_CODING_AGENT_DIR to override the agent directory.
  *
  * On Linux, if XDG_DATA_HOME / XDG_STATE_HOME / XDG_CACHE_HOME environment
  * variables are set, paths are redirected to XDG-compliant locations under
- * $XDG_*_HOME/omp/. This requires running `zeta config migrate` first to
+ * $XDG_*_HOME/zeta/. This requires running `zeta config migrate` first to
  * move data to the new locations. No filesystem existence checks are performed
  * — if the env var is set, omp trusts that the migration has been done.
  */
-/** App name (e.g. "zeta") */
+/** App name (e.g. "omp") */
 export declare const APP_NAME: string;
 /** Config directory name (e.g. ".zeta") */
 export declare const CONFIG_DIR_NAME: string;
@@ -18,7 +18,7 @@ export declare const CONFIG_DIR_NAME: string;
 export declare const MAIN_CONFIG_FILENAMES: readonly ["config.yml", "config.yaml"];
 /** Version (e.g. "1.0.0") */
 export declare const VERSION: string;
-/** Default User-Agent header string (e.g. "zeta/1.0.10") */
+/** Default User-Agent header string (e.g. "zeta/1.1.5") */
 export declare const USER_AGENT: string;
 /** Minimum Bun version */
 export declare const MIN_BUN_VERSION: string;
@@ -48,6 +48,10 @@ export declare function relativePathWithinRoot(root: string, candidate: string):
 export declare function getProjectDir(): string;
 /** Set the project directory. */
 export declare function setProjectDir(dir: string): void;
+/** Reset the cached project directory (test seam). */
+export declare function __resetProjectDirCacheForTests(): void;
+/** Whether a path is absent or not a directory. Other stat failures return false. */
+export declare function directoryIsMissing(dir: string): Promise<boolean>;
 /**
  * Whether `dir` resolves to an existing directory. Any stat failure — a deleted
  * path (ENOENT), permission error, or a non-directory — returns `false`, so
@@ -55,16 +59,23 @@ export declare function setProjectDir(dir: string): void;
  * working directory before {@link setProjectDir} throws on it.
  */
 export declare function directoryExists(dir: string): Promise<boolean>;
-/** Get the config directory name relative to home (e.g. ".zeta" or PI_CONFIG_DIR override). */
-export declare function getConfigDirName(): string;
 /**
- * One-time migration of a legacy `~/.omp` config root to `~/.zeta`. Called
- * from the CLI entrypoint before any user data is written; it only moves the
- * directory when `.zeta` does not exist yet. Zeta keeps no `.omp`
- * compatibility surface afterwards (see AGENTS.md), so this is the single
- * exception that honors pre-existing installs.
+ * Whether `dir` both exists and can be entered. POSIX `stat` succeeds for a
+ * directory whose own search/execute permission is denied (it only needs
+ * +x on the parent chain), so existence alone does not imply `chdir` works.
+ * Callers that adopt a directory as a working directory must check this
+ * rather than {@link directoryExists} alone.
  */
-export declare function migrateLegacyOmpConfigDir(): void;
+export declare function directoryIsEnterable(dir: string): Promise<boolean>;
+/** Whether `dir` is enterable, synchronous variant. See {@link directoryIsEnterable}. */
+export declare function directoryIsEnterableSync(dir: string): boolean;
+/**
+ * Project directory when it is enterable, otherwise a safe fallback.
+ * Used by spawns that must preserve project-relative behavior when healthy.
+ */
+export declare function getSafeProjectCwd(): string;
+/** Get the config directory name relative to home (e.g. ".zeta" or PI_CONFIG_DIR override). */
+export declare function getConfigDirName(): string;
 /** Get the config agent directory name relative to home (e.g. ".zeta/agent" or PI_CONFIG_DIR + "/agent"). */
 export declare function getConfigAgentDirName(): string;
 /**
@@ -112,7 +123,7 @@ export declare function getProjectAgentDir(cwd?: string): string;
 export declare function getReportsDir(): string;
 /** Get the logs directory (~/.zeta/logs). */
 export declare function getLogsDir(): string;
-/** Get this process's dated log path (~/.zeta/logs/zeta.YYYY-MM-DD.PID.log). */
+/** Get this process's dated log path (~/.zeta/logs/omp.YYYY-MM-DD.PID.log). */
 export declare function getLogPath(date?: Date, pid?: number): string;
 /**
  * Get the plugins directory (~/.zeta/plugins or its XDG equivalent).
@@ -129,13 +140,13 @@ export declare function getPluginsDir(home?: string): string;
 export declare function getPluginsNodeModules(home?: string): string;
 /** Plugin manifest (~/.zeta/plugins/package.json). */
 export declare function getPluginsPackageJson(home?: string): string;
-/** Plugin lock file (~/.zeta/plugins/zeta-plugins.lock.json). */
+/** Plugin lock file (~/.zeta/plugins/omp-plugins.lock.json). */
 export declare function getPluginsLockfile(home?: string): string;
 /** Get the remote mount directory (~/.zeta/remote). */
 export declare function getRemoteDir(): string;
 /**
  * Relocate the base directory for agent-managed worktrees (PR checkouts, task
- * isolation, and `zeta worktree` cleanup all read the same base). Driven by the
+ * isolation, and `omp worktree` cleanup all read the same base). Driven by the
  * `worktree.base` setting in coding-agent; pass `undefined`/empty to clear and
  * fall back to `OMP_WORKTREE_DIR` or the `~/.zeta/wt` default.
  *
@@ -190,7 +201,7 @@ export declare function getGpuCachePath(): string;
  */
 export declare function getGithubCacheDbPath(): string;
 /**
- * Get the conventional commit inference cache database path (~/.omp/cache/commit-inference.db).
+ * Get the conventional commit inference cache database path (~/.zeta/cache/commit-inference.db).
  * Honors `OMP_COMMIT_CACHE_DB` so tests and operators can isolate the cache.
  */
 export declare function getCommitCacheDbPath(): string;
@@ -202,10 +213,9 @@ export declare function getLegacyPiExtensionCacheDbPath(): string;
  * operators can isolate or relocate the cache file.
  */
 export declare function getAuthBrokerSnapshotCachePath(): string;
-/** Get the local FastEmbed model cache directory (~/.zeta/cache/fastembed). */
-/** Get the commit-author avatar cache directory (~/.omp/cache/avatars). */
+/** Get the commit-author avatar cache directory (~/.zeta/cache/avatars). */
 export declare function getAvatarCacheDir(): string;
-/** Get the local FastEmbed model cache directory (~/.omp/cache/fastembed). */
+/** Get the local FastEmbed model cache directory (~/.zeta/cache/fastembed). */
 export declare function getFastembedCacheDir(): string;
 /** Get the on-demand fastembed runtime install root (~/.zeta/cache/fastembed-runtime). */
 export declare function getFastembedRuntimeDir(): string;
@@ -237,6 +247,8 @@ export declare function getModelDbPath(agentDir?: string): string;
 export declare function getTinyModelsCacheDir(agentDir?: string): string;
 /** Get the document conversion cache directory (~/.zeta/agent/cache/document-conversions; XDG default: $XDG_CACHE_HOME/zeta/cache/document-conversions). */
 export declare function getDocumentConversionCacheDir(agentDir?: string): string;
+/** Get the per-project composer speculative cache directory (~/.zeta/agent/cache/composer; XDG default: $XDG_CACHE_HOME/zeta/cache/composer). */
+export declare function getComposerCacheDir(agentDir?: string): string;
 /** Get the sessions directory (~/.zeta/agent/sessions). */
 export declare function getSessionsDir(agentDir?: string): string;
 /** Get the content-addressed blob store directory (~/.zeta/agent/blobs). */
@@ -255,9 +267,9 @@ export declare function getAgentModulesDir(agentDir?: string): string;
 export declare function getMemoriesDir(agentDir?: string): string;
 /** Get the terminal sessions directory (~/.zeta/agent/terminal-sessions). */
 export declare function getTerminalSessionsDir(agentDir?: string): string;
-/** Get the crash log path (~/.zeta/agent/zeta-crash.log). */
+/** Get the crash log path (~/.zeta/agent/omp-crash.log). */
 export declare function getCrashLogPath(agentDir?: string): string;
-/** Get the debug log path (~/.zeta/agent/zeta-debug.log). */
+/** Get the debug log path (~/.zeta/agent/omp-debug.log). */
 export declare function getDebugLogPath(agentDir?: string): string;
 /** Get the secret placeholder key path (~/.zeta/agent/secret-placeholder.key; XDG default: $XDG_STATE_HOME/zeta/secret-placeholder.key). Adopts a legacy key on first XDG resolution. */
 export declare function getSecretPlaceholderKeyPath(): string;
@@ -283,10 +295,13 @@ export declare function getProjectPluginOverridesPath(cwd?: string): string;
 export declare function getMCPConfigPath(scope: "user" | "project", cwd?: string): string;
 /** Get the SSH config file path. */
 export declare function getSSHConfigPath(scope: "user" | "project", cwd?: string): string;
-/** Get the project-level tracking directory (<project>/.zeta/tracking). */
-export declare function getProjectTrackingDir(cwd?: string): string;
-/** Get the global tracking index path (~/.zeta/agent/tracking-index.json). */
-export declare function getTrackingIndexPath(agentDir?: string): string;
+/**
+ * Application label for usage attribution (`OMP_APP_NAME`), defaulting to
+ * `omp`. Embedders that drive omp programmatically (robomp, CI bots, …) set
+ * the env var so broker-side per-client burn tracking can answer "what did
+ * app X use" instead of folding everything into one install-wide bucket.
+ */
+export declare function getAppName(): string;
 /**
  * Persistent per-install UUID stored at `~/.zeta/install-id`.
  *
@@ -304,3 +319,7 @@ export declare function getTrackingIndexPath(agentDir?: string): string;
 export declare function getInstallId(): string;
 /** Test-only: clear cached install id. Never call from production code. */
 export declare function __resetInstallIdCacheForTests(): void;
+/** Get the project-level tracking directory (<project>/.zeta/tracking). */
+export declare function getProjectTrackingDir(cwd?: string): string;
+/** Get the global tracking index path (~/.zeta/agent/tracking-index.json). */
+export declare function getTrackingIndexPath(agentDir?: string): string;

package/dist/types/index.d.ts

@@ -14,6 +14,7 @@ export * from "./json.js";
 export * from "./json-parse.js";
 export * as logger from "./logger.js";
 export * from "./loop-phase.js";
+export * from "./math-delimiters.js";
 export * from "./mermaid-ascii.js";
 export * from "./mime.js";
 export * from "./path.js";

package/dist/types/math-delimiters.d.ts

@@ -0,0 +1,45 @@
+/**
+ * LaTeX delimiter grammar for agent-authored Markdown: where does a math span
+ * begin and end, in source offsets. Carries no rendering policy — what to do
+ * with an unclosed opener, whether a body is typesettable, and how it is
+ * displayed belong to the renderer (Unicode in the TUI, KaTeX in collab web).
+ */
+/** Opening delimiter. Each closer (`$`, `$$`, `\)`, `\]`) is as wide as its opener. */
+export type MathOpener = "$" | "$$" | "\\(" | "\\[";
+/** A closed math span found in the source. */
+export interface MathSpan {
+    opener: MathOpener;
+    /** True for the display forms `$$…$$` and `\[…\]`. */
+    display: boolean;
+    /** Offset one past the closing delimiter. */
+    end: number;
+    /** Source between the delimiters, verbatim. */
+    body: string;
+}
+/** An own-line display block: opener and closer each alone on their line. */
+export interface MathBlock {
+    /** Both delimiter lines, the body, and the trailing newline. */
+    raw: string;
+    body: string;
+}
+/**
+ * Leftmost offset at or after `from` where an opener could begin. A scan hint,
+ * not a decision: whether that candidate is really math — escaped, currency,
+ * unclosed — is decided by {@link mathSpanAt}.
+ */
+export declare function mathStartIndex(source: string, from?: number): number | undefined;
+/** Math opener at `at`, or `undefined` when no delimiter starts there. */
+export declare function mathOpenerAt(source: string, at: number): MathOpener | undefined;
+/**
+ * The span opened at `at`, or `undefined` when the run is not math — including
+ * an opener the source escaped, so `\$x$` and `\\(x\)` are literal text.
+ *
+ * `from` bounds how far back the escape scan may look. Leave it at 0 when
+ * reading raw source. Pass the offset your own walk resumed at if you have
+ * already consumed the escapes behind it, as `renderMathInText` does: after it
+ * emits the `\\` of `\\\(x\)`, the `\(` that follows is a real opener even
+ * though a backslash precedes it.
+ */
+export declare function mathSpanAt(source: string, at: number, from?: number): MathSpan | undefined;
+/** The own-line display block starting at offset 0, or `undefined`. */
+export declare function mathBlockAt(source: string): MathBlock | undefined;

package/dist/types/postmortem.d.ts

@@ -44,6 +44,19 @@ export type BrokenPipeSource = "ipc-send" | "stdio-write";
 export declare function classifyBrokenPipe(err: Error): BrokenPipeSource | undefined;
 /** Whether an EPIPE came from an IPC `send()` to an optional worker. */
 export declare function isIpcSendEpipe(err: Error): boolean;
+/**
+ * Whether an uncaught error is Bun's asynchronous `ERR_SOCKET_CLOSED` thrown
+ * from inside `node:net` internals with no application frames on the stack.
+ *
+ * Bun ≥1.4 can fire the close callback of an already-closed `node:net` socket
+ * on a fresh stack; the throw bypasses every callsite try/catch and surfaces
+ * here as a process-level uncaughtException. Closing an already-closed socket
+ * is inherently a no-op — the socket owner's own `error`/`close` handlers
+ * still drive recovery — so tearing the session down for it is pure loss.
+ * Only frameless internal stacks qualify: an `ERR_SOCKET_CLOSED` raised
+ * through application code keeps the fatal path.
+ */
+export declare function isInternalSocketClosedError(err: unknown): boolean;
 /**
  * Detect Bun's advanced-serialization (structured-clone) IPC decode failure.
  *
@@ -94,10 +107,10 @@ export declare function registerStdioDisconnectHandling(): () => void;
  */
 export declare function markExpectedCleanupError<T extends object>(reason: T): T;
 /**
- * Whether `reason` (or any error in its `cause` chain) was marked via
- * {@link markExpectedCleanupError}. Walks the chain because the unhandled
- * reason is often a wrapper (`AbortError`) with the marked abort reason as
- * its `cause`.
+ * Whether `reason` (or any object in its bounded `cause` chain) was explicitly
+ * marked via {@link markExpectedCleanupError}. Runtime error names and codes
+ * are intentionally insufficient: unmarked `AbortError` and socket failures
+ * can originate from application code and must remain fatal when unhandled.
  */
 export declare function isExpectedCleanupError(reason: unknown): boolean;
 /**
@@ -110,15 +123,33 @@ export declare function interceptUnhandledRejections(interceptor: (reason: unkno
  * through an uncaught exception or unhandled rejection.
  */
 export declare function registerFatalRecoveryHint(provider: FatalRecoveryHintProvider): () => void;
+/** Controls when a registered cleanup callback participates in cleanup passes. */
+export interface CleanupRegistrationOptions {
+    /**
+     * Run only on a real exit, never during a manual keep-alive cleanup.
+     * The registration remains armed when a keep-alive pass skips it.
+     */
+    exitOnly?: boolean;
+}
 /**
- * Register a process cleanup callback, to be run on shutdown, signal, or fatal error.
+ * Registers a cleanup callback for shutdown, signals, fatal errors, and
+ * repeatable manual cleanup passes.
  *
- * Returns a Callback instance that can be used to cancel (unregister) or manually clean up.
- * If register is called after cleanup already began, invokes callback on a microtask.
+ * Registrations persist across keep-alive {@link cleanup} passes and run at
+ * most once per pass. Set `exitOnly` for resources the continuing process still
+ * holds (open databases, cached handles): keep-alive passes skip the callback
+ * without consuming its registration, while the eventual real exit runs it.
+ *
+ * A callback registered during a running keep-alive pass joins future passes;
+ * normal callbacks also run immediately for the current pass. Registrations
+ * made during a real exit run immediately.
+ *
+ * Returns a function that permanently cancels the registration.
  */
-export declare function register(id: string, callback: (reason: Reason) => void | Promise<void>): () => void;
+export declare function register(id: string, callback: (reason: Reason) => void | Promise<void>, options?: CleanupRegistrationOptions): () => void;
 /**
- * Runs all cleanup callbacks without exiting.
+ * Runs all cleanup callbacks without exiting, then re-arms the system so
+ * resources opened afterwards are still cleaned at the eventual real exit.
  * Use this in workers or when you need to clean up but continue execution.
  */
 export declare function cleanup(): Promise<void>;
@@ -127,6 +158,12 @@ export interface QuitOptions {
     /** Wait for buffered stdout before exiting; disable after the terminal has disconnected. */
     drainStdout?: boolean;
 }
+/**
+ * Waits (bounded) for buffered stdout to reach the terminal. Used before
+ * process exit and before an exec-replace, where unflushed output would be
+ * lost with the process image.
+ */
+export declare function drainStdout(): Promise<void>;
 /**
  * Runs all cleanup callbacks and exits through the current `process.exit`.
  *

package/dist/types/ptree.d.ts

@@ -10,6 +10,13 @@ import type { Spawn, Subprocess } from "bun";
 type InMask = "pipe" | "ignore" | Buffer | Uint8Array | null;
 /** A Bun subprocess with stdout/stderr always piped (stdin may vary). */
 type PipedSubprocess<In extends InMask = InMask> = Subprocess<In, "pipe", "pipe">;
+/**
+ * Build the Linux child-subreaper entrypoint.
+ *
+ * @internal Exported so tests can force a missing first libc soname and verify
+ * the loader continues to the next candidate.
+ */
+export declare function createLinuxSubreaperScript(libcCandidates?: readonly string[]): string;
 /**
  * Base for all exceptions representing child process nonzero exit, killed, or
  * cancellation.
@@ -63,7 +70,7 @@ export declare class ChildProcess<In extends InMask = InMask> {
     #private;
     readonly proc: PipedSubprocess<In>;
     readonly exposeStderr: boolean;
-    constructor(proc: PipedSubprocess<In>, exposeStderr: boolean, retainFullStderr?: boolean);
+    constructor(proc: PipedSubprocess<In>, exposeStderr: boolean, retainFullStderr?: boolean, terminateGroup?: boolean, hardKillTree?: boolean);
     get pid(): number;
     get exited(): Promise<number>;
     get exitCode(): number | null;
@@ -93,6 +100,13 @@ export declare class ChildProcess<In extends InMask = InMask> {
 type ChildSpawnOptions<In extends InMask = InMask> = Omit<Spawn.SpawnOptions<In, "pipe", "pipe">, "stdout" | "stderr" | "detached"> & {
     signal?: AbortSignal;
     detached?: boolean;
+    /**
+     * On Linux, supervise the command from a child subreaper so descendants
+     * remain reachable after changing session and reparenting. Other platforms
+     * ignore this option. macOS process groups cannot retain a daemonized
+     * descendant that creates a new session and reparents to launchd.
+     */
+    subreaper?: boolean;
     /** Expose and retain complete stderr for a later `wait({ stderr: "full" })`. */
     stderr?: "full" | null;
 };

package/dist/types/runtime-install.d.ts

@@ -73,6 +73,13 @@ export interface EnsureRuntimeInstalledOptions {
 export declare function writeRuntimeManifest(runtimeDir: string, install: RuntimeInstallSpec): Promise<void>;
 /**
  * Materialize a pinned dependency set into `runtimeDir` (idempotent,
- * cross-process safe via a lock directory). Returns `runtimeDir`.
+ * cross-process safe). Returns `runtimeDir`.
+ *
+ * Serialization uses the OS-backed {@link withFileLock} at
+ * `${runtimeDir}.install.lock`, which the kernel releases on process death, so
+ * a crashed installer cannot wedge later attempts (issue #10120). The path is
+ * deliberately distinct from the legacy `${runtimeDir}.lock` mkdir directory;
+ * {@link withLegacyInstallLock} atomically reserves that namespace during the
+ * new install so older processes cannot cross the migration boundary.
  */
 export declare function ensureRuntimeInstalled(options: EnsureRuntimeInstalledOptions): Promise<string>;

package/dist/types/sqlite.d.ts

@@ -7,6 +7,9 @@
  * one implementation here prevents the classifiers from drifting between the
  * credential store and the model cache.
  */
+import type { Database } from "bun:sqlite";
+/** Checkpoints committed WAL frames without waiting for concurrent readers. */
+export declare function checkpointWal(db: Database): void;
 /**
  * SQLite's busy result-code family — base `SQLITE_BUSY` plus the extended
  * variants `SQLITE_BUSY_RECOVERY` (concurrent WAL recovery), `SQLITE_BUSY_SNAPSHOT`,

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@linxiraos/pi-utils",
-	"version": "1.1.5",
+	"version": "1.1.7",
 	"description": "Shared utilities for pi packages",
 	"homepage": "https://linxira-os.github.io/zeta/",
 	"author": "Can Boluk",
@@ -31,7 +31,7 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@linxiraos/pi-natives": "1.1.5"
+		"@linxiraos/pi-natives": "1.1.7"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14"

package/src/acp/transport.ts

@@ -77,6 +77,15 @@ export class RequestError extends Error {
 			uri === undefined ? undefined : { uri },
 		);
 	}
+	/**
+	 * Creates a session-busy error: the agent/session is already processing, so the
+	 * request can be retried once idle (steer/follow-up/wait) instead of treating it
+	 * as a fault. `message` carries the caller's user-facing wording; `data` should
+	 * keep the stable discriminator shape (`reason: "session_busy"`).
+	 */
+	static sessionBusy(message: string, data?: unknown): RequestError {
+		return new RequestError(-32003, message, data);
+	}
 	/** Converts this error into a JSON-RPC result. */
 	toResult(): { error: ErrorResponse } {
 		return { error: this.toErrorResponse() };

package/src/async.ts

@@ -59,6 +59,7 @@ export function withTimeout<T>(promise: Promise<T>, ms: number, message: string,
 export class AsyncDrain<T> {
 	#queue?: T[];
 	#promise = Promise.resolve();
+	#flush?: () => void;
 
 	constructor(readonly delayMs: number = 0) {}
 
@@ -66,21 +67,28 @@ export class AsyncDrain<T> {
 	push(value: T, hnd: (values: T[]) => Promise<void> | void): Promise<void> {
 		let queue = this.#queue;
 		if (!queue) {
-			this.#queue = queue = [];
+			const batch: T[] = [];
+			this.#queue = batch;
+			queue = batch;
 			const { promise, resolve, reject } = Promise.withResolvers<void>();
 			const exec = (): void => {
+				if (this.#queue !== batch) return;
+				this.#queue = undefined;
+				this.#flush = undefined;
 				try {
-					if (this.#queue === queue) {
-						this.#queue = undefined;
-					}
-					resolve(hnd(queue!));
+					resolve(hnd(batch));
 				} catch (error) {
 					reject(error);
 				}
 			};
 			if (this.delayMs > 0) {
-				setTimeout(exec, this.delayMs);
+				const timer = setTimeout(exec, this.delayMs);
+				this.#flush = () => {
+					clearTimeout(timer);
+					exec();
+				};
 			} else {
+				this.#flush = exec;
 				queueMicrotask(exec);
 			}
 			this.#promise = promise;
@@ -88,4 +96,10 @@ export class AsyncDrain<T> {
 		queue.push(value);
 		return this.#promise;
 	}
+
+	/** Runs the pending batch handler immediately and returns its completion promise. */
+	flush(): Promise<void> {
+		this.#flush?.();
+		return this.#promise;
+	}
 }