@hydraharness/harness-shell 0.1.1-rc.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,51 @@
+# @hydraharness/harness-shell
+
+The **`ShellExecutor`** (`ctx.shell`) defines WHAT a bash backend does — run foreground commands and start background processes — without saying HOW. Job ids, ownership, collection, cancellation, and notices belong to the generic `ctx.jobs` runtime.
+
+This package owns the Service Definition role of the bash capability, split so each role can evolve (and be swapped) independently:
+
+| Package | Role |
+|---|---|
+| `@hydraharness/harness-shell` (this) | Service Definition: abstract service + vocabulary types |
+| `@hydraharness/harness-bash-local` | Service Provider: local subprocesses |
+| `@hydraharness/harness-bash-sandbox` | Service Provider: `@hydraharness/harness-bash-local`'s mechanics with every spawn confined via [`ctx.sandbox`](../../sandbox/sandbox/), denials reported as result facts |
+| `@hydraharness/harness-tool-bash` | the model-facing tool schemas over `ctx.shell` |
+
+The split is a standard capability seam ([capability-seams Agent Note](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)): `@hydraharness/harness-bash-sandbox` is a sandboxing executor behind the same Service Definition — the Consumer detects its `sandboxMode` capability and adds escalation fields without importing the provider — and a containerized or remote executor slots in the same way.
+
+## Service API (`ctx.shell`)
+
+| Member | Semantics |
+|---|---|
+| `run(spec)` | Foreground execution. Resolves when the command finishes. **Rejects only for infrastructure failures** (unusable workdir, missing shell, pre-aborted signal); nonzero exits, timeout kills, and abort kills resolve with a descriptive `ShellRunResult`. |
+| `start(spec)` | Background execution. Returns a task-free `ShellProcess` handle immediately; **no timeout applies**. The caller may adapt it into `ctx.jobs`. |
+| `sandboxMode` | The capability fact for the tool layer: the default mode a SANDBOXING executor confines under (`undefined` in the base class — "this executor does not sandbox"). `@hydraharness/harness-tool-bash` reads it at registration to advertise the escalation fields only when the composition honors them. |
+| `ShellProcess.readOutput()` | **Incremental** output read — consecutive reads never re-deliver. Reads that lost data to buffer bounds flag `lossy` and point at full-stream spill files. |
+| `ShellProcess.kill()` | Kill the process group. Returns `false` when it already finished. |
+
+Implementations subclass `ShellExecutor` and implement the abstract methods. Disposal must kill every running process and await its exit.
+
+`SHELL_SETTINGS_NAMESPACE` (`bash`) is exported here rather than by a provider because it names the capability, not an implementation. A host composes exactly one provider of `ctx.shell` — the win32 layer swaps the POSIX rows for the pwsh ones, and mounting both fails loud on a duplicate service registration — so every provider can register this one namespace with its own schema and composition entry without two of them ever colliding, and a `settings.yaml` carried between platforms keeps resolving on both.
+
+## Vocabulary
+
+`ShellExecRequest` (command, workdir?, timeoutMs?, stdoutMaxBytes?, signal?, stdin?, env?, hydraEnv?, sandboxPolicy?) resolves to `ShellExecSpec` (command, workdir, timeoutMs, stdoutMaxBytes, signal?, stdin?, env?, hydraEnv?, sandboxPolicy) before execution. `stdoutMaxBytes` is a trusted foreground-run capture budget for consumers that must parse complete bounded stdout; the model-facing bash tool does not expose it. `sandboxPolicy` is optional on the request and required-but-nullable on the resolved spec: it carries the complete per-call mode and workspace root. The sandbox tool path resolves it from the calling session through `ctx.sandboxPolicy`; a direct sandbox-executor caller falls back to deployment policy, while a non-sandboxing executor carries the field and confines nothing.
+
+The per-session sandbox-mode override vocabulary (the `'sandbox/mode'` event, the `effectiveSandboxMode(events)` fold, and the `setSandboxMode(session, mode)` write path) is NOT here — it is policy state shared by every enforcing family, owned by [`@hydraharness/harness-sandbox-policy`](../../sandbox/sandbox-policy/). `run()` returns `ShellRunResult`; `start()` returns `ShellProcess`, whose incremental read and kill methods are adapted by `@hydraharness/harness-tool-bash` into a generic task registration. A sandboxing executor stamps `ShellSandboxInfo` on foreground results and settled process handles. See `src/types.ts` and [subsystems/shell.md](../../../docs/subsystems/shell.md).
+
+`stdin` and ordinary `env` are set by in-process plugins (the hooks bridges, native plugins) to feed a hook command its JSON payload and `CLAUDE_PROJECT_DIR`/`CLAUDE_PLUGIN_ROOT` values. `hydraEnv` is a separate trusted overlay restricted by type to managed keys; the exported `HYDRA_ENV_PREFIX` is the single source for that namespace, its `HydraEnvironmentKey` template type, executor scrubbing, registry validation, derived built-in names, and model guidance. Model bash uses the current snapshot collected by `ctx.shellEnv`. Implementations remove inherited managed keys, then merge `hydraEnv` after ordinary `env`, so an omitted current fact cannot fall back to stale ambient state and an `env` entry cannot displace a managed value. The model-facing tool exposes none of these as parameters. All three remain optional on the resolved spec; absent means no input/overlay. See [the bash-stdin-env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-api.md) and [the session environment Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md).
+
+The exported `parseExitStatus` (with `ParsedExitStatus`) is the shared rendering contract half of the shell tools: the inverse of the `[exit code: N]` / `[killed by signal: X]` markers `@hydraharness/harness-tool-bash`'s `renderResult` and `@hydraharness/harness-tool-pwsh`'s `renderPwshResult` append. Both tools' `presentResult` use it to split the rendered text into the terminal card's output body and its exit-status pill; it lives with the Service Definition so the two tools never drift on the marker contract.
+
+## Model Experience
+
+Indirectly, through `@hydraharness/harness-tool-bash`, which turns executor output and sandbox facts into guidance and retained tool-result tokens.
+
+#### KV Cache effect
+
+No direct invalidation; the named consumer owns any request-prefix changes.
+
+## Known Limitations and Deferred Work
+
+- **No interactive-input vocabulary** — `stdin` is written once at spawn and closed; the seam has no channel to feed a running task and no PTY session concept.
+- **Foreground timeouts are always executor-owned** — a caller-owned-deadline mode on the seam is explicitly deferred by [the tool-call timeout-policy Agent Note](../../../.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.md).

