dsh-perm-gate 5.0.4 → 5.1.0

package/dsh.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "dsh-perm-gate",
   "name": "dsh-perm-gate",
-  "version": "5.0.2",
+  "version": "5.1.0",
   "description": {
     "en": "Deterministic-first, fail-closed permission gate for DeepSeek Harness 0.1.2+: a P0 hard-deny -> P1 precise session grant -> P2 static allow/deny rule chain -> P3 optional LLM classifier -> P4 ask pipeline over the tools/pre-execute waterfall, with a standalone CLI dry-run evaluator and an auditable decision log. It only vetoes with deny/ask and always delegates otherwise, and unknown or malformed rules fail loud instead of silently standing the gate down.",
     "zh": "面向 DeepSeek Harness 0.1.2+ 的确定性优先、失败即拒的权限闸门：在 tools/pre-execute 瀑布上串起 P0 硬拒绝 → P1 精确会话授权 → P2 静态 allow/deny 规则链 → P3 可选 LLM 语义分类 → P4 ask，并附带独立 CLI 干跑评估器与可审计的决策日志。只以 deny/ask 否决、其余一律放行，规则未知或非法时直接报错，绝不静默失效。"
@@ -13,7 +13,7 @@
   },
   "license": "MIT",
   "engines": {
-    "dsh": ">=0.2.0-rc.1 <0.2.1-0"
+    "dsh": "0.1.0-rc.2 || 0.1.0-rc.3 || 0.1.0-rc.6 || 0.1.0-rc.7 || 0.1.0-rc.8 || 0.1.1-rc.1 || 0.1.1-rc.2 || 0.1.2-rc.1 || 0.1.5-rc.1 || 0.1.5-rc.2 || 0.1.5-rc.3 || 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1 || 0.2.0-rc.2"
   },
   "components": {
     "host": "lib/index.js",

package/lib/appcontainer/compile.d.ts

@@ -0,0 +1,17 @@
+/** The shipped C# launcher source (read-only asset). */
+export declare const LAUNCHER_SOURCE: string;
+/** Compile-cache root (also swept by the controller's housekeeping). */
+export declare const CACHE_DIR: string;
+/** Locate the .NET Framework C# compiler, or undefined when absent. */
+export declare function locateCsc(): string | undefined;
+export interface CompiledLauncher {
+    readonly exePath: string;
+    readonly hash: string;
+    readonly cached: boolean;
+}
+/**
+ * Compile (or reuse) the launcher for the current source hash. Returns the exe
+ * path; undefined means the platform cannot provide one (no csc) — callers
+ * must treat sandbox mode as unavailable (fail-closed), never run unwrapped.
+ */
+export declare function ensureLauncher(): Promise<CompiledLauncher | undefined>;

package/lib/appcontainer/compile.js

@@ -0,0 +1,74 @@
+/**
+ * compile.ts —— launcher.exe 的按需编译（csc.exe，.NET Framework 自带）。
+ *
+ * 产物按 launcher.cs 的 sha256 缓存在 `os.tmpdir()/dsh-perm-gate-ac/`——
+ * 源码不变则编译一次终身复用；换版本自动重编。C# 源码随包发布
+ * （`assets/appcontainer-launcher.cs`），插件本体零原生依赖。
+ *
+ * csc 定位：`%WINDIR%\Microsoft.NET\Framework64\v4.0.30319\csc.exe`（Win10/
+ * 11/24H2 全系自带 .NET Framework 4.x），缺失时回退 Framework（32 位）。
+ * 找不到 csc → 返回 undefined，上层按 fail-closed 处理（沙盒开启时该调用
+ * 硬拒绝，绝不回退到容器外执行）。
+ */
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** The shipped C# launcher source (read-only asset). */
+export const LAUNCHER_SOURCE = fileURLToPath(new URL('../../assets/appcontainer-launcher.cs', import.meta.url));
+/** Compile-cache root (also swept by the controller's housekeeping). */
+export const CACHE_DIR = path.join(os.tmpdir(), 'dsh-perm-gate-ac');
+function cscCandidates() {
+    const windir = process.env['WINDIR'] ?? 'C:\\Windows';
+    return [
+        path.join(windir, 'Microsoft.NET', 'Framework64', 'v4.0.30319', 'csc.exe'),
+        path.join(windir, 'Microsoft.NET', 'Framework', 'v4.0.30319', 'csc.exe'),
+    ];
+}
+/** Locate the .NET Framework C# compiler, or undefined when absent. */
+export function locateCsc() {
+    for (const candidate of cscCandidates()) {
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+async function run(cwd, exe, args) {
+    return new Promise((resolve, reject) => {
+        execFile(exe, args, { cwd, windowsHide: true, timeout: 120_000 }, (error, _stdout, stderr) => {
+            if (error !== undefined && error !== null) {
+                reject(new Error(`csc failed: ${String(stderr ?? error.message).slice(-400)}`));
+            }
+            else
+                resolve();
+        });
+    });
+}
+/**
+ * Compile (or reuse) the launcher for the current source hash. Returns the exe
+ * path; undefined means the platform cannot provide one (no csc) — callers
+ * must treat sandbox mode as unavailable (fail-closed), never run unwrapped.
+ */
+export async function ensureLauncher() {
+    const csc = locateCsc();
+    if (csc === undefined)
+        return undefined;
+    const source = await readFile(LAUNCHER_SOURCE, 'utf8');
+    const hash = createHash('sha256').update(source, 'utf8').digest('hex').slice(0, 16);
+    const exePath = path.join(CACHE_DIR, `appcontainer-launcher-${hash}.exe`);
+    const marker = `${exePath}.ok`;
+    if (existsSync(exePath) && existsSync(marker))
+        return { exePath, hash, cached: true };
+    await mkdir(CACHE_DIR, { recursive: true });
+    await run(CACHE_DIR, csc, [
+        '/nologo', '/target:exe', '/optimize+',
+        '/r:System.Web.Extensions.dll',
+        `/out:${exePath}`,
+        LAUNCHER_SOURCE,
+    ]);
+    await writeFile(marker, String(process.pid), 'utf8');
+    return { exePath, hash, cached: false };
+}

package/lib/appcontainer/exempt.d.ts

@@ -0,0 +1,18 @@
+export type LoopbackExemptResult = {
+    readonly status: 'exempt' | 'already-exempt';
+} | {
+    readonly status: 'failed';
+    readonly message: string;
+} | {
+    readonly status: 'unsupported';
+    readonly message: string;
+};
+/**
+ * Ensure the container SID is on the machine's loopback-exempt list.
+ *
+ * `elevate` (default false): when true and the non-elevated add is denied, one
+ * UAC elevation prompt is offered via PowerShell Start-Process -Verb RunAs.
+ */
+export declare function ensureLoopbackExempt(sid: string, options?: {
+    elevate?: boolean;
+}): Promise<LoopbackExemptResult>;

package/lib/appcontainer/exempt.js

@@ -0,0 +1,71 @@
+/**
+ * exempt.ts —— AppContainer 回环豁免（CheckNetIsolation LoopbackExempt）。
+ *
+ * 背景：AppContainer 进程默认连 127.0.0.1 都不可达（WFP 回环隔离）。豁免以
+ * 容器 SID 为键，与本插件的**稳定派生 SID**（sid.ts）配合——全机只需做一次，
+ * 之后每个会话直接复用。豁免写入 HKLM 防火墙策略区，非提权进程可能被拒；
+ * 被拒不致命（沙盒内进程只是够不到 127.0.0.1 的代理/宿主服务），但要把
+ * 手工提权命令原样告诉用户。
+ *
+ * 幂等：`-s` 子命令列出已豁免 SID，命中即跳过；避免每次会话都打一次
+ * CheckNetIsolation（它也不便宜）。
+ */
+import { execFile } from 'node:child_process';
+function checkNetIsolationPath() {
+    const windir = process.env['WINDIR'] ?? 'C:\\Windows';
+    return `${windir}\\System32\\CheckNetIsolation.exe`;
+}
+function run(exe, args, timeoutMs = 30_000) {
+    return new Promise((resolve) => {
+        execFile(exe, args, { windowsHide: true, timeout: timeoutMs }, (error, stdout, stderr) => {
+            const code = error === undefined || error === null ? 0 : error.code ?? 1;
+            resolve({ code, stdout: String(stdout ?? ''), stderr: String(stderr ?? '') });
+        });
+    });
+}
+/**
+ * Ensure the container SID is on the machine's loopback-exempt list.
+ *
+ * `elevate` (default false): when true and the non-elevated add is denied, one
+ * UAC elevation prompt is offered via PowerShell Start-Process -Verb RunAs.
+ */
+export async function ensureLoopbackExempt(sid, options = {}) {
+    if (process.platform !== 'win32') {
+        return { status: 'unsupported', message: 'loopback exemption is Windows-only (AppContainer)' };
+    }
+    const exe = checkNetIsolationPath();
+    const list = await run(exe, ['LoopbackExempt', '-s']);
+    if (list.code !== 0 && list.stdout === '' && list.stderr !== '') {
+        return { status: 'failed', message: `CheckNetIsolation -s failed: ${list.stderr.trim().slice(0, 200)}` };
+    }
+    if (list.stdout.includes(sid))
+        return { status: 'already-exempt' };
+    const add = await run(exe, ['LoopbackExempt', '-a', `-p=${sid}`]);
+    if (add.code === 0)
+        return { status: 'exempt' };
+    const denied = /denied|administrator|elevation/i.test(`${add.stderr}${add.stdout}`);
+    if (denied && options.elevate === true) {
+        const elevated = await elevate(exe, sid);
+        if (elevated !== undefined)
+            return elevated;
+    }
+    return {
+        status: 'failed',
+        message: `loopback exemption needs elevation (win32 exit ${add.code}). Run once from an elevated prompt:\n`
+            + `  ${exe} LoopbackExempt -a -p=${sid}\n`
+            + `The SID is stable per machine, so this is a one-time step.`,
+    };
+}
+async function elevate(exe, sid) {
+    const command = `${exe} LoopbackExempt -a -p=${sid}`;
+    return new Promise((resolve) => {
+        execFile('powershell.exe', ['-NoProfile', '-Command', `Start-Process -Verb RunAs -Wait -WindowStyle Hidden '${command}'`], { windowsHide: true, timeout: 120_000 }, (error) => {
+            if (error === undefined || error === null) {
+                resolve({ status: 'exempt' });
+            }
+            else {
+                resolve(undefined); // caller falls back to the manual-guidance message
+            }
+        });
+    });
+}

package/lib/appcontainer/index.d.ts

@@ -0,0 +1,85 @@
+/** Sandbox-relevant settings, resolved from the volatile config each read. */
+export interface SandboxSettings {
+    readonly enabled: boolean;
+    readonly mode: 'read-only' | 'workspace-write';
+    /** '' = follow the builtin filtered proxy; otherwise an explicit loopback URL. */
+    readonly proxy: string;
+    readonly loopback: 'exempt' | 'off';
+}
+/** What the gate should do with an allowed shell call. */
+export type SandboxRewriteResult = {
+    readonly kind: 'wrap';
+    readonly command: string;
+} | {
+    readonly kind: 'deny';
+    readonly reason: string;
+};
+/** The call face the controller needs (subset of ToolExecutionLike). */
+export interface SandboxCall {
+    readonly name: string;
+    readonly arguments: Record<string, unknown>;
+    readonly cwd?: string;
+}
+export interface SandboxControllerDeps {
+    /** Default workspace when the call carries no cwd (the host process cwd). */
+    readonly cwdRoot: () => string;
+    /** The builtin filtered proxy's actually-bound port, when it is up. */
+    readonly builtinProxyPort: () => number | undefined;
+    readonly log: (message: string) => void;
+    readonly platform?: () => NodeJS.Platform;
+    readonly now?: () => number;
+}
+/**
+ * Workspace roots that must never receive container ACEs: granting the whole
+ * user profile / a drive root / the OS directory turns "workspace-write" into
+ * a machine-wide write grant (R3). Returns the denial reason or undefined.
+ */
+export declare function isForbiddenWorkspace(workspace: string, home?: string, winDir?: string): string | undefined;
+export declare class SandboxController {
+    private readonly deps;
+    private launcherPromise;
+    private probe;
+    private tempRoot;
+    private configRoot;
+    private exemptSettled;
+    private exemptLastAttempt;
+    private sid;
+    private swept;
+    constructor(deps: SandboxControllerDeps);
+    private get platform();
+    private get now();
+    /** Comparison key for change detection (settings-edit → re-ensure). */
+    static keyOf(settings: SandboxSettings, sid: string): string;
+    /**
+     * Compile the launcher once per source hash, ask it for the OS-derived
+     * container SID, and run the one-shot `--probe` verdict. Failures are NOT
+     * cached (a missing csc may appear after a .NET install — retry next call);
+     * the loopback exemption settles only on success (a failure retries with
+     * backoff — a transient denial must not disable loopback for the process
+     * lifetime).
+     */
+    ensure(settings: SandboxSettings): Promise<{
+        exePath: string;
+        hash: string;
+    } | undefined>;
+    /** The proxy URL injected into sandboxed processes, if any. */
+    resolveProxyUrl(settings: SandboxSettings): string | undefined;
+    /**
+     * Gate-aware rewrite of one allowed shell call: undefined (not applicable —
+     * disabled / not a shell tool / non-Windows), wrap (the rewritten command),
+     * or deny (fail-closed when the sandbox is on but cannot be honored).
+     */
+    wrap(settings: SandboxSettings, exec: SandboxCall): Promise<SandboxRewriteResult | undefined>;
+    /** One standing scratch dir per plugin process, removed on dispose. */
+    private ensureTempDir;
+    /** Private config dir — NOT container-writable (R5). */
+    private ensureConfigDir;
+    /** Best-effort scratch cleanup at plugin dispose. */
+    dispose(): Promise<void>;
+    /**
+     * One-shot housekeeping: orphan scratch dirs (crashed processes leak them —
+     * 6 found on this machine) older than 24h, and stale compile-cache exes
+     * older than 7 days. Best effort, once per process.
+     */
+    private sweep;
+}

package/lib/appcontainer/index.js

@@ -0,0 +1,286 @@
+/**
+ * appcontainer/index.ts —— 沙盒控制器：把门控放行的 shell 调用重写进
+ * Windows AppContainer（目标 2 的编排层）。
+ *
+ * 出网模型（设计定案，见 README「AppContainer 沙盒」一节）：
+ *   - 属性列表启动 **零能力** → 非回环出网被 WFP 物理封死（不是环境变量那种
+ *     可绕过的软约束）；
+ *   - 容器 SID 由 OS 派生（launcher `--print-sid`），回环豁免做一次终身有效
+ *     （exempt.ts，失败带退避重试——只缓存成功）；
+ *   - 代理来自配置参数 `sandboxProxy`：空 = 跟随本插件的内置过滤代理
+ *     （NetworkLifecycle 实际绑定的 127.0.0.1:<port>）；显式 URL 逐字注入
+ *     （必须是回环地址——容器只可达回环）。注入时**同时置空 NO_PROXY**，
+ *     否则继承的 NO_PROXY 会让容器绕开过滤代理直连回环（R4）。
+ *
+ * fail-closed：沙盒开启但启动器不可用 / 命令文本缺失 / 工作区越禁 / POSIX
+ * 方言工具 → 返回 deny 而不是放行裸执行——这是权限闸门，不是便利贴。
+ */
+import { execFile } from 'node:child_process';
+import { readdir, mkdtemp, rm, stat } from 'node:fs/promises';
+import { homedir, tmpdir } from 'node:os';
+import path from 'node:path';
+import { SHELL_TOOLS } from '../evaluate.js';
+import { NO_PROXY_ENV_NAMES, PROXY_ENV_NAMES } from '../proxy.js';
+import { ensureLauncher, locateCsc } from './compile.js';
+import { ensureLoopbackExempt } from './exempt.js';
+import { runProbe } from './probe.js';
+import { buildWrappedCommand, writeLaunchConfig } from './wrap.js';
+/** Tools whose command text is POSIX shell dialect — cmd.exe cannot honor it. */
+const POSIX_DIALECT_TOOLS = new Set(['bash', 'sh']);
+/** Retry cadence for a FAILED loopback exemption (successes settle permanently). */
+const EXEMPT_RETRY_MS = 60_000;
+/**
+ * Workspace roots that must never receive container ACEs: granting the whole
+ * user profile / a drive root / the OS directory turns "workspace-write" into
+ * a machine-wide write grant (R3). Returns the denial reason or undefined.
+ */
+export function isForbiddenWorkspace(workspace, home = homedir(), winDir = process.env['WINDIR'] ?? 'C:\\Windows') {
+    const norm = (p) => path.resolve(p).replace(/[\\/]+$/, '').toLowerCase();
+    const target = norm(workspace);
+    if (path.parse(target).root === target && target.endsWith(':'))
+        return 'workspace is a drive root';
+    if (target === norm(home))
+        return 'workspace is the user home directory (would grant a whole-home ACE)';
+    if (target === norm(winDir))
+        return 'workspace is the Windows directory';
+    return undefined;
+}
+export class SandboxController {
+    deps;
+    launcherPromise;
+    probe;
+    tempRoot;
+    configRoot;
+    exemptSettled = false;
+    exemptLastAttempt = 0;
+    sid;
+    swept = false;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    get platform() {
+        return this.deps.platform ? this.deps.platform() : process.platform;
+    }
+    get now() {
+        return this.deps.now ? this.deps.now() : Date.now();
+    }
+    /** Comparison key for change detection (settings-edit → re-ensure). */
+    static keyOf(settings, sid) {
+        return JSON.stringify([sid, settings.enabled, settings.mode, settings.proxy, settings.loopback]);
+    }
+    /**
+     * Compile the launcher once per source hash, ask it for the OS-derived
+     * container SID, and run the one-shot `--probe` verdict. Failures are NOT
+     * cached (a missing csc may appear after a .NET install — retry next call);
+     * the loopback exemption settles only on success (a failure retries with
+     * backoff — a transient denial must not disable loopback for the process
+     * lifetime).
+     */
+    async ensure(settings) {
+        this.launcherPromise ??= ensureLauncher().then(async (compiled) => {
+            if (compiled === undefined) {
+                this.deps.log('[dsh-perm-gate] sandbox: csc.exe not found — install .NET Framework 4.x; sandboxed calls will be DENIED (fail-closed)');
+                return undefined;
+            }
+            // OS-derived container SID (opaque; both era shapes accepted).
+            this.sid = await launcherSid(compiled.exePath);
+            if (this.sid === undefined) {
+                this.deps.log('[dsh-perm-gate] sandbox: launcher --print-sid failed — sandboxed calls will be DENIED (fail-closed)');
+                return undefined;
+            }
+            // One-shot probe verdict (diagnostics/attribution ONLY — never a
+            // pass-through basis; per-launch resolution stays the trust anchor).
+            this.probe = await runProbe(compiled.exePath);
+            if (this.probe !== undefined) {
+                this.deps.log(`[dsh-perm-gate] sandbox probe: era=${this.probe.era} sidSubAuthorities=${this.probe.sidSubAuthorities} registered=${this.probe.registered.state} tryLaunch.win32Err=${this.probe.tryLaunch.win32Err}`);
+            }
+            // Fire-and-forget housekeeping (orphan scratch + stale compile cache).
+            void this.sweep().catch(() => undefined);
+            return { exePath: compiled.exePath, hash: compiled.hash };
+        }, (error) => {
+            this.launcherPromise = undefined; // transient compile failure: retry next call
+            this.deps.log(`[dsh-perm-gate] sandbox: launcher compile failed: ${String(error)}`);
+            return undefined;
+        });
+        const compiled = await this.launcherPromise;
+        if (compiled !== undefined && settings.loopback === 'exempt' && !this.exemptSettled && this.now - this.exemptLastAttempt >= EXEMPT_RETRY_MS) {
+            if (this.sid === undefined)
+                await this.launcherPromise;
+            if (this.sid !== undefined) {
+                this.exemptLastAttempt = this.now;
+                const result = await ensureLoopbackExempt(this.sid, { elevate: false });
+                // Only successes settle: a transient elevation denial must not
+                // disable loopback for the whole process lifetime (B finding).
+                if (result.status === 'exempt' || result.status === 'already-exempt' || result.status === 'unsupported') {
+                    this.exemptSettled = true;
+                    if (result.status === 'exempt')
+                        this.deps.log(`[dsh-perm-gate] sandbox: loopback exempted for ${this.sid}`);
+                }
+                else if (result.status === 'failed') {
+                    this.deps.log(`[dsh-perm-gate] sandbox: ${result.message}`);
+                }
+            }
+        }
+        return compiled;
+    }
+    /** The proxy URL injected into sandboxed processes, if any. */
+    resolveProxyUrl(settings) {
+        if (settings.proxy !== '') {
+            let parsed;
+            try {
+                parsed = new URL(settings.proxy);
+            }
+            catch {
+                parsed = undefined;
+            }
+            const loopback = parsed !== undefined
+                && (parsed.hostname === '127.0.0.1' || parsed.hostname === 'localhost' || parsed.hostname === '[::1]' || parsed.hostname === '::1');
+            if (!loopback) {
+                this.deps.log(`[dsh-perm-gate] sandbox: proxy "${settings.proxy}" is not loopback-bound — the container cannot reach it; ignored`);
+                return undefined;
+            }
+            return settings.proxy;
+        }
+        const port = this.deps.builtinProxyPort();
+        return port !== undefined && port > 0 ? `http://127.0.0.1:${port}` : undefined;
+    }
+    /**
+     * Gate-aware rewrite of one allowed shell call: undefined (not applicable —
+     * disabled / not a shell tool / non-Windows), wrap (the rewritten command),
+     * or deny (fail-closed when the sandbox is on but cannot be honored).
+     */
+    async wrap(settings, exec) {
+        if (!settings.enabled)
+            return undefined;
+        if (this.platform !== 'win32')
+            return undefined; // feature is Windows-only: silently off (apply() warns)
+        if (!SHELL_TOOLS.has(exec.name))
+            return undefined;
+        // POSIX-dialect tools cannot be honored by the container's cmd.exe —
+        // running them anyway would silently reinterpret the command (R9).
+        if (POSIX_DIALECT_TOOLS.has(exec.name)) {
+            return { kind: 'deny', reason: `sandbox: "${exec.name}" is a POSIX-dialect tool the AppContainer wrapper cannot honor (cmd.exe semantics) — run it via a Windows shell tool or disable sandboxEnabled` };
+        }
+        const raw = exec.arguments['command'];
+        if (typeof raw !== 'string' || raw.trim() === '') {
+            return { kind: 'deny', reason: 'sandbox: shell call carries no command text — refusing to run it unconfined' };
+        }
+        const workspace = exec.cwd !== undefined && exec.cwd !== '' ? exec.cwd : this.deps.cwdRoot();
+        const forbidden = isForbiddenWorkspace(workspace);
+        if (forbidden !== undefined) {
+            return { kind: 'deny', reason: `sandbox: ${forbidden} — refusing to grant container ACEs there` };
+        }
+        const launcher = await this.ensure(settings);
+        if (launcher === undefined) {
+            const hint = this.probe !== undefined ? ` (probe: ${this.probe.era})` : '';
+            return { kind: 'deny', reason: `sandbox: launcher unavailable (compile failed or csc missing)${hint} — failing closed` };
+        }
+        const proxyUrl = this.resolveProxyUrl(settings);
+        const proxyEnv = {};
+        if (proxyUrl !== undefined) {
+            for (const name of PROXY_ENV_NAMES)
+                proxyEnv[name] = proxyUrl;
+            // Clear inherited NO_PROXY: otherwise hosts with NO_PROXY=127.0.0.1,…
+            // bypass the filtering proxy straight to loopback services (R4).
+            for (const name of NO_PROXY_ENV_NAMES)
+                proxyEnv[name] = '';
+        }
+        const tempDir = await this.ensureTempDir();
+        // The launch config lives OUTSIDE the container-writable scratch dir: a
+        // resident container process must never be able to rewrite a future
+        // call's config into granting ACEs elsewhere (R5 TOCTOU).
+        const configDir = await this.ensureConfigDir();
+        const configPath = await writeLaunchConfig({
+            workspace,
+            tempDir,
+            mode: settings.mode,
+            proxyEnv,
+        }, configDir);
+        const wrapped = buildWrappedCommand(launcher.exePath, configPath, raw);
+        this.deps.log(`[dsh-perm-gate] sandbox(appcontainer): ${raw.split('\n')[0].slice(0, 120)}`);
+        return { kind: 'wrap', command: wrapped };
+    }
+    /** One standing scratch dir per plugin process, removed on dispose. */
+    async ensureTempDir() {
+        this.tempRoot ??= await mkdtemp(path.join(tmpdir(), 'dsh-perm-gate-ac-'));
+        return this.tempRoot;
+    }
+    /** Private config dir — NOT container-writable (R5). */
+    async ensureConfigDir() {
+        this.configRoot ??= await mkdtemp(path.join(tmpdir(), 'dsh-perm-gate-ac-cfg-'));
+        return this.configRoot;
+    }
+    /** Best-effort scratch cleanup at plugin dispose. */
+    async dispose() {
+        for (const dir of [this.tempRoot, this.configRoot]) {
+            if (dir !== undefined) {
+                await rm(dir, { recursive: true, force: true }).catch(() => undefined);
+            }
+        }
+        this.tempRoot = undefined;
+        this.configRoot = undefined;
+    }
+    /**
+     * One-shot housekeeping: orphan scratch dirs (crashed processes leak them —
+     * 6 found on this machine) older than 24h, and stale compile-cache exes
+     * older than 7 days. Best effort, once per process.
+     */
+    async sweep() {
+        if (this.swept)
+            return;
+        this.swept = true;
+        const dayMs = 24 * 60 * 60_000;
+        const now = this.now;
+        let entries = [];
+        try {
+            entries = await readdir(tmpdir());
+        }
+        catch {
+            return;
+        }
+        for (const name of entries) {
+            if (!name.startsWith('dsh-perm-gate-ac-'))
+                continue;
+            const full = path.join(tmpdir(), name);
+            try {
+                const info = await stat(full);
+                if (now - info.mtimeMs > dayMs)
+                    await rm(full, { recursive: true, force: true });
+            }
+            catch { /* racing with another process's sweep is fine */ }
+        }
+        // Compile cache: csc writes launcher-<hash>.exe (+ .ok); keep only recent
+        // artifacts — stale hashes are dead once the source moved on.
+        const csc = locateCsc();
+        if (csc === undefined)
+            return;
+        const { CACHE_DIR } = await import('./compile.js');
+        let cached = [];
+        try {
+            cached = await readdir(CACHE_DIR);
+        }
+        catch {
+            return;
+        }
+        for (const name of cached) {
+            if (!name.startsWith('appcontainer-launcher-'))
+                continue;
+            const full = path.join(CACHE_DIR, name);
+            try {
+                const info = await stat(full);
+                if (now - info.mtimeMs > 7 * dayMs)
+                    await rm(full, { force: true });
+            }
+            catch { /* ignore */ }
+        }
+    }
+}
+/** Ask the launcher for its OS-derived container SID (deterministic per name). */
+function launcherSid(exePath) {
+    return new Promise((resolve) => {
+        execFile(exePath, ['--print-sid'], { windowsHide: true, timeout: 30_000 }, (error, stdout) => {
+            const sid = String(stdout ?? '').trim();
+            resolve(error === undefined || error === null ? (sid !== '' ? sid : undefined) : undefined);
+        });
+    });
+}

package/lib/appcontainer/probe.d.ts

@@ -0,0 +1,44 @@
+export interface ProbeDerive {
+    readonly name: string;
+    readonly module: string;
+    readonly hr: number;
+}
+export type ProbeRegisteredState = 'yes' | 'no' | 'unknown' | 'n/a';
+/** The `--probe` verdict, exactly the launcher's single-line JSON. */
+export interface LauncherProbe {
+    readonly era: 'classic' | 'moniker' | 'none';
+    readonly derive: ProbeDerive;
+    readonly sid: string;
+    readonly sidSubAuthorities: number;
+    readonly registered: {
+        readonly state: ProbeRegisteredState;
+        readonly lookupHr: number;
+        readonly mappingMoniker: string | null;
+    };
+    readonly tryLaunch: {
+        readonly attempted: boolean;
+        readonly win32Err: number;
+        readonly childExit: number | null;
+    };
+    readonly osBuild: number;
+    readonly capabilities: Readonly<Record<string, boolean>>;
+    readonly mxc: {
+        readonly present: boolean;
+    };
+}
+/**
+ * Parse the probe's single-line stdout. Returns undefined for anything that
+ * is not a recognizable verdict (crash output, truncated line, foreign text) —
+ * the controller treats undefined as UNAVAILABLE-with-retry.
+ */
+export declare function parseProbeJson(text: string): LauncherProbe | undefined;
+/**
+ * The in-memory probe cache key. The launcher hash covers code changes, the
+ * OS build covers kernel-side behavior changes; context is deliberately NOT
+ * in the key because the cache never leaves the process (see header).
+ */
+export declare function probeCacheKey(launcherHash: string, probe: LauncherProbe): string;
+/** Run `launcher --probe` and parse its verdict. Undefined = launcher unusable. */
+export declare function runProbe(exePath: string, timeoutMs?: number): Promise<LauncherProbe | undefined>;
+/** Human-attributable one-liner for deny logs (which resolution level failed). */
+export declare function probeAttribution(probe: LauncherProbe): string;