@hasna-internal/kai-pwsh-sandbox 0.1.1-rc.2

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.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/shell/pwsh-sandbox/README.md
+README.md: 533b89b533084843a17153f3f3da39f21d271b04
+README.zh.md: 8607554d10562bc519f379030ccd9518cb63b3b6

package/README.md

@@ -0,0 +1,34 @@
+# @hasna-internal/kai-pwsh-sandbox
+
+English | [中文](README.zh.md)
+
+Sandbox-consuming PowerShell implementation of the [`ctx.shell` executor seam](../shell/): every command runs as `pwsh -NoLogo -NoProfile -NonInteractive -Command <command>` **confined through `ctx.sandbox`**, with the selected mode, enforcement, and denial facts stamped on each settled result. The pwsh twin of [`@hasna-internal/kai-bash-sandbox`](../bash-sandbox/), a call-for-call mirror per the [pwsh executor and tool decision](../../../.agents/notes/implemented/feature/2026-08-01-pwsh-tool-and-executor.md) — the confinement substance is platform-neutral: on Windows the sandbox seam resolves to the ACL restricted-token runner chain ([`@hasna-internal/kai-sandbox-windows-acl`](../../sandbox/sandbox-windows-acl/)), on Linux/macOS to bwrap/Landlock/Seatbelt.
+
+The executor inherits [`@hasna-internal/kai-pwsh-local`](../pwsh-local/)'s process mechanics and consumes its argv-level seam (`argv()` / `runArgv()` / `startArgv()` / `onProcessDone()`) to wrap the exact pwsh invocation through the provider. The sandbox policy (mode + workspace root) is NOT this package's config: it rides each call from `ctx.sandboxPolicy` (tool calls pass the calling session's resolved policy; direct calls fall back to deployment policy).
+
+## Behavior
+
+- `danger-full-access`: commands run through the local executor unchanged; results carry `sandbox: { mode, denied: false }`.
+- Confined modes (`read-only`, `workspace-write`): the pwsh argv is wrapped by `ctx.sandbox.confine()`; runner-launch refusal fails closed with `SANDBOX_UNAVAILABLE` (foreground throw, background `runnerFailed` fact), and a denied write classifies against the selected backend's `denialSignatures` into `sandbox.denied`.
+
+## Model Experience
+
+### Confinement works, denial surfaces as command failure
+
+#### What the model sees
+
+The confined command's own stderr (e.g. `Access to the path '...' is denied.` under the Windows ACL runner); the tool layer converts classified denials into the standard permission-denied surface exactly as it does for the bash tool.
+
+#### Token effect
+
+No model-visible text beyond the command's stderr and the tool layer's standard denial surface.
+
+#### KV Cache effect
+
+None directly; the denial surface belongs to the tool layer.
+
+## Known Limitations and Deferred Work
+
+- **Reads are unrestricted** on Windows (the ACL runner restricts writes only); the read boundary is documented in `@hasna-internal/kai-sandbox-windows-acl`.
+- **Windows workspace-write temp authority is private** per live session/workspace pair; agentless calls receive a fresh private directory per invocation. The ambient temp root is never granted, and the runner rewrites TMP/TEMP to the private directory before spawning.
+- **Windows read-only grants no explicit writable root but remains partial** because the restricted token must retain Everyone. Objects whose DACL grants Everyone write access — including compatible opens of the NUL device — remain ambient authority; PowerShell's `> $null` redirection still works without opening NUL.

package/README.zh.md

@@ -0,0 +1,34 @@
+# @hasna-internal/kai-pwsh-sandbox
+
+[English](README.md) | 中文
+
+沙盒消费型的 [`ctx.shell` 执行器 seam](../shell/) 的 PowerShell 实现：每条命令以 `pwsh -NoLogo -NoProfile -NonInteractive -Command <command>` 运行，**经 `ctx.sandbox` 隔离**，选定模式、强制完整性、拒绝事实都盖在每次结算的结果上。它是 [`@hasna-internal/kai-bash-sandbox`](../bash-sandbox/) 的 pwsh 孪生，按 [pwsh 执行器与工具决策](../../../.agents/notes/implemented/feature/2026-08-01-pwsh-tool-and-executor.zh.md) 逐调用镜像——隔离实体本身是平台无关的：Windows 上沙盒 seam 解析到 ACL 受限令牌 runner 链（[`@hasna-internal/kai-sandbox-windows-acl`](../../sandbox/sandbox-windows-acl/)），Linux/macOS 上解析到 bwrap/Landlock/Seatbelt。
+
+执行器继承 [`@hasna-internal/kai-pwsh-local`](../pwsh-local/) 的进程机制，并消费其 argv 级 seam（`argv()` / `runArgv()` / `startArgv()` / `onProcessDone()`）把精确的 pwsh 调用经 provider 包装。沙盒策略（模式 + 工作区根目录）不是本包的配置：每次调用由 `ctx.sandboxPolicy` 随行（工具层传调用会话解析后的策略；直接调用回退到部署策略）。
+
+## 行为
+
+- `danger-full-access`：命令经本地执行器原样运行；结果携带 `sandbox: { mode, denied: false }`。
+- 受限模式（`read-only`、`workspace-write`）：pwsh argv 由 `ctx.sandbox.confine()` 包装；runner 启动失败按 fail-closed 抛 `SANDBOX_UNAVAILABLE`（前台抛错、后台记 `runnerFailed` 事实），被拒绝的写按所选后端的 `denialSignatures` 分类为 `sandbox.denied`。
+
+## 模型体验
+
+### 隔离生效，拒绝以命令失败呈现
+
+#### 模型看到什么
+
+受限命令自身的 stderr（Windows ACL runner 下如 `Access to the path '...' is denied.`）；工具层把分类后的拒绝转成标准权限拒绝面，与 bash 工具完全一致。
+
+#### Token 影响
+
+除命令 stderr 与工具层标准拒绝面外，无额外模型可见文本。
+
+#### KV Cache 影响
+
+无直接影响；拒绝呈现面属于工具层。
+
+## 已知限制与后续工作
+
+- **Windows 上读不受限**（ACL runner 只限写）；读边界文档在 `@hasna-internal/kai-sandbox-windows-acl`。
+- **Windows workspace-write 的临时权限按每个活跃的会话/工作区对私有**；无 agent（智能体）的调用每次都获得一个新的私有目录。环境临时根目录绝不会被授权，runner 会在 spawn 前将 TMP/TEMP 重写为该私有目录。
+- **Windows read-only 不授予任何显式可写根目录，但仍为部分强制执行**，因为受限令牌必须保留 Everyone。DACL 向 Everyone 授予写访问的对象——包括以兼容方式打开的 NUL 设备——仍构成环境权限来源；PowerShell 的 `> $null` 重定向仍可工作，且不会打开 NUL。

package/lib/index.js

@@ -0,0 +1,241 @@
+import { SandboxUnavailableError } from "@hasna-internal/kai-sandbox";
+import { PwshLocalExecutor } from "@hasna-internal/kai-pwsh-local";
+import { accessSync, constants, statSync } from "node:fs";
+//#region lib/types/helpers.js
+/**
+* Internal sandbox-result classification helpers — deliberate call-for-call
+* mirror of `@hasna-internal/kai-bash-sandbox/src/helpers.ts` (the pwsh twin of
+* the bash consumer shares the identical classification dialect).
+*
+* @module @hasna-internal/kai-pwsh-sandbox/helpers
+*/
+/** Node-local spawn codes proven to identify executable resolution or permission failure. */
+const EXECUTABLE_SPAWN_CODES = new Set(["EACCES", "ENOENT"]);
+/** Whether the caller-owned spawn cwd can be entered. */
+function isUsableWorkdir(path) {
+	try {
+		if (!statSync(path).isDirectory()) return false;
+		accessSync(path, constants.X_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Attribute only Node ENOENT/EACCES failures with positive argv[0] provenance
+* after independently ruling out the caller-owned cwd. A supplied error path
+* must exactly identify the runner; without one, the syscall must. With a
+* usable cwd, these codes describe resolution or execute permission for that
+* argv[0] or its shebang interpreter.
+* The workdir is checked at classification time, not atomically with spawn;
+* concurrent path replacement may change attribution but cannot permit an
+* unconfined execution.
+* @param error - the original spawn rejection.
+* @param runnerProgram - provider argv[0], the executable that establishes confinement.
+* @param workdir - the caller-owned spawn cwd, checked independently for usability.
+* @returns whether the rejection has executable-specific runner evidence.
+*/
+function isRunnerSpawnFailure(error, runnerProgram, workdir) {
+	if (runnerProgram === void 0 || !isUsableWorkdir(workdir)) return false;
+	if (typeof error !== "object" || error === null) return false;
+	const { code, path, syscall } = error;
+	if (typeof code !== "string" || !EXECUTABLE_SPAWN_CODES.has(code)) return false;
+	if (typeof syscall !== "string") return false;
+	const exactSyscall = `spawn ${runnerProgram}`;
+	if (path === void 0) return syscall === exactSyscall;
+	if (typeof path !== "string" || path.length === 0 || path !== runnerProgram) return false;
+	return syscall === "spawn" || syscall === exactSyscall;
+}
+/**
+* Classify a failed run against the selected backend's denial dialect.
+* @param result - settled foreground run.
+* @param signatures - case-insensitive denial substrings from the active wrap.
+* @returns whether the failed run matches that denial dialect.
+*/
+function classifyDenial(result, signatures) {
+	return matchesSignature(result.exitCode, result.stderr.text, signatures);
+}
+/**
+* Classify one settled process against the selected backend's structured
+* runner-failure rules. Each rule requires a nonzero exit, its optional
+* exit-code gate, and a fatal signature on one stderr line after exact
+* informational lines are excluded.
+* @param exitCode - process exit code; null means signal termination.
+* @param stderr - collected stderr text, left unchanged.
+* @param rules - structured runner-failure rules from the active wrap.
+* @returns the first matching fatal line, or undefined when evidence is insufficient.
+*/
+function classifyRunnerFailure(exitCode, stderr, rules) {
+	if (exitCode === null || exitCode === 0) return void 0;
+	const lines = stderr.split(/\r?\n/);
+	for (const rule of rules) {
+		if (rule.allowedExitCodes !== void 0 && !rule.allowedExitCodes.includes(exitCode)) continue;
+		const informationalLines = new Set((rule.informationalLines ?? []).map((line) => line.toLowerCase()));
+		const fatalSignatures = rule.fatalSignatures.filter((signature) => signature.trim().length > 0).map((signature) => signature.toLowerCase());
+		for (const line of lines) {
+			const lowered = line.toLowerCase();
+			if (informationalLines.has(lowered)) continue;
+			if (fatalSignatures.some((signature) => lowered.includes(signature))) return { detail: line };
+		}
+	}
+}
+/**
+* Match a non-zero exit against case-insensitive stderr signatures.
+* @param exitCode - process exit code; null means signal termination.
+* @param stderr - collected stderr text.
+* @param signatures - substrings identifying the selected backend's dialect.
+* @returns whether this is a non-zero exit whose stderr matches a signature.
+*/
+function matchesSignature(exitCode, stderr, signatures) {
+	if (exitCode === null || exitCode === 0) return false;
+	const lowered = stderr.toLowerCase();
+	return signatures.some((signature) => lowered.includes(signature.toLowerCase()));
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* Sandbox-consuming PowerShell executor — the pwsh twin of
+* `@hasna-internal/kai-bash-sandbox`. It wraps the exact local pwsh argv through
+* `ctx.sandbox` (which on Windows resolves to the ACL restricted-token runner
+* chain), inherits local process mechanics, and reports the selected mode,
+* enforcement, and denial facts. Positive runner-launch evidence means the
+* command never ran: foreground calls throw `SANDBOX_UNAVAILABLE`, while
+* background processes carry `runnerFailed`; other spawn rejections retain
+* local-executor semantics. The tool layer owns the escalation approval flow
+* through `ctx.approval`; this executor reports the sandbox facts the tool
+* renders.
+* @module @hasna-internal/kai-pwsh-sandbox
+*/
+/**
+* Registers as `ctx.shell` in place of the local pwsh executor and requires a
+* `ctx.sandbox` provider plus `ctx.sandboxPolicy`; the tool layer carries the
+* sandbox denial rendering and escalation surface (see the
+* pwsh-tool-and-executor Agent Note). Tool calls pass the calling session's
+* resolved policy; direct calls fall back to deployment policy.
+* `result.sandbox` reports the mode, enforcement, and denial facts the tool
+* renders.
+*/
+var SandboxPwshExecutor = class extends PwshLocalExecutor {
+	static inject = [
+		"subprocess",
+		"sandbox",
+		"sandboxPolicy"
+	];
+	mode;
+	/**
+	* Per-process confinement facts retained until settlement. Providers may
+	* vary enforcement and diagnostic dialect between overlapping calls, so a
+	* shared latest-wrap value would classify a process against the wrong facts.
+	* Unconfined processes have no entry.
+	*/
+	processFacts = /* @__PURE__ */ new Map();
+	constructor(ctx, config) {
+		super(ctx, config);
+		this.mode = ctx.sandboxPolicy.defaultMode;
+	}
+	/** The configured default mode — the capability fact the tool layer reads. */
+	get sandboxMode() {
+		return this.mode;
+	}
+	/**
+	* Stamp a complete per-call policy onto the spec. Tool calls supply the
+	* calling session's resolved mode and root; lower-level callers fall back to
+	* the deployment policy.
+	*/
+	resolve(request) {
+		return {
+			...super.resolve(request),
+			sandboxPolicy: request.sandboxPolicy ?? this.ctx.sandboxPolicy.resolve()
+		};
+	}
+	async run(spec) {
+		const policy = spec.sandboxPolicy;
+		const { mode } = policy;
+		if (mode === "danger-full-access") return {
+			...await super.run(spec),
+			sandbox: {
+				mode,
+				denied: false
+			}
+		};
+		const confined = this.confine(spec, {
+			...policy,
+			mode
+		});
+		let result;
+		try {
+			result = await this.runArgv(spec, confined.argv);
+		} catch (error) {
+			if (spec.signal?.aborted === true) spec.signal.throwIfAborted();
+			if (isRunnerSpawnFailure(error, confined.argv[0], spec.workdir)) throw new SandboxUnavailableError(mode, String(error));
+			throw error;
+		}
+		const runnerFailure = classifyRunnerFailure(result.exitCode, result.stderr.text, confined.runnerFailureRules);
+		if (runnerFailure !== void 0) throw new SandboxUnavailableError(mode, runnerFailure.detail);
+		return {
+			...result,
+			sandbox: {
+				mode,
+				denied: classifyDenial(result, confined.denialSignatures),
+				enforcement: confined.enforcement
+			}
+		};
+	}
+	start(spec) {
+		const policy = spec.sandboxPolicy;
+		const { mode } = policy;
+		if (mode === "danger-full-access") return super.start(spec);
+		const confined = this.confine(spec, {
+			...policy,
+			mode
+		});
+		let proc;
+		try {
+			proc = this.startArgv(spec, confined.argv);
+		} catch (error) {
+			if (isRunnerSpawnFailure(error, confined.argv[0], spec.workdir)) throw new SandboxUnavailableError(mode, String(error));
+			throw error;
+		}
+		const { enforcement, denialSignatures, runnerFailureRules } = confined;
+		this.processFacts.set(proc, {
+			mode,
+			enforcement,
+			denialSignatures,
+			runnerFailureRules,
+			runnerProgram: confined.argv[0],
+			workdir: spec.workdir
+		});
+		return proc;
+	}
+	/**
+	* Stamp per-process sandbox facts before `done` settles. Full-access
+	* processes have no facts; signal deaths are not denials.
+	*/
+	onProcessDone(proc, stderr, spawnFailed, spawnError) {
+		const facts = this.processFacts.get(proc);
+		if (facts !== void 0) {
+			this.processFacts.delete(proc);
+			const runnerFailed = spawnFailed ? isRunnerSpawnFailure(spawnError, facts.runnerProgram, facts.workdir) : classifyRunnerFailure(proc.exitCode, stderr, facts.runnerFailureRules) !== void 0;
+			proc.sandbox = {
+				mode: facts.mode,
+				denied: !runnerFailed && matchesSignature(proc.exitCode, stderr, facts.denialSignatures),
+				enforcement: facts.enforcement,
+				...runnerFailed ? { runnerFailed } : {}
+			};
+		}
+		super.onProcessDone(proc, stderr, spawnFailed, spawnError);
+	}
+	/**
+	* Wrap one pwsh invocation via the `ctx.sandbox` provider. Provider errors
+	* propagate unchanged; the returned argv is handed directly to the local
+	* executor's subprocess path.
+	* @param spec - resolved execution spec whose pwsh argv is confined.
+	* @param policy - resolved confined execution policy.
+	* @returns the provider's exact argv and settlement-classification facts.
+	*/
+	confine(spec, policy) {
+		return this.ctx.sandbox.confine(this.argv(spec), policy);
+	}
+};
+//#endregion
+export { SandboxPwshExecutor, SandboxPwshExecutor as default };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@hasna-internal/kai-pwsh-sandbox`.
+* @module @hasna-internal/kai-pwsh-sandbox/invariant
+*/
+const PACKAGE_NAME = "@hasna-internal/kai-pwsh-sandbox";
+/** Cordis companion plugin name. */
+const name = "pwsh-sandbox-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: this package exposes no independent event sequence or
+* mutable data relation beyond contracts enforced at its owning seams.
+*/
+const install = () => {};
+/**
+* Register this package's 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/helpers.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Internal sandbox-result classification helpers — deliberate call-for-call
+ * mirror of `@hasna-internal/kai-bash-sandbox/src/helpers.ts` (the pwsh twin of
+ * the bash consumer shares the identical classification dialect).
+ *
+ * @module @hasna-internal/kai-pwsh-sandbox/helpers
+ */
+import type { ShellRunResult } from '@hasna-internal/kai-shell';
+import type { RunnerFailureRule } from '@hasna-internal/kai-sandbox';
+/**
+ * Attribute only Node ENOENT/EACCES failures with positive argv[0] provenance
+ * after independently ruling out the caller-owned cwd. A supplied error path
+ * must exactly identify the runner; without one, the syscall must. With a
+ * usable cwd, these codes describe resolution or execute permission for that
+ * argv[0] or its shebang interpreter.
+ * The workdir is checked at classification time, not atomically with spawn;
+ * concurrent path replacement may change attribution but cannot permit an
+ * unconfined execution.
+ * @param error - the original spawn rejection.
+ * @param runnerProgram - provider argv[0], the executable that establishes confinement.
+ * @param workdir - the caller-owned spawn cwd, checked independently for usability.
+ * @returns whether the rejection has executable-specific runner evidence.
+ */
+export declare function isRunnerSpawnFailure(error: unknown, runnerProgram: string | undefined, workdir: string): boolean;
+/** Fatal runner evidence retained for infrastructure-error detail. */
+interface RunnerFailureMatch {
+    /** The original stderr line that matched a fatal signature. */
+    detail: string;
+}
+/**
+ * Classify a failed run against the selected backend's denial dialect.
+ * @param result - settled foreground run.
+ * @param signatures - case-insensitive denial substrings from the active wrap.
+ * @returns whether the failed run matches that denial dialect.
+ */
+export declare function classifyDenial(result: ShellRunResult, signatures: readonly string[]): boolean;
+/**
+ * Classify one settled process against the selected backend's structured
+ * runner-failure rules. Each rule requires a nonzero exit, its optional
+ * exit-code gate, and a fatal signature on one stderr line after exact
+ * informational lines are excluded.
+ * @param exitCode - process exit code; null means signal termination.
+ * @param stderr - collected stderr text, left unchanged.
+ * @param rules - structured runner-failure rules from the active wrap.
+ * @returns the first matching fatal line, or undefined when evidence is insufficient.
+ */
+export declare function classifyRunnerFailure(exitCode: number | null, stderr: string, rules: readonly RunnerFailureRule[]): RunnerFailureMatch | undefined;
+/**
+ * Match a non-zero exit against case-insensitive stderr signatures.
+ * @param exitCode - process exit code; null means signal termination.
+ * @param stderr - collected stderr text.
+ * @param signatures - substrings identifying the selected backend's dialect.
+ * @returns whether this is a non-zero exit whose stderr matches a signature.
+ */
+export declare function matchesSignature(exitCode: number | null, stderr: string, signatures: readonly string[]): boolean;
+export {};
+//# sourceMappingURL=helpers.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Sandbox-consuming PowerShell executor — the pwsh twin of
+ * `@hasna-internal/kai-bash-sandbox`. It wraps the exact local pwsh argv through
+ * `ctx.sandbox` (which on Windows resolves to the ACL restricted-token runner
+ * chain), inherits local process mechanics, and reports the selected mode,
+ * enforcement, and denial facts. Positive runner-launch evidence means the
+ * command never ran: foreground calls throw `SANDBOX_UNAVAILABLE`, while
+ * background processes carry `runnerFailed`; other spawn rejections retain
+ * local-executor semantics. The tool layer owns the escalation approval flow
+ * through `ctx.approval`; this executor reports the sandbox facts the tool
+ * renders.
+ * @module @hasna-internal/kai-pwsh-sandbox
+ */
+import { Context } from '@deepseek-ai/cordis';
+import type { ShellExecRequest, ShellExecSpec, ShellProcess, ShellRunResult } from '@hasna-internal/kai-shell';
+import type { SandboxMode } from '@hasna-internal/kai-sandbox';
+import { PwshLocalExecutor } from '@hasna-internal/kai-pwsh-local';
+import type { Config as LocalConfig } from '@hasna-internal/kai-pwsh-local';
+/**
+ * Plugin config: the local executor's knobs, verbatim. The sandbox policy —
+ * the default mode and fallback `workspace-write` root — is NOT here: it lives
+ * on `ctx.sandboxPolicy` (`@hasna-internal/kai-sandbox-policy`), which resolves
+ * each calling session's mode and cwd for every enforcing capability. The
+ * runner choice is likewise the `ctx.sandbox` provider's config, not this
+ * executor's.
+ */
+export type Config = LocalConfig;
+/**
+ * Registers as `ctx.shell` in place of the local pwsh executor and requires a
+ * `ctx.sandbox` provider plus `ctx.sandboxPolicy`; the tool layer carries the
+ * sandbox denial rendering and escalation surface (see the
+ * pwsh-tool-and-executor Agent Note). Tool calls pass the calling session's
+ * resolved policy; direct calls fall back to deployment policy.
+ * `result.sandbox` reports the mode, enforcement, and denial facts the tool
+ * renders.
+ */
+export declare class SandboxPwshExecutor extends PwshLocalExecutor {
+    static inject: string[];
+    private readonly mode;
+    /**
+     * Per-process confinement facts retained until settlement. Providers may
+     * vary enforcement and diagnostic dialect between overlapping calls, so a
+     * shared latest-wrap value would classify a process against the wrong facts.
+     * Unconfined processes have no entry.
+     */
+    private readonly processFacts;
+    constructor(ctx: Context, config: Config);
+    /** The configured default mode — the capability fact the tool layer reads. */
+    get sandboxMode(): SandboxMode;
+    /**
+     * Stamp a complete per-call policy onto the spec. Tool calls supply the
+     * calling session's resolved mode and root; lower-level callers fall back to
+     * the deployment policy.
+     */
+    resolve(request: ShellExecRequest): ShellExecSpec;
+    run(spec: ShellExecSpec): Promise<ShellRunResult>;
+    start(spec: ShellExecSpec): ShellProcess;
+    /**
+     * Stamp per-process sandbox facts before `done` settles. Full-access
+     * processes have no facts; signal deaths are not denials.
+     */
+    protected onProcessDone(proc: ShellProcess, stderr: string, spawnFailed: boolean, spawnError?: unknown): void;
+    /**
+     * Wrap one pwsh invocation via the `ctx.sandbox` provider. Provider errors
+     * propagate unchanged; the returned argv is handed directly to the local
+     * executor's subprocess path.
+     * @param spec - resolved execution spec whose pwsh argv is confined.
+     * @param policy - resolved confined execution policy.
+     * @returns the provider's exact argv and settlement-classification facts.
+     */
+    private confine;
+}
+export default SandboxPwshExecutor;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@hasna-internal/kai-pwsh-sandbox`.
+ * @module @hasna-internal/kai-pwsh-sandbox/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "pwsh-sandbox-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's 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/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@hasna-internal/kai-pwsh-sandbox",
+  "description": "Sandbox-consuming implementation of the DeepSeek Harness PowerShell executor seam (confines every command via ctx.sandbox, reports denial/enforcement result facts)",
+  "version": "0.1.1-rc.2",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/shell/pwsh-sandbox"
+  },
+  "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": {
+    "@hasna-internal/kai-invariants": "^0.1.1-rc.2",
+    "@hasna-internal/kai-shell": "^0.1.1-rc.2",
+    "@hasna-internal/kai-sandbox": "^0.1.1-rc.2",
+    "@hasna-internal/kai-pwsh-local": "^0.1.1-rc.2",
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@hasna-internal/kai-sandbox-policy": "^0.1.1-rc.2"
+  },
+  "devDependencies": {
+    "@hasna-internal/kai-sandbox-local": "^0.1.1-rc.2",
+    "@hasna-internal/kai-sandbox": "^0.1.1-rc.2",
+    "@hasna-internal/kai-pwsh-local": "^0.1.1-rc.2",
+    "@hasna-internal/kai-sandbox-policy": "^0.1.1-rc.2",
+    "@hasna-internal/kai-invariants": "^0.1.1-rc.2",
+    "@hasna-internal/kai-shell": "^0.1.1-rc.2",
+    "@hasna-internal/kai-subprocess-local": "^0.1.1-rc.2",
+    "@deepseek-ai/cordis": "^4.0.1"
+  }
+}