package/lib/index.js

@@ -0,0 +1,96 @@
+import { Service } from "@hydraharness/cordis";
+import { settingsNamespace } from "@hydraharness/harness-settings";
+import { HYDRA_ENV_PREFIX } from "@hydraharness/harness-subprocess";
+//#region lib/types/render.js
+/**
+* Shared rendering helpers for the shell tools (`@hydraharness/harness-tool-bash`,
+* `@hydraharness/harness-tool-pwsh`): the exit-status marker contract the tools' renderers
+* emit and the presentation layer parses back.
+* @module @hydraharness/harness-shell/render
+*/
+/**
+* Split a rendered shell-tool result string into its output body and the
+* structured exit status — the inverse of the `[exit code: N]` /
+* `[killed by signal: X]` markers the shell tools' renderers append. A killed
+* marker yields `signal`; otherwise a non-zero marker yields `exitCode`;
+* absent both means a clean exit 0.
+*
+* The consumed marker is removed from `body` because a terminal presentation
+* shows the exit status as its own pill: leaving the marker in the output
+* would render the exit twice. Other markers (timeout, sandbox denial) carry
+* facts no pill shows, so they stay in the body.
+*
+* Replay only retains the rendered content text, not the original
+* `ShellRunResult`, so terminal presentation must recover the exit pill here.
+* Requiring a leading newline and the end of the string keeps ordinary output
+* that merely ends with marker-like text from matching unless the final line
+* is indistinguishable from a real marker.
+* @param text - rendered model-facing shell-tool result.
+* @returns the marker-free body plus the recovered terminal exit code or signal.
+*/
+function parseExitStatus(text) {
+	const signal = /\n\[killed by signal: ([^\]\n]+)\]$/.exec(text);
+	if (signal?.[1] !== void 0) return {
+		body: text.slice(0, signal.index),
+		signal: signal[1]
+	};
+	const exit = /\n\[exit code: (\d+)\]$/.exec(text);
+	if (exit?.[1] !== void 0) return {
+		body: text.slice(0, exit.index),
+		exitCode: Number(exit[1])
+	};
+	return {
+		body: text,
+		exitCode: 0
+	};
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* Service Definition for the `ctx.shell` capability seam, covering foreground commands and background process
+* handles. Job ids, ownership, polling, and notices belong to
+* `@hydraharness/harness-jobs`, keeping executors independent of sessions.
+* @module @hydraharness/harness-shell
+*/
+/**
+* Settings namespace of this capability, owned here rather than by either
+* executor family because it names the capability, not an implementation: a
+* host composes exactly one provider of `ctx.shell` (the win32 layer swaps the
+* POSIX rows for the pwsh ones, and mounting both fails loud on a duplicate
+* service registration), so the providers share one namespace without ever
+* registering it twice, and a settings document carried between platforms
+* keeps resolving on both.
+*/
+const SHELL_SETTINGS_NAMESPACE = settingsNamespace("shell");
+/**
+* Abstract bash execution service. Subclass, implement the abstract methods,
+* and load the subclass as a plugin — it registers as `ctx.shell` (one
+* implementation per context; loading a second throws, which is cordis'
+* standard duplicate-service behavior).
+*
+* Implementations must honor these semantics:
+* - {@link run} rejects only for infrastructure failures. Nonzero exits,
+*   timeout kills, and abort kills resolve with a {@link ShellRunResult}.
+* - {@link start} returns immediately; no timeout applies to background
+*   processes. `done` settles at process close and never rejects; spawn
+*   failures settle as `killed` with the error on stderr.
+* - {@link ShellProcess.readOutput} is incremental: consecutive reads never
+*   repeat output. Lossy reads report truncation and available spill files.
+* - A still-running background process is stopped and awaited when its
+*   owning composition tears down. With the subprocess seam that
+*   boundary is `ctx.subprocess` disposal, so a background process survives
+*   an executor-only reload.
+*/
+var ShellExecutor = class extends Service {
+	constructor(ctx) {
+		super(ctx, "shell");
+	}
+	/**
+	* The sandbox mode this executor applies by default, or `undefined` when it
+	* does not sandbox commands.
+	* @returns the configured default sandbox mode, when supported.
+	*/
+	get sandboxMode() {}
+};
+//#endregion
+export { HYDRA_ENV_PREFIX, SHELL_SETTINGS_NAMESPACE, ShellExecutor, ShellExecutor as default, parseExitStatus };

