@linxiraos/pi-utils 1.4.11 → 1.4.13

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 ## [Unreleased]
 
+## [1.4.13] - 2026-11-08
+
+- Released as part of Zeta 1.4.13.
+
+## [1.4.12] - 2026-11-08
+
+- Synced with upstream OMP v18.18.0.
+- Released as part of Zeta 1.4.12; no package-specific user-visible changes.
+
 ## [1.4.11] - 2026-11-06
 
 - `applyLegacyOmpEnv()` lets a host apply the read-only legacy OMP dotenv files after its settings layer resolves the compatibility switch; the eager `ZETA_OMP_COMPAT` pass is unchanged.
@@ -10,15 +19,15 @@
 
 ## [1.4.9] - 2026-11-03
 
-- Synced with upstream OMP v18.16.0; no package-specific user-visible changes.
+- Synced with upstream OMP v18.18.0.
 
 ## [1.4.7] - 2026-10-30
 
-- Synced with upstream OMP v18.14.0; no package-specific user-visible changes.
+- Synced with upstream OMP v18.18.0.
 
 ## [1.4.5] - 2026-10-28
 
-- Synced with upstream OMP v18.13.2 (shared utilities and runtime fixes); user-visible changes are in UPDATE-LOG.md under 1.4.5.
+- Synced with upstream OMP v18.18.0.
 
 ## [1.4.4] - 2026-10-26
 

package/THIRD-PARTY-NOTICES.txt

@@ -20,7 +20,7 @@ Forked application trees:
 | Path | Upstream | Snapshot | License | What Zeta changed |
 |---|---|---|---|---|
 | `packages/ main/ crates/ python/ lsp/ sdk/ types/ skills/` | oh-my-pi (OMP), https://github.com/can1357/oh-my-pi | integrated through tag `v18.15.0` (`document/upstream-sync.md`) | see upstream files | product name, paths, command names and env prefixes; branded assets; internal identifiers renamed to `__zeta*` |
-| `web-ui/` | OMP Web, https://github.com/17380936778/omp-web | frozen snapshot + manual cherry-picks (`document/upstream-sync.md`) | see upstream files | gateway transport, theme token bridge, page routing |
+| `web-ui/` | OMP Web, https://github.com/17380936778/omp-web | frozen snapshot, **abandoned 2026-11-05** (`document/upstream-sync.md`) | see upstream files | third-party UI, not maintained by Zeta: frozen as received, no builds, no fixes; the product renderer is `web-app/` (`Differences from Upstream` in README) |
 | `web-app/` (`src/studio`, `src/vendor/*`) | OMP Studio 0.1.17, https://github.com/the-snowpear/omp-studio | `0.1.17`, ported into the product renderer | MIT | maintained by Zeta now: the host contract is reimplemented in `studio-host` (pair/CSRF/query/command/events), the renderer was rebranded (`zeta-studio` wire name, Zeta links/fixtures), and Zeta adds windowed transcripts, precompressed static serving, the plugin registry, and the usage dashboard |
 | `termide/` | TermIDE, https://github.com/termide/termide | tag `0.46.0` = `a027ca788cd4c9d24f060cdcd3195ca2e475617b` | MIT | deviations listed in `termide/VENDOR.md` (28 entries) |
 | `editor/npm/*` (`@linxiraos/editor*`) | TermIDE `panel-editor` | same tree as `termide/` | MIT | built as the editor-only bin `termide-editor` (`editor/npm/editor/VENDOR.md`) |
@@ -44,10 +44,9 @@ Brand and assets:
 Frozen counterpart constants (interoperability, not branding):
 
 * Stencil OIDC `client-id "omp"`, its issuer and scopes; `catalog.stencil.so`;
-  `docs.stencil.so/tern/protocol/`; `my.omp.sh` as the collaboration relay
-  constant; the `__omp_judgment_images` upload key. These are wire-compatible
-  identifiers Zeta must keep, listed here so that a brand sweep does not break
-  them.
+  `docs.stencil.so/tern/protocol/`; the `__omp_judgment_images` upload key.
+  These are wire-compatible identifiers Zeta must keep, listed here so that a
+  brand sweep does not break them.
 
 PYTHON DEPENDENCY DISTRIBUTION ROLE
 ===================================

package/dist/types/dirs.d.ts

@@ -147,7 +147,18 @@ export declare function getAgentDir(): string;
 export declare function getProjectAgentDir(cwd?: string): string;
 /** Get the reports directory (~/.zeta/reports). */
 export declare function getReportsDir(): string;
-/** Get the logs directory (~/.zeta/logs). */
+/**
+ * Get the self-update state directory (~/.zeta/update): the background
+ * auto-update's status file and worker log, and the lock that keeps two
+ * installs (`zetacode update`, auto-update) from running at once.
+ */
+export declare function getUpdateStateDir(): string;
+/**
+ * Get the logs directory (~/.zeta/logs). `bun test` processes get
+ * `<tmpdir>/omp-test-logs-<uid>` instead, so suites never write into the
+ * developer's real logs; the uid suffix (as for the test session-owners dir)
+ * keeps users of a shared `/tmp` from owning each other's directory.
+ */
 export declare function getLogsDir(): string;
 /**
  * Local-timezone `YYYY-MM-DD` day key (zero-padded), formatted exactly like
@@ -176,35 +187,19 @@ export declare function getPluginsNodeModules(home?: string): string;
 /** Plugin manifest (~/.zeta/plugins/package.json). */
 export declare function getPluginsPackageJson(home?: string): string;
 /**
- * Zeta-named lockfile, written going forward; `PLUGINS_LOCKFILE_LEGACY` stays
- * readable so a pre-rename install keeps its state (see
- * `document/brand-surface-rules.md`, DUAL: read both spellings, write the Zeta
- * one). Every lockfile name in the tree comes from the two constants below —
- * a writer on one spelling and a reader on the other is what emptied
- * `zetacode plugin list` after the loader migrated the file.
+ * Zeta plugin lockfile name. Every lockfile name in the tree comes from this
+ * constant — a writer on one spelling and a reader on the other is what once
+ * emptied `zetacode plugin list`.
  */
 export declare const PLUGINS_LOCKFILE_CANONICAL = "zeta-plugins.lock.json";
-/** Pre-rename lockfile name still produced by earlier installs. */
-export declare const PLUGINS_LOCKFILE_LEGACY = "omp-plugins.lock.json";
 /**
  * Plugin lock file (~/.zeta/plugins/zeta-plugins.lock.json) — the path every
- * writer targets and every reader asks for first.
+ * writer targets and every reader asks for.
  *
  * It carries per-plugin runtime state (enabled flag, enabled features,
- * version), so the rename is a migration rather than a reset: a lockfile left
- * under the pre-rename name is still read (see
- * {@link pluginsLockfileReadOrder}) and moved to this path on first load.
+ * version).
  */
 export declare function getPluginsLockfile(home?: string): string;