package/lib/invariant.js

@@ -0,0 +1,17 @@
+//#region lib/types/invariant.js
+/** Package-owned invariant companion for the bash seam. @module @hydraharness/harness-shell/invariant */
+const PACKAGE_NAME = "@hydraharness/harness-shell";
+/** Cordis companion plugin name. */
+const name = "shell-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/** No runtime invariant: this stateless Service Definition owns request/result types, while executors and policy own observations. */
+const install = () => {};
+/**
+* Register the bash invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Service Definition for the `ctx.shell` capability seam, covering foreground commands and background process
+ * handles. Job ids, ownership, polling, and notices belong to
+ * `@hydraharness/harness-jobs`, keeping executors independent of sessions.
+ * @module @hydraharness/harness-shell
+ */
+import { Context, Service } from '@hydraharness/cordis';
+import type { SandboxMode } from '@hydraharness/harness-sandbox';
+import type { ShellExecRequest, ShellExecSpec, ShellProcess, ShellRunResult } from './types.ts';
+/**
+ * Settings namespace of this capability, owned here rather than by either
+ * executor family because it names the capability, not an implementation: a
+ * host composes exactly one provider of `ctx.shell` (the win32 layer swaps the
+ * POSIX rows for the pwsh ones, and mounting both fails loud on a duplicate
+ * service registration), so the providers share one namespace without ever
+ * registering it twice, and a settings document carried between platforms
+ * keeps resolving on both.
+ */
+export declare const SHELL_SETTINGS_NAMESPACE: import("@hydraharness/harness-settings").SettingsNamespace;
+export { HYDRA_ENV_PREFIX } from './types.ts';
+export type { ShellExecRequest, ShellExecSpec, ShellProcess, ShellProcessRead, ShellProcessStatus, ShellRunResult, ShellSandboxInfo, CollectedOutput, HydraEnvironment, HydraEnvironmentKey, } from './types.ts';
+export { parseExitStatus } from './render.ts';
+export type { ParsedExitStatus } from './render.ts';
+declare module '@hydraharness/cordis' {
+    interface Context {
+        shell: ShellExecutor;
+    }
+}
+/**
+ * Abstract bash execution service. Subclass, implement the abstract methods,
+ * and load the subclass as a plugin — it registers as `ctx.shell` (one
+ * implementation per context; loading a second throws, which is cordis'
+ * standard duplicate-service behavior).
+ *
+ * Implementations must honor these semantics:
+ * - {@link run} rejects only for infrastructure failures. Nonzero exits,
+ *   timeout kills, and abort kills resolve with a {@link ShellRunResult}.
+ * - {@link start} returns immediately; no timeout applies to background
+ *   processes. `done` settles at process close and never rejects; spawn
+ *   failures settle as `killed` with the error on stderr.
+ * - {@link ShellProcess.readOutput} is incremental: consecutive reads never
+ *   repeat output. Lossy reads report truncation and available spill files.
+ * - A still-running background process is stopped and awaited when its
+ *   owning composition tears down. With the subprocess seam that
+ *   boundary is `ctx.subprocess` disposal, so a background process survives
+ *   an executor-only reload.
+ */
+export declare abstract class ShellExecutor extends Service {
+    constructor(ctx: Context);
+    /**
+     * The sandbox mode this executor applies by default, or `undefined` when it
+     * does not sandbox commands.
+     * @returns the configured default sandbox mode, when supported.
+     */
+    get sandboxMode(): SandboxMode | undefined;
+    /**
+     * Apply implementation-owned defaults and caps to a request before execution.
+     * @param request - the caller's request; omitted fields get this
+     *   implementation's defaults, capped fields are clamped.
+     * @returns the fully-specified spec to hand to {@link run}/{@link start}.
+     */
+    abstract resolve(request: ShellExecRequest): ShellExecSpec;
+    /**
+     * Run a command in the foreground; resolves when it finishes.
+     * @param spec - a resolved spec from {@link resolve}, never a raw request.
+     * @returns the outcome; nonzero exits, timeout kills, and abort kills
+     *   resolve with a descriptive result rather than reject.
+     */
+    abstract run(spec: ShellExecSpec): Promise<ShellRunResult>;
+    /**
+     * Start a background process and return its handle immediately.
+     * @param spec - a resolved spec from {@link resolve}, never a raw request.
+     * @returns the live process handle (reads, kill, quiescence promise).
+     */
+    abstract start(spec: ShellExecSpec): ShellProcess;
+}
+export default ShellExecutor;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,13 @@
+/** Package-owned invariant companion for the bash seam. @module @hydraharness/harness-shell/invariant */
+import type { Context } from '@hydraharness/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "shell-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register the bash invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/render.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Shared rendering helpers for the shell tools (`@hydraharness/harness-tool-bash`,
+ * `@hydraharness/harness-tool-pwsh`): the exit-status marker contract the tools' renderers
+ * emit and the presentation layer parses back.
+ * @module @hydraharness/harness-shell/render
+ */
+/**
+ * The exit status recovered from a rendered result, with the output body that
+ * status was split off from.
+ */
+export type ParsedExitStatus = {
+    body: string;
+} & ({
+    exitCode: number;
+} | {
+    signal: string;
+});
+/**
+ * Split a rendered shell-tool result string into its output body and the
+ * structured exit status — the inverse of the `[exit code: N]` /
+ * `[killed by signal: X]` markers the shell tools' renderers append. A killed
+ * marker yields `signal`; otherwise a non-zero marker yields `exitCode`;
+ * absent both means a clean exit 0.
+ *
+ * The consumed marker is removed from `body` because a terminal presentation
+ * shows the exit status as its own pill: leaving the marker in the output
+ * would render the exit twice. Other markers (timeout, sandbox denial) carry
+ * facts no pill shows, so they stay in the body.
+ *
+ * Replay only retains the rendered content text, not the original
+ * `ShellRunResult`, so terminal presentation must recover the exit pill here.
+ * Requiring a leading newline and the end of the string keeps ordinary output
+ * that merely ends with marker-like text from matching unless the final line
+ * is indistinguishable from a real marker.
+ * @param text - rendered model-facing shell-tool result.
+ * @returns the marker-free body plus the recovered terminal exit code or signal.
+ */
+export declare function parseExitStatus(text: string): ParsedExitStatus;
+//# sourceMappingURL=render.d.ts.map