-/**
- * Read order for a lockfile path whose directory is a plugins root: the
- * canonical name first, then the pre-rename one. Returned as absolute paths so
- * a caller can hand each to `Bun.file` without re-deriving the directory.
- *
- * A path that is not one of the two names (a caller- or test-supplied path) is
- * returned as-is and reads nothing else.
- */
-export declare function pluginsLockfileReadOrder(lockfilePath: string): string[];
 /**
  * Normalize a plugin id into a safe single path segment (spec §4.2): lowercased,
  * every character outside `[a-z0-9._-]` (including `/` and `\`, so scoped npm
@@ -241,7 +236,7 @@ export declare function getRemoteDir(): string;
  * Relocate the base directory for agent-managed worktrees (PR checkouts, task
  * isolation, and `zetacode 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.
+ * fall back to `ZETA_WORKTREE_DIR` or the `~/.zeta/wt` default.
  *
  * `~` is expanded and a relative path is rejected (see {@link resolveAbsoluteDir}).
  * Returns the absolute path that took effect, or `undefined` if the input was
@@ -251,7 +246,7 @@ export declare function getRemoteDir(): string;
 export declare function setWorktreesDir(dir: string | undefined): string | undefined;
 /**
  * Get the agent-managed worktrees directory. Resolution order: the
- * `OMP_WORKTREE_DIR` env var, then the {@link setWorktreesDir} override (the
+ * `ZETA_WORKTREE_DIR` env var, then the {@link setWorktreesDir} override (the
  * `worktree.base` setting), then the `~/.zeta/wt` default. The env var and the
  * override are both `~`-expanded and must be absolute; a relative value is
  * ignored and resolution falls through.
@@ -289,25 +284,28 @@ export declare function hashPath(absPath: string): string;
 export declare function getWorktreeDir(segment: string): string;
 /**
  * Get the GitHub view cache database path (~/.zeta/cache/github-cache.db).
- * Honors the `OMP_GITHUB_CACHE_DB` env var when set so tests can isolate the
- * cache file without touching the rest of the config root.
+ * Honors the `ZETA_GITHUB_CACHE_DB` env var (`OMP_GITHUB_CACHE_DB` kept as a
+ * read alias) when set so tests can isolate the cache file without touching
+ * the rest of the config root.
  */
 export declare function getGithubCacheDbPath(): string;
 /**
  * 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.
+ * Honors `ZETA_COMMIT_CACHE_DB` (`OMP_COMMIT_CACHE_DB` kept as a read alias)
+ * so tests and operators can isolate the cache.
  */
 export declare function getCommitCacheDbPath(): string;
 /**
  * Get the judgment answer cache database path (~/.zeta/cache/judgment-cache.db).
- * Honors `OMP_JUDGMENT_CACHE_DB` so tests and operators can isolate the cache.
+ * Honors `ZETA_JUDGMENT_CACHE_DB` (`OMP_JUDGMENT_CACHE_DB` kept as a read
+ * alias) so tests and operators can isolate the cache.
  */
 export declare function getJudgmentCacheDbPath(): string;
 /** Get the legacy Pi extension parse cache database path. */
 export declare function getLegacyPiExtensionCacheDbPath(): string;
 /**
  * Get the encrypted auth-broker snapshot cache path (~/.zeta/cache/auth-broker-snapshot.enc).
- * Honors the `OMP_AUTH_BROKER_SNAPSHOT_CACHE` env var when set so tests and
+ * Honors the `ZETA_AUTH_BROKER_SNAPSHOT_CACHE` env var when set so tests and
  * operators can isolate or relocate the cache file.
  */
 export declare function getAuthBrokerSnapshotCachePath(): string;