package/lib/types/types.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Execution types for the bash executor seam. Background job semantics belong
+ * to `@hydraharness/harness-jobs`; this seam exposes only process handles. The
+ * managed-environment and captured-output vocabulary is owned by the
+ * subprocess seam and re-exported here so bash consumers keep one import
+ * root.
+ * @module hydra-shell/types
+ */
+import type { SandboxEnforcement, SandboxExecutionPolicy, SandboxMode } from '@hydraharness/harness-sandbox';
+import type { CollectedOutput, HydraEnvironment } from '@hydraharness/harness-subprocess';
+export { HYDRA_ENV_PREFIX } from '@hydraharness/harness-subprocess';
+export type { CollectedOutput, HydraEnvironment, HydraEnvironmentKey } from '@hydraharness/harness-subprocess';
+/**
+ * Sandbox facts for one run, present iff a sandboxing executor handled it.
+ * Facts are reported independently of process exit status so callers can
+ * distinguish command failures from policy denials and runner failures.
+ */
+export interface ShellSandboxInfo {
+    /** The mode the command actually ran under. */
+    mode: SandboxMode;
+    /** Whether the sandbox denied a file operation. */
+    denied: boolean;
+    /** How completely the selected runner enforced the requested mode. */
+    enforcement?: SandboxEnforcement;
+    /** Whether the sandbox runner failed before the command could run. */
+    runnerFailed?: boolean;
+}
+/**
+ * A caller's execution REQUEST: `workdir` and `timeoutMs` are optional and
+ * filled by {@link ShellExecutor.resolve} from the implementation's config.
+ * This is the model-/plugin-facing shape; pass it to `resolve()` to obtain a
+ * fully-resolved {@link ShellExecSpec}.
+ */
+export interface ShellExecRequest {
+    command: string;
+    /** Working directory override (default: implementation-configured). */
+    workdir?: string | undefined;
+    /** Timeout override in milliseconds (implementations cap it). */
+    timeoutMs?: number | undefined;
+    /**
+     * Foreground stdout capture budget in bytes. Absent uses the executor's
+     * default output cap. Trusted in-process consumers use this when they must
+     * parse complete stdout up to their own bounded limit; the model-facing bash
+     * tool does not expose it as a parameter.
+     */
+    stdoutMaxBytes?: number | undefined;
+    /** Abort signal — implementations kill the command when it fires. */
+    signal?: AbortSignal | undefined;
+    /**
+     * Bytes to write to the command's stdin, then close it. Absent leaves stdin
+     * closed/empty (the default for model-driven tool calls). Set by in-process
+     * plugins (e.g. the hooks bridges, which write a hook command's JSON payload
+     * to its stdin); the model-facing bash tool does not expose it as a parameter
+     * (a model that needs stdin uses shell syntax like a heredoc or a pipe).
+     */
+    stdin?: string | undefined;
+    /**
+     * Ordinary environment entries for the command, merged after the credential
+     * scrub. Managed facts belong in {@link hydraEnv}, which merges after this
+     * map, so an entry here can never displace one. Set by in-process plugins
+     * (the hooks bridges set `CLAUDE_PROJECT_DIR`, `CLAUDE_PLUGIN_ROOT`, …); the
+     * model-facing bash tool does not expose it as a parameter.
+     */
+    env?: Record<string, string> | undefined;
+    /**
+     * Harness-owned `HYDRA_*` variables for this execution (typed to managed
+     * keys). Executors discard ambient `HYDRA_*` entries before merging this
+     * snapshot last, so an unavailable current fact cannot inherit a stale
+     * value from the harness process and a caller {@link env} entry cannot
+     * displace a managed one.
+     */
+    hydraEnv?: HydraEnvironment | undefined;
+    /** Fully resolved per-call sandbox policy; sandboxing executors default it. */
+    sandboxPolicy?: SandboxExecutionPolicy | undefined;
+}
+/**
+ * A resolved execution spec. {@link ShellExecutor.resolve} fills and caps the
+ * required fields; {@link ShellExecutor.start} ignores `timeoutMs` because
+ * background processes have no executor timeout.
+ */
+export interface ShellExecSpec {
+    command: string;
+    workdir: string;
+    timeoutMs: number;
+    /**
+     * Resolved foreground stdout capture budget in bytes. `run()` uses it for
+     * stdout; background jobs and stderr keep the executor's own output cap.
+     */
+    stdoutMaxBytes: number;
+    /** Abort signal — implementations kill the command when it fires. */
+    signal?: AbortSignal | undefined;
+    /** Bytes to write to stdin before closing it; absent means no stdin. */
+    stdin?: string | undefined;
+    /**
+     * Ordinary environment entries carried through from
+     * {@link ShellExecRequest.env}; {@link hydraEnv} still merges after them.
+     * OPTIONAL on the spec for the same reason as `stdin`: absent means no
+     * ordinary extra environment.
+     */
+    env?: Record<string, string> | undefined;
+    /** Managed `HYDRA_*` snapshot (typed to managed keys); merges after {@link env}. */
+    hydraEnv?: HydraEnvironment | undefined;
+    /** Resolved sandbox policy; ignored by executors that do not confine. */
+    sandboxPolicy: SandboxExecutionPolicy | undefined;
+}
+/** The outcome of one completed (or killed) foreground run. */
+export interface ShellRunResult {
+    /** Exit code; null when the process died from a signal. */
+    exitCode: number | null;
+    /** Terminating signal (e.g. 'SIGTERM'); null on normal exit. */
+    signal: NodeJS.Signals | null;
+    /**
+     * True when the executor's own timeout was the FIRST cause to cut the command
+     * short. Mutually exclusive with {@link aborted}: one fused deadline drives
+     * both the timeout and the caller's cancellation, so a timeout and an abort
+     * racing before process close report the single first-abort cause, not both
+     * (see the [timeout-library Agent Note](../../../../.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md)).
+     */
+    timedOut: boolean;
+    /**
+     * True when the caller's `AbortSignal` was the FIRST cause to kill the command
+     * (and it was not the executor's own timeout). Mutually exclusive with
+     * {@link timedOut} — see there for the first-cause classification.
+     */
+    aborted: boolean;
+    /** The effective timeout applied to this run (after defaulting/capping). */
+    timeoutMs: number;
+    stdout: CollectedOutput;
+    stderr: CollectedOutput;
+    /** Sandbox execution facts, absent for an unsandboxed executor. */
+    sandbox?: ShellSandboxInfo;
+}
+/** Lifecycle of a background process. */
+export type ShellProcessStatus = 'running' | 'completed' | 'killed';
+/** One incremental {@link ShellProcess.readOutput} read. */
+export interface ShellProcessRead {
+    /** Output produced since the previous read (stderr in a marked section). */
+    delta: string;
+    /** True when truncation dropped unread bytes the delta cannot include. */
+    lossy: boolean;
+    /** Full stdout spill file, when stdout truncation occurred and a safe path is available. */
+    stdoutSpillPath?: string;
+    /** Full stderr spill file, when stderr truncation occurred and a safe path is available. */
+    stderrSpillPath?: string;
+}
+/**
+ * A background process handle returned by {@link ShellExecutor.start}. It is the
+ * only access path; buffered output remains readable after exit. Composition
+ * teardown (the subprocess service's disposal) kills running processes and
+ * awaits {@link done}; an executor-only reload leaves them running.
+ */
+export interface ShellProcess {
+    /** Process lifecycle state (settled exactly once). */
+    status: ShellProcessStatus;
+    /** Exit code once finished (null = killed by signal / still running). */
+    exitCode: number | null;
+    /** Terminating signal name, when signal-killed. */
+    signal: NodeJS.Signals | null;
+    /** Resolves when the underlying process closes (never rejects — a spawn failure settles as `killed` with the error on stderr). */
+    readonly done: Promise<void>;
+    /** Sandbox facts, stamped once a confined process settles. */
+    sandbox?: ShellSandboxInfo;
+    /**
+     * Read output produced since the previous read (consuming — consecutive
+     * reads never re-deliver). Reads that lost data flag `lossy` and point at
+     * full-stream spill files when available.
+     */
+    readOutput(): ShellProcessRead;
+    /**
+     * Kill the process group. Returns false when it had already finished
+     * (no-op); idempotent.
+     */
+    kill(): boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@hydraharness/harness-shell",
+  "description": "Abstract bash executor seam (ctx.shell) for the Hydra harness",
+  "version": "0.1.1-rc.5",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MaiHongPhong1902/Hydra-Harness.git",
+    "directory": "packages/shell/shell"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@hydraharness/harness-invariants": "^0.1.1-rc.5",
+    "@hydraharness/harness-sandbox": "^0.1.1-rc.5",
+    "@hydraharness/cordis": "^4.0.2",
+    "@hydraharness/harness-subprocess": "^0.1.1-rc.5",
+    "@hydraharness/harness-settings": "^0.1.1-rc.5"
+  },
+  "devDependencies": {
+    "@hydraharness/harness-subprocess": "^0.1.1-rc.5",
+    "@hydraharness/harness-invariants": "^0.1.1-rc.5",
+    "@hydraharness/cordis": "^4.0.2",
+    "@hydraharness/harness-sandbox": "^0.1.1-rc.5",
+    "@hydraharness/harness-settings": "^0.1.1-rc.5"
+  }
+}