@@ -426,10 +424,11 @@ export declare function getMCPConfigPath(scope: "user" | "project", cwd?: string
 /** Get the SSH config file path. */
 export declare function getSSHConfigPath(scope: "user" | "project", cwd?: string): string;
 /**
- * Application label for usage attribution (`OMP_APP_NAME`), defaulting to
- * `zeta`. Embedders that drive zeta 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.
+ * Application label for usage attribution (`ZETA_APP_NAME`, with
+ * `OMP_APP_NAME` kept as a read alias), defaulting to `zeta`. Embedders that
+ * drive zeta 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;
 /**

package/dist/types/env.d.ts

@@ -44,16 +44,6 @@ export declare function getDotenvEnvValues(cwd?: string, env?: Record<string, st
  * only shell-identifier names and spawn-safe values.
  */
 export declare function parseEnvFile(filePath: string): Record<string, string>;
-export declare function isOmpCompatEnabled(env?: Record<string, string | undefined>): boolean;
-/**
- * Apply the legacy OMP dotenv files on demand.
- *
- * The eager pass above only sees `ZETA_OMP_COMPAT` from the shell or a Zeta
- * dotenv file. A host that resolves the persisted `compat.importLegacyOmp`
- * setting calls this once its settings layer is loaded. Idempotent, and it
- * never overwrites a name the process already has.
- */
-export declare function applyLegacyOmpEnv(): void;
 /**
  * Intentional re-export of Bun.env.
  *

package/dist/types/logger.d.ts

@@ -9,6 +9,35 @@ export interface LogEvent {
 }
 /** Receives each structured log event after the local transport path runs. */
 export type LogSink = (event: LogEvent) => void;
+/**
+ * Destination that takes this thread's log records in place of its own
+ * transports and sinks (a worker thread routing records to the main thread's
+ * logger); see {@link setLogForwarder}.
+ */
+export interface LogForwarder {
+    /**
+     * Take one record. Its context is already merged over the enclosing
+     * {@link withContext} fields and reduced to plain JSON data, so it survives
+     * a structured clone; `timestamp` is when the record was logged.
+     */
+    emit(event: LogEvent): void;
+    /** Write every record emitted so far on the receiving side; backs {@link flush}. */
+    flush(): void;
+}
+/**
+ * Route every later record logged on this thread to `forwarder` instead of the
+ * local transports and sinks, which then stay unused (no log file is opened);
+ * {@link flush} asks the forwarder to flush. `undefined` restores local logging.
+ * For worker threads, whose main thread owns the process log file.
+ */
+export declare function setLogForwarder(forwarder: LogForwarder | undefined): void;
+/**
+ * Log a record another thread forwarded (see {@link setLogForwarder}): written
+ * to the local transports with its own timestamp, then handed to the sinks. Its
+ * context is taken as is; the caller's enclosing {@link withContext} is not
+ * merged in. On a thread that forwards itself, the record is forwarded on.
+ */
+export declare function emitForeign(event: LogEvent): void;
 /** Register an out-of-band log sink and return a disposer. */
 export declare function registerLogSink(sink: LogSink): () => void;
 /**

package/dist/types/path.d.ts

@@ -8,3 +8,5 @@ export declare function stripWindowsExtendedLengthPathPrefix(filePath: string, p
  * On POSIX, requires an absolute path.
  */
 export declare function isFullyQualifiedPath(filePath: string, platform?: NodeJS.Platform): boolean;
+/** Expands a leading `~` (`~`, `~/…`, `~\…`, `~name`) to `home`, the user's home directory by default. */
+export declare function expandTilde(filePath: string, home?: string): string;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@linxiraos/pi-utils",
-	"version": "1.4.11",
+	"version": "1.4.13",
 	"description": "Shared utilities for pi packages",
 	"keywords": [
 		"utilities",
@@ -47,15 +47,15 @@
 	},
 	"scripts": {
 		"check": "oxlint . && oxfmt --check --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts' && bun run check:types",
-		"check:types": "tsc -p tsconfig.json --noEmit",
+		"check:types": "bun check --no-script -p tsconfig.json",
 		"lint": "oxlint .",
 		"test": "bun test --parallel",
 		"fix": "oxlint --fix --fix-suggestions . && bun run fmt",
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@linxiraos/pi-natives": "1.4.11",
-		"@linxiraos/zeta-schema": "1.4.11"
+		"@linxiraos/pi-natives": "1.4.13",
+		"@linxiraos/zeta-schema": "1.4.13"
 	},
 	"devDependencies": {
 		"@types/bun": "1.4.4"

package/src/dirs.ts

@@ -24,6 +24,13 @@ import { isBunTestRuntime } from "./test-runtime";
  * names, provider attribution headers, splash wordmark. NOT the CLI command. */
 export const APP_NAME: string = "zeta";
 
+/** Read `primary`, falling back to the pre-rename `legacy` spelling. */
+function readAliasedEnv(primary: string, legacy: string): string | undefined {
+	const value = process.env[primary]?.trim();
+	if (value) return value;
+	return process.env[legacy]?.trim() || undefined;
+}
+
 /** CLI binary name (`npm i -g @linxiraos/zeta` installs exactly one bin,
  * `zetacode` — the retired `zeta-c`/`zeta-cli` aliases are gone). Every
  * user-facing "run this command" string and process title uses this; the
@@ -644,7 +651,7 @@ export function setProfile(profile: string | undefined): void {
 	if (activeProfile) {
 		dirs = new DirResolver({ profile: activeProfile });
 		process.env.ZETA_PROFILE = activeProfile;
-		process.env.OMP_PROFILE = activeProfile;
+		process.env.ZETA_PROFILE = activeProfile;
 		process.env.PI_PROFILE = activeProfile;
 		process.env.ZETA_CODING_AGENT_DIR = dirs.agentDir;
 	} else {
@@ -688,7 +695,21 @@ export function getReportsDir(): string {
 	return dirs.rootSubdir("reports", "state");
 }
 
-/** Get the logs directory (~/.zeta/logs). */
+/**
+ * Get the self-update state directory (~/.zeta/update): the background
+ * auto-update's status file and worker log, and the lock that keeps two
+ * installs (`zetacode update`, auto-update) from running at once.
+ */
+export function getUpdateStateDir(): string {
+	return dirs.rootSubdir("update", "state");
+}
+
+/**
+ * Get the logs directory (~/.zeta/logs). `bun test` processes get
+ * `<tmpdir>/omp-test-logs-<uid>` instead, so suites never write into the
+ * developer's real logs; the uid suffix (as for the test session-owners dir)
+ * keeps users of a shared `/tmp` from owning each other's directory.
+ */
 export function getLogsDir(): string {
 	if (isBunTestRuntime()) {
 		const uid = typeof process.getuid === "function" ? process.getuid() : os.userInfo().username;
@@ -742,46 +763,23 @@ export function getPluginsPackageJson(home?: string): string {
 }
 
 /**
- * Zeta-named lockfile, written going forward; `PLUGINS_LOCKFILE_LEGACY` stays
- * readable so a pre-rename install keeps its state (see
- * `document/brand-surface-rules.md`, DUAL: read both spellings, write the Zeta
- * one). Every lockfile name in the tree comes from the two constants below —
- * a writer on one spelling and a reader on the other is what emptied
- * `zetacode plugin list` after the loader migrated the file.
+ * Zeta plugin lockfile name. Every lockfile name in the tree comes from this
+ * constant — a writer on one spelling and a reader on the other is what once
+ * emptied `zetacode plugin list`.
  */
 export const PLUGINS_LOCKFILE_CANONICAL = "zeta-plugins.lock.json";
 
-/** Pre-rename lockfile name still produced by earlier installs. */
-export const PLUGINS_LOCKFILE_LEGACY = "omp-plugins.lock.json";
-
 /**
  * Plugin lock file (~/.zeta/plugins/zeta-plugins.lock.json) — the path every
- * writer targets and every reader asks for first.
+ * writer targets and every reader asks for.
  *
  * It carries per-plugin runtime state (enabled flag, enabled features,
- * version), so the rename is a migration rather than a reset: a lockfile left
- * under the pre-rename name is still read (see
- * {@link pluginsLockfileReadOrder}) and moved to this path on first load.
+ * version).
  */
 export function getPluginsLockfile(home?: string): string {
 	return path.join(getPluginsDir(home), PLUGINS_LOCKFILE_CANONICAL);
 }
 
-/**
- * Read order for a lockfile path whose directory is a plugins root: the
- * canonical name first, then the pre-rename one. Returned as absolute paths so
- * a caller can hand each to `Bun.file` without re-deriving the directory.
- *
- * A path that is not one of the two names (a caller- or test-supplied path) is
- * returned as-is and reads nothing else.
- */
-export function pluginsLockfileReadOrder(lockfilePath: string): string[] {
-	const dir = path.dirname(lockfilePath);
-	const base = path.basename(lockfilePath);
-	if (base !== PLUGINS_LOCKFILE_CANONICAL && base !== PLUGINS_LOCKFILE_LEGACY) return [lockfilePath];
-	return [path.join(dir, PLUGINS_LOCKFILE_CANONICAL), path.join(dir, PLUGINS_LOCKFILE_LEGACY)];
-}
-
 /**
  * Normalize a plugin id into a safe single path segment (spec §4.2): lowercased,
  * every character outside `[a-z0-9._-]` (including `/` and `\`, so scoped npm
@@ -893,7 +891,7 @@ let worktreesDirOverride: string | undefined;
  * Relocate the base directory for agent-managed worktrees (PR checkouts, task
  * isolation, and `zetacode 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.
+ * fall back to `ZETA_WORKTREE_DIR` or the `~/.zeta/wt` default.
  *
  * `~` is expanded and a relative path is rejected (see {@link resolveAbsoluteDir}).
  * Returns the absolute path that took effect, or `undefined` if the input was
@@ -907,13 +905,13 @@ export function setWorktreesDir(dir: string | undefined): string | undefined {
 
 /**
  * Get the agent-managed worktrees directory. Resolution order: the
- * `OMP_WORKTREE_DIR` env var, then the {@link setWorktreesDir} override (the
+ * `ZETA_WORKTREE_DIR` env var, then the {@link setWorktreesDir} override (the
  * `worktree.base` setting), then the `~/.zeta/wt` default. The env var and the
  * override are both `~`-expanded and must be absolute; a relative value is
  * ignored and resolution falls through.
  */
 export function getWorktreesDir(): string {
-	return resolveAbsoluteDir(process.env.OMP_WORKTREE_DIR) ?? worktreesDirOverride ?? dirs.rootSubdir("wt", "data");
+	return resolveAbsoluteDir(process.env.ZETA_WORKTREE_DIR) ?? worktreesDirOverride ?? dirs.rootSubdir("wt", "data");
 }
 
 /** Get the SSH control socket directory (~/.zeta/ssh-control). */
@@ -980,30 +978,33 @@ export function getWorktreeDir(segment: string): string {
 
 /**
  * Get the GitHub view cache database path (~/.zeta/cache/github-cache.db).
- * Honors the `OMP_GITHUB_CACHE_DB` env var when set so tests can isolate the
- * cache file without touching the rest of the config root.
+ * Honors the `ZETA_GITHUB_CACHE_DB` env var (`OMP_GITHUB_CACHE_DB` kept as a
+ * read alias) when set so tests can isolate the cache file without touching
+ * the rest of the config root.
  */
 export function getGithubCacheDbPath(): string {
-	const override = process.env.OMP_GITHUB_CACHE_DB;
+	const override = readAliasedEnv("ZETA_GITHUB_CACHE_DB", "OMP_GITHUB_CACHE_DB");
 	if (override) return override;
 	return dirs.rootSubdir(path.join("cache", "github-cache.db"), "cache");
 }
 /**
  * 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.
+ * Honors `ZETA_COMMIT_CACHE_DB` (`OMP_COMMIT_CACHE_DB` kept as a read alias)
+ * so tests and operators can isolate the cache.
  */
 export function getCommitCacheDbPath(): string {
-	const override = process.env.OMP_COMMIT_CACHE_DB;
+	const override = readAliasedEnv("ZETA_COMMIT_CACHE_DB", "OMP_COMMIT_CACHE_DB");
 	if (override) return override;
 	return dirs.rootSubdir(path.join("cache", "commit-inference.db"), "cache");
 }
 
 /**
  * Get the judgment answer cache database path (~/.zeta/cache/judgment-cache.db).
- * Honors `OMP_JUDGMENT_CACHE_DB` so tests and operators can isolate the cache.
+ * Honors `ZETA_JUDGMENT_CACHE_DB` (`OMP_JUDGMENT_CACHE_DB` kept as a read
+ * alias) so tests and operators can isolate the cache.
  */
 export function getJudgmentCacheDbPath(): string {
-	const override = process.env.OMP_JUDGMENT_CACHE_DB;
+	const override = readAliasedEnv("ZETA_JUDGMENT_CACHE_DB", "OMP_JUDGMENT_CACHE_DB");
 	if (override) return override;
 	return dirs.rootSubdir(path.join("cache", "judgment-cache.db"), "cache");
 }
@@ -1015,11 +1016,11 @@ export function getLegacyPiExtensionCacheDbPath(): string {
 
 /**
  * Get the encrypted auth-broker snapshot cache path (~/.zeta/cache/auth-broker-snapshot.enc).
- * Honors the `OMP_AUTH_BROKER_SNAPSHOT_CACHE` env var when set so tests and
+ * Honors the `ZETA_AUTH_BROKER_SNAPSHOT_CACHE` env var when set so tests and
  * operators can isolate or relocate the cache file.
  */
 export function getAuthBrokerSnapshotCachePath(): string {
-	const override = process.env.OMP_AUTH_BROKER_SNAPSHOT_CACHE;
+	const override = process.env.ZETA_AUTH_BROKER_SNAPSHOT_CACHE;
 	if (override) return override;
 	return dirs.rootSubdir(path.join("cache", "auth-broker-snapshot.enc"), "cache");
 }
@@ -1364,13 +1365,14 @@ let cachedInstallId: string | null = null;
 
 const INSTALL_ID_FILE = "install-id";
 /**
- * Application label for usage attribution (`OMP_APP_NAME`), defaulting to
- * `zeta`. Embedders that drive zeta 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.
+ * Application label for usage attribution (`ZETA_APP_NAME`, with
+ * `OMP_APP_NAME` kept as a read alias), defaulting to `zeta`. Embedders that
+ * drive zeta 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 function getAppName(): string {
-	const value = process.env.OMP_APP_NAME?.trim();
+	const value = readAliasedEnv("ZETA_APP_NAME", "OMP_APP_NAME");
 	return value ? value : "zeta";
 }
 

package/src/env.ts

@@ -2,7 +2,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { parseEnv } from "node:util";
-import { getActiveProfile, getAgentDir, getConfigRootDir, getProjectDir, refreshDirsFromEnv } from "./dirs";
+import { getAgentDir, getConfigRootDir, getProjectDir, refreshDirsFromEnv } from "./dirs";
 import { isBunTestRuntime } from "./test-runtime";
 
 export * from "./test-runtime";
@@ -134,7 +134,7 @@ function readLaunchEnv(): ReadonlyMap<string, string> | undefined {
 }
 
 const launchEnvValues = readLaunchEnv();
-const projectEnvNamesLoadedByOmp = new Set<string>();
+const projectEnvNamesLoadedFromDotenv = new Set<string>();
 
 function expandDotenvValues(values: Record<string, string>, env: Record<string, string>): Record<string, string> {
 	const expanded: Record<string, string> = {};
@@ -215,7 +215,7 @@ function filterChildShellEnvInternal(
 			}
 			continue;
 		}
-		if (runtimeLaunchEnvValues || projectEnvNamesLoadedByOmp.has(key)) {
+		if (runtimeLaunchEnvValues || projectEnvNamesLoadedFromDotenv.has(key)) {
 			// Strong provenance: the launch environment is known and this name is
 			// absent from it, or OMP itself injected the value — either way it came
 			// from a project dotenv file, not the parent shell.
@@ -278,56 +278,11 @@ export function parseEnvFile(filePath: string): Record<string, string> {
 	return result;
 }
 
-// Read-only compatibility with the old OMP agent directory. Off by default:
-// external OMP configuration must be explicitly imported. Set
-// ZETA_OMP_COMPAT=1 in the shell or a Zeta dotenv file to enable both the
-// legacy dotenv fallback and the models.yml/agent.db overlay.
-export function isOmpCompatEnabled(env: Record<string, string | undefined> = Bun.env): boolean {
-	const value = env.ZETA_OMP_COMPAT;
-	if (!value) return false;
-	const normalized = value.toLowerCase();
-	return normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on";
-}
-
-function loadLegacyOmpEnv(): Record<string, string> {
-	const home = os.homedir();
-	const project = getProjectDir();
-	const profile = getActiveProfile();
-	const files = [
-		{ file: path.join(home, ".omp", ".env"), project: false },
-		{ file: path.join(home, ".omp", "agent", ".env"), project: false },
-		...(profile ? [{ file: path.join(home, ".omp", "profiles", profile, "agent", ".env"), project: false }] : []),
-		{ file: path.join(project, ".omp", ".env"), project: true },
-		{ file: path.join(project, ".omp", "agent", ".env"), project: true },
-	];
-	const merged: Record<string, string> = {};
-	const seen = new Set<string>();
-	for (const { file, project: projectFile } of files) {
-		if (seen.has(file)) continue;
-		seen.add(file);
-		for (const [key, value] of Object.entries(parseEnvFile(file))) {
-			merged[key] = value;
-			if (projectFile) projectEnvNamesLoadedByOmp.add(key);
-		}
-	}
-	return merged;
-}
-
 // Eagerly parse the user's $HOME/.env and the current project's .env (from cwd)
 const homeEnv = parseEnvFile(path.join(os.homedir(), ".env"));
 const piEnv = parseEnvFile(path.join(getConfigRootDir(), ".env"));
 const agentEnv = parseEnvFile(path.join(getAgentDir(), ".env"));
 const projectEnv = parseEnvFile(path.join(getProjectDir(), ".env"));
-// The switch itself may come from the shell or any Zeta dotenv file. Check the
-// same precedence before touching legacy OMP files; do not read them by default.
-const ompCompatValue =
-	Bun.env.ZETA_OMP_COMPAT ??
-	projectEnv.ZETA_OMP_COMPAT ??
-	agentEnv.ZETA_OMP_COMPAT ??
-	piEnv.ZETA_OMP_COMPAT ??
-	homeEnv.ZETA_OMP_COMPAT;
-const legacyOmpEnabled = isOmpCompatEnabled({ ZETA_OMP_COMPAT: ompCompatValue });
-const legacyOmpEnv = legacyOmpEnabled ? loadLegacyOmpEnv() : {};
 
 for (const key of Object.keys(Bun.env)) {
 	const value = Bun.env[key];
@@ -341,12 +296,12 @@ function mergeDotenvIntoProcess(file: Record<string, string>): void {
 	for (const key in file) {
 		if (!isMacosMallocStackLoggingEnvName(key) && !Bun.env[key]) {
 			Bun.env[key] = file[key];
-			if (file === projectEnv) projectEnvNamesLoadedByOmp.add(key);
+			if (file === projectEnv) projectEnvNamesLoadedFromDotenv.add(key);
 		}
 	}
 }
 
-for (const file of [projectEnv, agentEnv, piEnv, homeEnv, legacyOmpEnv]) mergeDotenvIntoProcess(file);
+for (const file of [projectEnv, agentEnv, piEnv, homeEnv]) mergeDotenvIntoProcess(file);
 
 // Directory-affecting keys (XDG_*_HOME, and in default mode ZETA_CODING_AGENT_DIR)
 // may have just arrived from the profile/agent `.env` applied above. The dirs
@@ -355,23 +310,6 @@ for (const file of [projectEnv, agentEnv, piEnv, homeEnv, legacyOmpEnv]) mergeDo
 // the profile name + home, so this re-reads only the directory vars.
 refreshDirsFromEnv();
 
-let legacyOmpEnvApplied = legacyOmpEnabled;
-
-/**
- * Apply the legacy OMP dotenv files on demand.
- *
- * The eager pass above only sees `ZETA_OMP_COMPAT` from the shell or a Zeta
- * dotenv file. A host that resolves the persisted `compat.importLegacyOmp`
- * setting calls this once its settings layer is loaded. Idempotent, and it
- * never overwrites a name the process already has.
- */
-export function applyLegacyOmpEnv(): void {
-	if (legacyOmpEnvApplied) return;
-	legacyOmpEnvApplied = true;
-	mergeDotenvIntoProcess(loadLegacyOmpEnv());
-	refreshDirsFromEnv();
-}
-
 /**
  * Intentional re-export of Bun.env.
  *

package/src/logger.ts

@@ -25,6 +25,7 @@ import { RotatingFileSink } from "./logger/rotating-file";
 import { isPidAlive } from "./pid";
 import { setStderrRedirectTarget } from "./stderr-guard";
 import { drainModuleLoadEvents } from "./timing-buffer";
+import { isRecord } from "./type-guards";
 /** Severity names accepted by the centralized logger. */
 export type LogLevel = "error" | "warn" | "info" | "debug";
 
@@ -39,8 +40,103 @@ export interface LogEvent {
 /** Receives each structured log event after the local transport path runs. */
 export type LogSink = (event: LogEvent) => void;
 
+/**
+ * Destination that takes this thread's log records in place of its own
+ * transports and sinks (a worker thread routing records to the main thread's
+ * logger); see {@link setLogForwarder}.
+ */
+export interface LogForwarder {
+	/**
+	 * Take one record. Its context is already merged over the enclosing
+	 * {@link withContext} fields and reduced to plain JSON data, so it survives
+	 * a structured clone; `timestamp` is when the record was logged.
+	 */
+	emit(event: LogEvent): void;
+	/** Write every record emitted so far on the receiving side; backs {@link flush}. */
+	flush(): void;
+}
+
 const logSinks = new Set<LogSink>();
 
+/** Set by {@link setLogForwarder}: records go there instead of to local transports and sinks. */
+let logForwarder: LogForwarder | undefined;
+
+/**
+ * Route every later record logged on this thread to `forwarder` instead of the
+ * local transports and sinks, which then stay unused (no log file is opened);
+ * {@link flush} asks the forwarder to flush. `undefined` restores local logging.
+ * For worker threads, whose main thread owns the process log file.
+ */
+export function setLogForwarder(forwarder: LogForwarder | undefined): void {
+	logForwarder = forwarder;
+}
+
+/**
+ * Log a record another thread forwarded (see {@link setLogForwarder}): written
+ * to the local transports with its own timestamp, then handed to the sinks. Its
+ * context is taken as is; the caller's enclosing {@link withContext} is not
+ * merged in. On a thread that forwards itself, the record is forwarded on.
+ */
+export function emitForeign(event: LogEvent): void {
+	const forwarder = logForwarder;
+	if (forwarder) {
+		try {
+			forwarder.emit(event);
+		} catch {
+			// Forwarding is as best-effort as local writes.
+		}
+		return;
+	}
+	try {
+		emitLocally(event.level, event.message, event.context, event.timestamp);
+	} catch {
+		// Silently ignore logging failures
+	}
+	dispatchToSinks(event);
+}
+
+/** Forward one record logged on this thread; never throws. */
+function forwardRecord(
+	forwarder: LogForwarder,
+	level: LogLevel,
+	message: string,
+	context: Record<string, unknown> | undefined,
+): void {
+	try {
+		forwarder.emit({ level, message, context: forwardableContext(context), timestamp: new Date() });
+	} catch {
+		// Forwarding is as best-effort as local writes.
+	}
+}
+
+/**
+ * The call's context merged over the enclosing {@link withContext} fields (call
+ * fields win, as for sinks), as plain JSON data: errors become
+ * `{ name, message, stack, … }` exactly as in the log file. A context that
+ * cannot be serialized (a cycle, a bigint) is dropped from the record.
+ */
+function forwardableContext(context: Record<string, unknown> | undefined): Record<string, unknown> | undefined {
+	// An Error passed as the context carries its fields as non-enumerable properties.
+	let merged = context instanceof Error ? errorToRecord(context) : context;
+	const scoped = logContextStorage.getStore();
+	if (scoped) {
+		try {
+			merged = { ...scoped, ...merged };
+		} catch {
+			// A throwing getter must not turn a log call into a failure; keep the call's own fields.
+		}
+	}
+	if (merged === undefined) return undefined;
+	try {
+		const parsed: unknown = JSON.parse(
+			mayContainError(merged) ? JSON.stringify(merged, jsonReplacer) : JSON.stringify(merged),
+		);
+		return isRecord(parsed) ? parsed : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
 /** Register an out-of-band log sink and return a disposer. */
 export function registerLogSink(sink: LogSink): () => void {
 	logSinks.add(sink);
@@ -62,7 +158,11 @@ function emitToSinks(level: LogLevel, message: string, context: Record<string, u
 			// A throwing getter must not turn a log call into a failure; sinks get the call's own fields.
 		}
 	}
-	const event: LogEvent = { level, message, context: merged, timestamp: new Date() };
+	dispatchToSinks({ level, message, context: merged, timestamp: new Date() });
+}
+
+function dispatchToSinks(event: LogEvent): void {
+	if (logSinks.size === 0) return;
 	for (const sink of logSinks) {
 		try {
 			sink(event);
@@ -199,19 +299,21 @@ function ensureDir(dir: string): string {
  * forensic logs showed only an opaque empty object.
  */
 function jsonReplacer(_key: string, value: unknown): unknown {
-	if (value instanceof Error) {
-		const out: Record<string, unknown> = {
-			name: value.name,
-			message: value.message,
-			stack: value.stack,
-		};
-		// Preserve `.cause` and any custom enumerable fields the caller attached.
-		const errAsRecord = value as unknown as Record<string, unknown>;
-		for (const k in errAsRecord) out[k] = errAsRecord[k];
-		if (value.cause !== undefined) out.cause = value.cause;
-		return out;
-	}
-	return value;
+	return value instanceof Error ? errorToRecord(value) : value;
+}
+
+/** An Error's fields as a plain object: name, message, stack, enumerable extras, and `cause`. */
+function errorToRecord(value: Error): Record<string, unknown> {
+	const out: Record<string, unknown> = {
+		name: value.name,
+		message: value.message,
+		stack: value.stack,
+	};
+	// Preserve `.cause` and any custom enumerable fields the caller attached.
+	const errAsRecord = value as unknown as Record<string, unknown>;
+	for (const k in errAsRecord) out[k] = errAsRecord[k];
+	if (value.cause !== undefined) out.cause = value.cause;
+	return out;
 }
 
 // Values visited by the Error pre-scan before falling back to the replacer.
@@ -278,12 +380,16 @@ export function withoutContext<T>(fn: () => T): T {
 	return logContextStorage.exit(fn);
 }
 
-/** Serialize one log record: timestamp, level, pid, message, then context fields. */
+/**
+ * Serialize one log record: timestamp, level, pid, message, then the `scoped`
+ * ({@link withContext}) fields and the context fields.
+ */
 function formatLogRecord(
 	level: LogLevel,
 	message: string,
 	context: Record<string, unknown> | undefined,
 	timestamp: string,
+	scoped: Readonly<Record<string, unknown>> | undefined,
 ): string {
 	const metadata =
 		!FORMAT_TOKEN_PATTERN.test(message) && context !== null && typeof context === "object" ? context : undefined;
@@ -293,7 +399,6 @@ function formatLogRecord(
 		pid: process.pid,
 		message: metadata?.message ? `${message} ${metadata.message}` : message,
 	};
-	const scoped = logContextStorage.getStore();
 	if (scoped) {
 		for (const key of Object.keys(scoped)) {
 			if (key !== "level" && key !== "timestamp" && key !== "message") entry[key] = scoped[key];
@@ -370,7 +475,8 @@ function resolveFileLevelRank(): number {
  */
 export function flush(): void {
 	try {
-		activeTransports?.file?.flush();
+		if (logForwarder) logForwarder.flush();
+		else activeTransports?.file?.flush();
 	} catch {
 		// Flushing diagnostics must never mask the caller's own work or failure.
 	}
@@ -405,13 +511,25 @@ function getLocalTransports(): LocalTransports {
 	return activeTransports;
 }
 
-function emitLocally(level: LogLevel, message: string, context: Record<string, unknown> | undefined): void {
+/**
+ * Write one record to the local transports. A `foreignTimestamp` marks a record
+ * another thread logged ({@link emitForeign}): it keeps that time and gets no
+ * {@link withContext} fields of this call stack, while the file still rotates by
+ * the current day so a late record cannot reopen an earlier day's file.
+ */
+function emitLocally(
+	level: LogLevel,
+	message: string,
+	context: Record<string, unknown> | undefined,
+	foreignTimestamp?: Date,
+): void {
 	const transports = getLocalTransports();
 	const rank = LOG_LEVEL_RANK[level];
 	const file = rank <= transports.fileLevelRank ? transports.file : undefined;
 	if (!file && !transports.console) return;
 	const now = new Date();
-	const line = formatLogRecord(level, message, context, formatLocalTimestamp(now));
+	const scoped = foreignTimestamp ? undefined : logContextStorage.getStore();
+	const line = formatLogRecord(level, message, context, formatLocalTimestamp(foreignTimestamp ?? now), scoped);
 	file?.write(line, rank <= IMMEDIATE_FLUSH_RANK || exiting, localDay(now));
 	if (transports.console) fs.writeSync(1, `${line}${os.EOL}`);
 }
@@ -438,6 +556,7 @@ export function setTransports(opts: { console?: boolean; file?: boolean | string
  * @param context - The context to log.
  */
 export function error(message: string, context?: Record<string, unknown>): void {
+	if (logForwarder) return forwardRecord(logForwarder, "error", message, context);
 	try {
 		emitLocally("error", message, context);
 	} catch {
@@ -452,6 +571,7 @@ export function error(message: string, context?: Record<string, unknown>): void
  * @param context - The context to log.
  */
 export function warn(message: string, context?: Record<string, unknown>): void {
+	if (logForwarder) return forwardRecord(logForwarder, "warn", message, context);
 	try {
 		emitLocally("warn", message, context);
 	} catch {
@@ -466,6 +586,7 @@ export function warn(message: string, context?: Record<string, unknown>): void {
  * @param context - The context to log.
  */
 export function info(message: string, context?: Record<string, unknown>): void {
+	if (logForwarder) return forwardRecord(logForwarder, "info", message, context);
 	try {
 		emitLocally("info", message, context);
 	} catch {
@@ -480,6 +601,7 @@ export function info(message: string, context?: Record<string, unknown>): void {
  * @param context - The context to log.
  */
 export function debug(message: string, context?: Record<string, unknown>): void {
+	if (logForwarder) return forwardRecord(logForwarder, "debug", message, context);
 	try {
 		emitLocally("debug", message, context);
 	} catch {

package/src/path.ts

@@ -1,3 +1,4 @@
+import * as os from "node:os";
 import * as path from "node:path";
 
 const WINDOWS_DRIVE_PATH = /^([A-Za-z]):[\\/](.*)$/;
@@ -54,3 +55,16 @@ export function isFullyQualifiedPath(filePath: string, platform: NodeJS.Platform
 	}
 	return true;
 }
+
+/** Expands a leading `~` (`~`, `~/…`, `~\…`, `~name`) to `home`, the user's home directory by default. */
+export function expandTilde(filePath: string, home?: string): string {
+	const h = home ?? os.homedir();
+	if (filePath === "~") return h;
+	if (filePath.startsWith("~/") || filePath.startsWith("~\\")) {
+		return h + filePath.slice(1);
+	}
+	if (filePath.startsWith("~")) {
+		return path.join(h, filePath.slice(1));
+	}
+	return filePath;
+}

package/src/postmortem.ts

@@ -713,6 +713,8 @@ export async function fatal(error: unknown): Promise<never> {
 	const report = `${Bun.inspect(error, { colors: process.stderr.isTTY === true })}\n`;
 	if (!Bun.isMainThread) {
 		process.stderr.write(`${report}${formatFatalRecoveryHints(fatalRecoveryHintProviders)}`);
+		// An explicit exit alone leaves the parent only `close` with code 1; this reaches its `error` listeners.
+		reportError(err);
 		process.exit(1);
 	}
 	return exitAfterFatal(report, "Fatal error", err, Reason.UNHANDLED_REJECTION);

package/src/procmgr.ts

@@ -142,7 +142,7 @@ export function resolveBasicShell(): string | undefined {
  * Resolve the external shell to advertise on Windows.
  *
  * A host bash is OPTIONAL: bash tool commands always execute in the embedded
- * brush-core shell. The resolved binary only serves the spawn-a-shell paths
+ * bash engine (pi-shell). The resolved binary only serves the spawn-a-shell paths
  * (interactive PTY sessions, ACP client terminals, SHELL env), so this
  * prefers a real Git Bash when one exists and otherwise falls back to
  * cmd.exe — it never fails.

package/src/ptree.ts

@@ -7,6 +7,7 @@
  * - Convenience helpers: captureText / execText, AbortSignal, timeouts.
  */
 
+import * as os from "node:os";
 import { Process, type ProcessTerminateOptions } from "@linxiraos/pi-natives";
 import type { Spawn, Subprocess } from "bun";
 
@@ -15,8 +16,8 @@ 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">;
 
-const LINUX_SUBREAPER_COMMAND_ENV = "OMP_PTREE_SUBREAPER_COMMAND";
-const LINUX_SUBREAPER_BUN_BE_BUN_ENV = "OMP_PTREE_SUBREAPER_BUN_BE_BUN";
+const LINUX_SUBREAPER_COMMAND_ENV = "ZETA_PTREE_SUBREAPER_COMMAND";
+const LINUX_SUBREAPER_BUN_BE_BUN_ENV = "ZETA_PTREE_SUBREAPER_BUN_BE_BUN";
 const SUBREAPER_KILL_WINDOW_MS = 100;
 const SUBREAPER_KILL_POLL_MS = 5;
 
@@ -183,18 +184,22 @@ export class ChildProcess<In extends InMask = InMask> {
 	#stderrDone: Promise<void>;
 	#exited: Promise<number>;
 	#openPipeReaders = 1;
-	// Set by attachTimeout() at the command deadline; untimed commands keep
-	// complete EOF-based capture. Active pipe readers are cancelled at cutoff so
-	// their pending read() settles as done and partial output is kept.
+	// Set at the command deadline or on abort; otherwise commands keep complete
+	// EOF-based capture. Active pipe readers are cancelled at cutoff so their
+	// pending read() settles as done and partial output is kept.
 	#cutoff = false;
-	/** Readers of piped stdio; the timeout cancels them so pending reads settle. */
+	/** Readers of piped stdio; timeout and abort cancel them so pending reads settle. */
 	#pipeReaders = new Set<{ cancel(reason?: unknown): Promise<void> }>();
+	// Each registration reconciles its listener with root-exit and reader activity.
+	// Keeping the registration after idle lets a later output read re-arm the signal.
+	#abortRegistrations?: Set<() => void>;
 	#timeoutTimer?: NodeJS.Timeout;
 	#stderrStream?: ReadableStream<Uint8Array>;
 	// Termination in flight after kill(); aborted exits await it before reporting.
 	#terminating?: Promise<boolean | void>;
-	// A hard subreaper sweep must remain authoritative across overlapping kill requests.
-	#hardKillSweep?: Promise<void>;
+	// The one stop sequence of a subreaper-supervised command; a later hard
+	// kill request ends its grace period, and any other later request is a no-op.
+	#subreaperStop?: { escalate: () => void };
 	#terminateGroup: boolean;
 	#hardKillTree: boolean;
 	// Windows has no process groups. Retaining the root's native handle pins
@@ -247,11 +252,13 @@ export class ChildProcess<In extends InMask = InMask> {
 			this.#openPipeReaders--;
 			this.#stderrTail += dec.decode();
 			trim();
+			this.#syncAbortListeners();
 		})();
 
 		proc.exited
 			.catch(() => null)
 			.then(async exitCode => {
+				this.#syncAbortListeners();
 				if (this.#exitReasonPending) {
 					this.#exitReason = this.#exitReasonPending;
 					reject(this.#exitReasonPending);
@@ -339,22 +346,31 @@ export class ChildProcess<In extends InMask = InMask> {
 			// group leader; wait() still needs to report the later deadline.
 			if (this.proc.exitCode !== null) this.#exitReason = reason;
 		}
-		// An AbortSignal can race a timeout after its hard subreaper sweep has
-		// started. Do not replace that sweep with a normal root termination: the
-		// root must stay alive until adopted descendants have been collected.
-		if (this.#hardKillSweep) return;
-		if (gracefulMs !== undefined && gracefulMs < 0 && this.#hardKillTree && this.proc.exitCode === null) {
-			// Keep the subreaper alive while descendants are killed. A single
-			// killTree() snapshot can miss a worker whose parent exits during the
-			// walk and reparents it to the subreaper after that root was enumerated.
-			const root = Process.fromPid(this.proc.pid);
+		// A command under the Linux subreaper is stopped without ever signalling
+		// the subreaper politely: SIGTERM would end it, its orphaned descendants
+		// would reparent to init, and the SIGKILL that follows would not find a
+		// descendant that ignored SIGTERM. One stop sequence serves every kill
+		// request; a hard request during its grace period ends the grace early.
+		if (this.#subreaperStop) {
+			if (gracefulMs !== undefined && gracefulMs < 0) this.#subreaperStop.escalate();
+			return;
+		}
+		if (this.#hardKillTree && this.proc.exitCode === null && this.proc.signalCode === null) {
+			let root: Process | null = null;
+			try {
+				root = Process.fromPid(this.proc.pid);
+			} catch {
+				// No usable native handle: the direct-signal fallback below still ends the subreaper.
+			}
 			if (root) {
-				const sweep = this.#hardKillSubreaperTree(root).catch(e => void e);
-				this.#hardKillSweep = sweep;
-				this.#terminating = sweep;
-				void sweep.finally(() => {
-					if (this.#hardKillSweep === sweep) this.#hardKillSweep = undefined;
-				});
+				const { promise: escalated, resolve: escalate } = Promise.withResolvers<void>();
+				const graceMs = gracefulMs === undefined ? 1000 : gracefulMs;
+				if (graceMs < 0) escalate();
+				// A stop that fails part-way (a native handle that cannot be used)
+				// must not count as a finished termination: signal the subreaper directly.
+				const stop = this.#stopSubreaperTree(root, graceMs, escalated).catch(() => this.#signalChild(graceMs));
+				this.#subreaperStop = { escalate };
+				this.#terminating = stop;
 				return;
 			}
 		}
@@ -421,6 +437,57 @@ export class ChildProcess<In extends InMask = InMask> {
 		if (this.proc.exitCode === null && this.proc.signalCode === null) signal("SIGKILL");
 	}
 
+	/**
+	 * Stop a subreaper-supervised command: SIGTERM to each of the subreaper's
+	 * children and their trees (never the subreaper itself), then, after
+	 * `gracefulMs`, the subreaper's own exit, or `escalated`, the hard sweep.
+	 * A negative `gracefulMs` skips the SIGTERM; zero sends it and sweeps at once.
+	 * The subreaper stays alive through the grace period, so a descendant
+	 * orphaned in it is still the subreaper's child when the sweep runs.
+	 *
+	 * A subreaper with no child has not launched the command yet (or the
+	 * command has ended). It is looked at again while frozen with SIGSTOP and,
+	 * when still childless, killed, so a command cancelled before its launch
+	 * never starts. Freeze, kill and resume all go through `root`, the native
+	 * handle pinned to the subreaper's identity, never through the numeric pid:
+	 * once the subreaper has been reaped and its pid reused, they signal
+	 * nothing. The resume runs on every way out of the frozen section,
+	 * including a throw; it is a no-op on a killed subreaper. The grace timer is
+	 * cleared as soon as the sequence moves on, so a finished stop never keeps
+	 * the caller's process alive.
+	 */
+	async #stopSubreaperTree(root: Process, gracefulMs: number, escalated: Promise<void>): Promise<void> {
+		let children = root.children();
+		if (children.length === 0) {
+			try {
+				root.killTree(os.constants.signals.SIGSTOP);
+				children = root.children();
+				if (children.length === 0) {
+					root.killTree(9);
+					return;
+				}
+				// It launched the command just before the freeze: the first wave
+				// goes to the snapshot taken while it cannot fork.
+				for (const child of children) child.killTree(gracefulMs < 0 ? 9 : 15);
+			} finally {
+				root.killTree(os.constants.signals.SIGCONT);
+			}
+		} else {
+			// The subreaper launches one command; once it has a child, no later launch can escape the snapshot.
+			for (const child of children) child.killTree(gracefulMs < 0 ? 9 : 15);
+		}
+		if (gracefulMs >= 0) {
+			const { promise: graceOver, resolve: endGrace } = Promise.withResolvers<void>();
+			const graceTimer = setTimeout(endGrace, gracefulMs);
+			try {
+				await Promise.race([this.proc.exited, graceOver, escalated]);
+			} finally {
+				clearTimeout(graceTimer);
+			}
+		}
+		await this.#hardKillSubreaperTree(root);
+	}
+
 	async #hardKillSubreaperTree(root: Process): Promise<void> {
 		try {
 			const deadline = Date.now() + SUBREAPER_KILL_WINDOW_MS;
@@ -460,12 +527,13 @@ export class ChildProcess<In extends InMask = InMask> {
 	}
 
 	/**
-	 * Read a pipe fully, stopping early only at an explicit command deadline.
+	 * Read a pipe fully, stopping early only at an explicit command deadline or abort.
 	 */
 	async #readStream(stream: ReadableStream<Uint8Array>): Promise<string> {
-		this.#openPipeReaders++;
 		const reader = stream.getReader();
+		this.#openPipeReaders++;
 		this.#pipeReaders.add(reader);
+		this.#syncAbortListeners();
 		const dec = new TextDecoder();
 		let out = "";
 		try {
@@ -481,15 +549,18 @@ export class ChildProcess<In extends InMask = InMask> {
 		} catch {
 			// A cancelled or failed read keeps whatever was already collected.
 		}
+		const tail = dec.decode();
 		this.#pipeReaders.delete(reader);
 		this.#openPipeReaders--;
-		return out + dec.decode();
+		this.#syncAbortListeners();
+		return out + tail;
 	}
 
 	async #readBytes(): Promise<Uint8Array<ArrayBuffer>> {
 		const reader = this.proc.stdout.getReader();
 		this.#openPipeReaders++;
 		this.#pipeReaders.add(reader);
+		this.#syncAbortListeners();
 		const chunks: Uint8Array[] = [];
 		let length = 0;
 		try {
@@ -509,6 +580,7 @@ export class ChildProcess<In extends InMask = InMask> {
 			this.#pipeReaders.delete(reader);
 			this.#openPipeReaders--;
 			reader.releaseLock();
+			this.#syncAbortListeners();
 		}
 		const bytes = new Uint8Array(length);
 		let offset = 0;
@@ -591,11 +663,49 @@ export class ChildProcess<In extends InMask = InMask> {
 	// ── Signal / timeout ─────────────────────────────────────────────────
 
 	attachSignal(signal: AbortSignal): void {
-		const cleanup = this.#exited.catch(() => {});
-		const onAbort = () => this.kill(new AbortError(signal.reason, "<cancelled>"));
-		if (signal.aborted) return void onAbort();
-		signal.addEventListener("abort", onAbort, { once: true });
-		cleanup.finally(() => signal.removeEventListener("abort", onAbort));
+		this.#exited.catch(() => {});
+		let attached = false;
+		const onAbort = () => {
+			// The { once: true } listener has removed itself at this point.
+			attached = false;
+			const rootRunning = this.proc.exitCode === null && this.proc.signalCode === null;
+			if (rootRunning || this.#openPipeReaders > 0) {
+				this.#abortRegistrations?.delete(sync);
+			}
+			this.kill(new AbortError(signal.reason, "<cancelled>"));
+			this.#cutoffOutput();
+		};
+		const sync = () => {
+			const rootRunning = this.proc.exitCode === null && this.proc.signalCode === null;
+			// A detached group leader can exit before its surviving descendants do
+			// (a SIGTERM-ignoring child keeps the session's pipes open). Keep the
+			// registration while the root is gone but the group is still ours, so
+			// an abort that arrives after the graceful stop still records AbortError
+			// and cancels the lingering tree — not just while our own readers are live.
+			const groupMaySurvive = this.#terminateGroup && this.proc.exitCode !== null;
+			const active = rootRunning || this.#openPipeReaders > 0 || groupMaySurvive;
+			if (signal.aborted) {
+				if (active) onAbort();
+				return;
+			}
+			if (active === attached) return;
+			if (active) signal.addEventListener("abort", onAbort, { once: true });
+			else signal.removeEventListener("abort", onAbort);
+			attached = active;
+		};
+		(this.#abortRegistrations ??= new Set()).add(sync);
+		if (signal.aborted) onAbort();
+		else sync();
+	}
+
+	#syncAbortListeners(): void {
+		if (!this.#abortRegistrations) return;
+		for (const sync of this.#abortRegistrations) sync();
+	}
+
+	#cutoffOutput(): void {
+		this.#cutoff = true;
+		for (const reader of this.#pipeReaders) reader.cancel().catch(() => {});
 	}
 
 	#clearTimeout(): void {
@@ -605,7 +715,9 @@ export class ChildProcess<In extends InMask = InMask> {
 	}
 
 	attachTimeout(ms: number): void {
-		if (ms <= 0 || this.proc.killed) return;
+		// Not skipped for a root Bun already reports as exited (`proc.killed`): it can
+		// exit before spawn() returns, while a descendant still holds its pipes.
+		if (ms <= 0) return;
 		this.#exited.catch(() => {});
 		// One unref'd deadline controls both termination and pipe collection.
 		// A clean command clears it in wait(), so fast invocations do not hold
@@ -620,8 +732,7 @@ export class ChildProcess<In extends InMask = InMask> {
 			) {
 				this.kill(new TimeoutError(ms, this.#stderrTail), -1);
 			}
-			this.#cutoff = true;
-			for (const reader of this.#pipeReaders) reader.cancel().catch(() => {});
+			this.#cutoffOutput();
 		}, ms);
 		timer.unref?.();
 		this.#timeoutTimer = timer;

package/src/stderr-guard.ts

@@ -14,9 +14,14 @@
  * so diagnostics stay greppable and Bun native-crash reports (which abort
  * before any JS cleanup can restore fd 2) are preserved.
  *
- * Only dup/dup2 go through bun:ffi. fcntl is deliberately avoided: it is
- * variadic, and the arm64-darwin ABI passes variadic arguments on the stack,
- * so a fixed-arity FFI signature would read garbage for the third argument.
+ * Only dup2 goes through bun:ffi. The saved copy of fd 2 comes from opening
+ * `/dev/fd/2` instead of `dup(2)`, because Bun opens files close-on-exec: a
+ * plain dup would leak the terminal into every child spawned without explicit
+ * fd handling (Rust `Command`, gitoxide filter drivers), which could then read
+ * the user's keystrokes and terminal replies. fcntl is deliberately avoided:
+ * it is variadic, and the arm64-darwin ABI passes variadic arguments on the
+ * stack, so a fixed-arity FFI signature would read garbage for the third
+ * argument.
  */
 import { dlopen, FFIType } from "bun:ffi";
 import * as fs from "node:fs";
@@ -27,7 +32,6 @@ const STDOUT_FILENO = 1;
 const STDERR_FILENO = 2;
 
 interface LibcFdOps {
-	dup(fd: number): number;
 	dup2(oldFd: number, newFd: number): number;
 }
 
@@ -44,7 +48,6 @@ function libcFdOps(): LibcFdOps | null {
 	for (const candidate of candidates) {
 		try {
 			const libc = dlopen(candidate, {
-				dup: { args: [FFIType.i32], returns: FFIType.i32 },
 				dup2: { args: [FFIType.i32, FFIType.i32], returns: FFIType.i32 },
 			});
 			libcFdOpsCache = libc.symbols;
@@ -102,6 +105,15 @@ export function suppressTerminalStderr(options?: SuppressTerminalStderrOptions):
 	const libc = libcFdOps();
 	if (!libc) return false;
 
+	// First, so a fd 2 that cannot be reopened (a socket: Linux refuses
+	// `/dev/fd/N` for those) leaves the guard inert with no redirect file made.
+	let saved: number;
+	try {
+		saved = fs.openSync(`/dev/fd/${STDERR_FILENO}`, fs.constants.O_WRONLY);
+	} catch {
+		return false;
+	}
+
 	let redirectFd: number;
 	try {
 		const redirectPath = options?.redirectPath ?? redirectTarget ?? getLogPath();
@@ -115,15 +127,11 @@ export function suppressTerminalStderr(options?: SuppressTerminalStderrOptions):
 		try {
 			redirectFd = fs.openSync("/dev/null", "w");
 		} catch {
+			fs.closeSync(saved);
 			return false;
 		}
 	}
 
-	const saved = libc.dup(STDERR_FILENO);
-	if (saved === -1) {
-		fs.closeSync(redirectFd);
-		return false;
-	}
 	if (libc.dup2(redirectFd, STDERR_FILENO) === -1) {
 		fs.closeSync(redirectFd);
 		fs.closeSync(saved);