@deepseek-ai/dsh-subprocess-local 0.1.5-rc.2 → 0.1.6-alpha.2

package/lib/types/linux-scope.d.ts

@@ -49,8 +49,18 @@ export declare function probeLinuxManager(internals?: LinuxScopeInternals): bool
 export declare function probeLinuxNative(internals?: LinuxScopeInternals): boolean;
 interface DirectRange {
     running(): boolean;
-    signal(signal: 'SIGTERM' | 'SIGKILL'): void;
+    /** True for group TERM delivery, direct signal submission, or proven direct-PID absence. */
+    signal(signal: 'SIGTERM' | 'SIGKILL'): boolean;
+    /** Direct exit/error settlement, independent of output drain and managed-range completion. */
+    settled: Promise<unknown>;
 }
+/**
+ * Send a direct-process signal, distinguishing an absent PID from failed delivery.
+ * @param pid - owned direct-process identity whose exit notification can still be pending.
+ * @param send - platform signal operation; true means the signal was submitted.
+ * @returns whether the signal was submitted or the owned PID is already absent.
+ */
+export declare function signalLinuxDirectProcess(pid: number, send: () => boolean): boolean;
 /** Linux PTY invocation and owner for the exact one-shot scope/bootstrap. */
 export interface LinuxTerminalScopeLaunch {
     command: string;
@@ -66,7 +76,7 @@ export interface LinuxTerminalScopeLaunch {
  * @param spec - terminal target request.
  * @param targetEnv - validated complete target environment.
  * @param internals - optional runner and systemd seams used by tests.
- * @returns invocation facts and ownership callbacks for node-pty.
+ * @returns invocation and ownership callbacks; requested termination preserves the observed signal even before bootstrap consumption.
  */
 export declare function prepareLinuxTerminalScope(spec: SubprocessTerminalSpawnSpec, targetEnv: Record<string, string>, internals?: LinuxScopeInternals): LinuxTerminalScopeLaunch;
 /**
@@ -74,7 +84,7 @@ export declare function prepareLinuxTerminalScope(spec: SubprocessTerminalSpawnS
  * @param spec - ordinary target request.
  * @param targetEnv - validated complete target environment.
  * @param internals - optional runner and systemd seams used by tests.
- * @returns direct streams, result, and managed-scope owner.
+ * @returns streams, result, and scope owner; requested termination preserves the observed signal even before bootstrap consumption.
  */
 export declare function launchLinuxScope(spec: SubprocessSpawnSpec, targetEnv: Record<string, string>, internals?: LinuxScopeInternals): ManagedProcessLaunch;
 export {};

package/lib/types/managed-owner.d.ts

@@ -1,5 +1,5 @@
 /** Minimal managed-range ownership bound to one ordinary subprocess handle. */
-import type { Readable, Writable } from 'node:stream';
+import type { Duplex, Readable, Writable } from 'node:stream';
 import type { SubprocessOutcome } from '@deepseek-ai/dsh-subprocess';
 /** Platform owner used by termination and whole-range settlement. */
 export interface BoundProcessOwner {
@@ -7,6 +7,11 @@ export interface BoundProcessOwner {
     signal(signal: 'SIGTERM' | 'SIGKILL', cancellationReason?: unknown): void;
     /** Wait for the same managed range to become empty; reject when it cannot be observed. */
     waitForExit(): Promise<void>;
+    /**
+     * Count tasks in the native range, including descendants outside the observable process tree.
+     * @returns the current count, or undefined when observation is unavailable.
+     */
+    inspectTaskCount?(): number | undefined;
     /** Synchronously force final termination during JavaScript-observable host exit. */
     terminateForHostExit(): void;
     /** Release provider-private protocol artifacts after outcome and range settlement. */
@@ -17,6 +22,7 @@ export interface ManagedProcessLaunch {
     stdin: Writable | null;
     stdout: Readable | null;
     stderr: Readable | null;
+    control?: Duplex | undefined;
     direct: Promise<SubprocessOutcome>;
     owner: BoundProcessOwner;
 }

package/lib/types/output.d.ts

@@ -0,0 +1,85 @@
+import type { CollectedOutput } from '@deepseek-ai/dsh-subprocess';
+/**
+ * Prepare fallible output storage before starting a managed native process.
+ * @param internals - optional caller-owned spill directory.
+ * @returns binding inputs whose spill directory is ready for use.
+ */
+export declare function prepareManagedProcessBinding(internals?: {
+    spillDir?: string;
+}): {
+    spillDir: string;
+};
+/**
+ * Collects one stream with a bounded in-memory tail. With a spill cap, on
+ * first overflow a spill file is created and every chunk (including those
+ * already collected) is appended there while the full stream remains within
+ * the cap; without one, only the in-memory tail is ever retained (the
+ * diagnostic-tail shape — a language server's stderr).
+ *
+ * Tail-keep rationale (pi/OpenCode): errors and final results cluster at the
+ * end of command output; the spill file covers the head.
+ */
+export declare class OutputCollector {
+    private readonly maxBytes;
+    private readonly maxSpillBytes;
+    private readonly label;
+    private readonly spillDir;
+    private chunks;
+    private bytes;
+    private dropped;
+    private spillFd;
+    private spillFile;
+    private spillDisabled;
+    /** Total bytes ever pushed (not just retained). */
+    private total;
+    constructor(maxBytes: number, maxSpillBytes: number | undefined, label: string, spillDir: string);
+    /**
+     * Ingest one stream chunk, counting it toward the whole-stream total. On
+     * first overflow of the in-memory cap a spill file is opened (when spilling
+     * is enabled) and every chunk (already-collected ones included) is appended
+     * there from then on; the in-memory tail then drops whole chunks from its
+     * head (or the head of a single over-cap chunk) until it fits the cap again.
+     * @param chunk - the raw bytes from one stream 'data' event.
+     */
+    push(chunk: Buffer): void;
+    /** Open the spill file lazily and append `chunk` (and any prior chunks once). */
+    private spillAll;
+    /** Stop spilling and remove the file once it can no longer hold the complete stream. */
+    private discardSpill;
+    /**
+     * Incremental read in whole-stream byte coordinates: returns everything
+     * pushed since `fromByte`. When `fromByte` has already slid out of the
+     * in-memory tail window, the read is `lossy` — it returns the whole
+     * retained tail and the gap is only recoverable from the spill file.
+     * @param fromByte - whole-stream offset to resume from (a prior read's `nextOffset`; 0 for the first read).
+     * @returns the delta text, the offset for the next read, the `lossy` flag, and the spill path when one was created.
+     */
+    readFrom(fromByte: number): {
+        text: string;
+        nextOffset: number;
+        lossy: boolean;
+        spillPath?: string;
+    };
+    /**
+     * Copy the retained raw tail with its position in the complete observed stream.
+     * @returns independent tail bytes and the total byte count before truncation.
+     */
+    snapshot(): {
+        bytes: Buffer;
+        totalBytes: number;
+    };
+    /**
+     * Close the spill file once the stream has ended. A failed close (delayed
+     * writeback fault) stops advertising the spill path — the file may be
+     * missing its tail — while every in-memory read keeps working. Idempotent;
+     * the spawn path seals both collectors at settlement so reads after exit
+     * never point at a still-open file.
+     */
+    seal(): void;
+    /**
+     * Seal the spill file and return the final output.
+     * @returns the final collected output: tail text, truncation flag, and the spill path when intact.
+     */
+    finalize(): CollectedOutput;
+}
+//# sourceMappingURL=output.d.ts.map

package/lib/types/process-inspector.d.ts

@@ -25,6 +25,8 @@ interface FileStatus {
  * is the fence a signal takes, because it reads current state instead.
  */
 export interface ProcessSnapshot {
+    /** Whether the process-table scan omitted no unreadable rows; absent means unverified. */
+    readonly complete?: boolean;
     /**
      * Return the root and its transitive descendants as observed, children first.
      * @param rootPid - tree root to descend from.
@@ -58,6 +60,7 @@ export interface ProcessInspector {
     /**
      * Read the process table once and answer tree, session, and liveness from it.
      * @returns A process-table observation whose reads are shared.
+     * @throws when the platform process table cannot be enumerated.
      */
     snapshot(): ProcessSnapshot;
     /**

package/lib/types/runner-launch.d.ts

@@ -39,7 +39,7 @@ export declare function consumeRunnerSelection(env?: NodeJS.ProcessEnv): string
 export declare function parseRunnerTargetArgv(argv: readonly string[]): string[];
 /**
  * Build direct Linux target stdio, or isolated Windows runner stdio with IPC
- * on fd 3 and target carriers on fd 4 through fd 6.
+ * on fd 3 and target carriers on fd 4 through fd 6; optional control uses fd 7.
  * @param spec - ordinary subprocess request whose stdio modes are preserved.
  * @param ipc - whether to isolate the runner and add its private Node IPC descriptor.
  * @param stdinCarrier - runner fd 4 carrier; Windows ignore passes an opened null-device fd.
@@ -62,5 +62,7 @@ export declare function resolveWindowsExecutable(command: string, cwd: string, e
  * @param spec - final target argv, cwd, and environment overrides.
  * @returns complete target environment after Node-equivalent validation.
  */
-export declare function targetEnvironment(spec: Pick<SubprocessSpawnSpec, 'argv' | 'cwd' | 'env'>): Record<string, string>;
+export declare function targetEnvironment(spec: Pick<SubprocessSpawnSpec, 'argv' | 'cwd' | 'env'> & {
+    stdio?: SubprocessSpawnSpec['stdio'];
+}): Record<string, string>;
 //# sourceMappingURL=runner-launch.d.ts.map

package/lib/types/runner-protocol.d.ts

@@ -3,6 +3,7 @@
 export interface LinuxLaunchRequest {
     cwd: string;
     env: Record<string, string>;
+    control?: 'pipe';
 }
 /** Bounded Node-shaped error fields allowed across a private runner boundary. */
 export interface SerializedRunnerError {
@@ -22,6 +23,7 @@ export interface WindowsStartRequest {
     type: 'start';
     cwd: string;
     env: Record<string, string>;
+    control?: 'pipe';
 }
 /** The only parent-to-runner control message on Windows. */
 export interface WindowsTerminateRequest {

package/lib/types/shell-activity.d.ts

@@ -0,0 +1,37 @@
+import type { SubprocessTerminalActivity, SubprocessTerminalSpawnSpec } from '@deepseek-ai/dsh-subprocess';
+/** Opt-in startup integration and revision tracking for one ordinary interactive shell. */
+export declare class ShellActivity {
+    private readonly directory;
+    readonly argv: readonly string[];
+    readonly env: Record<string, string>;
+    private revision;
+    private observed;
+    private invalidated;
+    private state;
+    /**
+     * @param directory - private startup and status file directory.
+     * @param argv - shell launch preserving supported user startup files.
+     * @param env - environment with any temporary startup redirect.
+     */
+    constructor(directory: string, argv: readonly string[], env: Record<string, string>);
+    /** Invalidate prompt evidence before delivering input or a foreground signal. */
+    invalidate(): void;
+    /**
+     * Read the latest top-level shell transition, fenced against input since that transition.
+     * @param pid - original shell process id.
+     * @returns lifecycle evidence; process ownership must be checked separately.
+     */
+    inspect(pid: number): SubprocessTerminalActivity;
+    /** Remove private startup and status files after process quiescence. */
+    dispose(): void;
+    private read;
+}
+/**
+ * Prepare optional Bash or Zsh integration for a plain, non-login interactive launch.
+ * @param spec - terminal request; custom arguments and wrapped executables remain unmodified.
+ * @param env - scrubbed target environment.
+ * @param platform - execution platform.
+ * @returns private integration, or undefined for unsupported launches.
+ */
+export declare function prepareShellActivity(spec: SubprocessTerminalSpawnSpec, env: Record<string, string>, platform: NodeJS.Platform): ShellActivity | undefined;
+//# sourceMappingURL=shell-activity.d.ts.map

package/lib/types/spawn-runner.d.ts

@@ -7,7 +7,7 @@ type RunnerHost = Pick<NodeJS.Process, 'env' | 'exitCode' | 'connected' | 'cwd'
 };
 /** Injectable operations used by the protocol-owner tests. */
 export interface SpawnRunnerInternals {
-    execve(file: string, argv: string[], env: Record<string, string>): never;
+    execve(file: string, argv: string[], env: Record<string, string>, control?: 'pipe'): never;
     loadWin32ProcessBindings(): CurrentTokenProcessBindings;
     spawnCurrentTokenJobProcess: typeof spawnCurrentTokenJobProcess;
     closeFileDescriptor(fileDescriptor: number): void;

package/lib/types/spawn.d.ts

@@ -8,7 +8,7 @@
  * @module dsh-subprocess-local/spawn
  */
 import { type ChildProcess, type SpawnOptions } from 'node:child_process';
-import type { CollectedOutput, SubprocessHandle, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess';
+import type { SubprocessHandle, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess';
 import type { ManagedProcessLaunch } from './managed-owner.ts';
 type SpawnProcess = (program: string, args: readonly string[], options: SpawnOptions) => ChildProcess;
 /**
@@ -42,79 +42,6 @@ export interface LocalSubprocessHandle extends SubprocessHandle {
     /** Force-terminate the current tree synchronously without starting timers or waits. */
     terminateForHostExit(): void;
 }
-/**
- * Prepare fallible output storage before starting a managed native process.
- * @param internals - optional caller-owned spill directory.
- * @returns binding inputs whose spill directory is ready for use.
- */
-export declare function prepareManagedProcessBinding(internals?: Pick<SpawnInternals, 'spillDir'>): {
-    spillDir: string;
-};
-/**
- * Collects one stream with a bounded in-memory tail. With a spill cap, on
- * first overflow a spill file is created and every chunk (including those
- * already collected) is appended there while the full stream remains within
- * the cap; without one, only the in-memory tail is ever retained (the
- * diagnostic-tail shape — a language server's stderr).
- *
- * Tail-keep rationale (pi/OpenCode): errors and final results cluster at the
- * end of command output; the spill file covers the head.
- */
-export declare class OutputCollector {
-    private readonly maxBytes;
-    private readonly maxSpillBytes;
-    private readonly label;
-    private readonly spillDir;
-    private chunks;
-    private bytes;
-    private dropped;
-    private spillFd;
-    private spillFile;
-    private spillDisabled;
-    /** Total bytes ever pushed (not just retained). */
-    private total;
-    constructor(maxBytes: number, maxSpillBytes: number | undefined, label: string, spillDir: string);
-    /**
-     * Ingest one stream chunk, counting it toward the whole-stream total. On
-     * first overflow of the in-memory cap a spill file is opened (when spilling
-     * is enabled) and every chunk (already-collected ones included) is appended
-     * there from then on; the in-memory tail then drops whole chunks from its
-     * head (or the head of a single over-cap chunk) until it fits the cap again.
-     * @param chunk - the raw bytes from one stream 'data' event.
-     */
-    push(chunk: Buffer): void;
-    /** Open the spill file lazily and append `chunk` (and any prior chunks once). */
-    private spillAll;
-    /** Stop spilling and remove the file once it can no longer hold the complete stream. */
-    private discardSpill;
-    /**
-     * Incremental read in whole-stream byte coordinates: returns everything
-     * pushed since `fromByte`. When `fromByte` has already slid out of the
-     * in-memory tail window, the read is `lossy` — it returns the whole
-     * retained tail and the gap is only recoverable from the spill file.
-     * @param fromByte - whole-stream offset to resume from (a prior read's `nextOffset`; 0 for the first read).
-     * @returns the delta text, the offset for the next read, the `lossy` flag, and the spill path when one was created.
-     */
-    readFrom(fromByte: number): {
-        text: string;
-        nextOffset: number;
-        lossy: boolean;
-        spillPath?: string;
-    };
-    /**
-     * Close the spill file once the stream has ended. A failed close (delayed
-     * writeback fault) stops advertising the spill path — the file may be
-     * missing its tail — while every in-memory read keeps working. Idempotent;
-     * the spawn path seals both collectors at settlement so reads after exit
-     * never point at a still-open file.
-     */
-    seal(): void;
-    /**
-     * Seal the spill file and return the final output.
-     * @returns the final collected output: tail text, truncation flag, and the spill path when intact.
-     */
-    finalize(): CollectedOutput;
-}
 /**
  * Send `sig` to a detached POSIX process group. Never throws: delivery races
  * process exit and may run in a timer callback, so failures are contained and

package/lib/types/terminal.d.ts

@@ -1,9 +1,10 @@
 /** Local node-pty terminal-process implementation for the subprocess seam. */
 import { PassThrough } from 'node:stream';
 import type { IPty } from 'node-pty';
-import type { SubprocessOutcome, SubprocessTerminalForeground, SubprocessTerminalHandle, SubprocessTerminalSignal } from '@deepseek-ai/dsh-subprocess';
+import type { SubprocessOutcome, SubprocessTerminalActivity, SubprocessTerminalForeground, SubprocessTerminalHandle, SubprocessTerminalSignal } from '@deepseek-ai/dsh-subprocess';
 import type { BoundProcessOwner } from './managed-owner.ts';
 import type { ProcessInspector } from './process-inspector.ts';
+import type { ShellActivity } from './shell-activity.ts';
 /**
  * A local terminal whose native managed range or fallback process-session
  * ownership stays below the PTY backend.
@@ -20,6 +21,9 @@ export declare class LocalTerminalHandle implements SubprocessTerminalHandle {
     private readonly platform;
     private readonly managedOwner?;
     private readonly resolveManagedOutcome?;
+    private readonly shellActivity?;
+    private readonly onQuiescence?;
+    private readonly observeShellExit;
     readonly pid: number;
     readonly output: PassThrough;
     readonly done: Promise<SubprocessOutcome>;
@@ -29,7 +33,12 @@ export declare class LocalTerminalHandle implements SubprocessTerminalHandle {
     private cleanup;
     private managedOwnerCleaned;
     private exited;
+    private outputPaused;
     private trackedDescendants;
+    private activityRevision;
+    private activityKey;
+    private quiescent;
+    private managedRangeEmpty;
     /** The spawned shell's start identity; scans stop adopting members once the root pid no longer carries it. */
     private readonly rootIdentity;
     /**
@@ -38,11 +47,13 @@ export declare class LocalTerminalHandle implements SubprocessTerminalHandle {
      * @param graceMs - TERM-to-KILL and exit-wait grace.
      * @param platform - host platform; defaults to the running platform, injectable for deterministic tests.
      */
-    constructor(terminal: IPty, inspector: ProcessInspector, graceMs: number, platform?: NodeJS.Platform, managedOwner?: BoundProcessOwner | undefined, resolveManagedOutcome?: ((outcome: SubprocessOutcome) => SubprocessOutcome) | undefined);
+    constructor(terminal: IPty, inspector: ProcessInspector, graceMs: number, platform?: NodeJS.Platform, managedOwner?: BoundProcessOwner | undefined, resolveManagedOutcome?: ((outcome: SubprocessOutcome) => SubprocessOutcome) | undefined, shellActivity?: Pick<ShellActivity, "inspect" | "invalidate" | "dispose"> | undefined, onQuiescence?: (() => void) | undefined, observeShellExit?: boolean);
     /** Whether node-pty has not yet published the top-level exit event. */
     get running(): boolean;
     write(data: string): Promise<void>;
+    resize(cols: number, rows: number): Promise<void>;
     inspectForeground(): Promise<SubprocessTerminalForeground | undefined>;
+    inspectActivity(): Promise<SubprocessTerminalActivity>;
     signalForeground(signal: SubprocessTerminalSignal): Promise<number>;
     terminate(): Promise<void>;
     /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-subprocess-local",
   "description": "Local-subprocess implementation of the DeepSeek Harness subprocess seam",
-  "version": "0.1.5-rc.2",
+  "version": "0.1.6-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -23,30 +23,36 @@
       "default": "./lib/runner.js"
     },
     "./src/*": "./src/*",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./output": {
+      "types": "./lib/types/output.d.ts",
+      "default": "./lib/output.js"
+    }
   },
   "files": [
     "lib/index.js",
     "lib/runner.js",
     "lib/runner-*.js",
+    "lib/output.js",
     "scripts/ensure-spawn-helper.mjs",
     "lib/types/**/*.d.ts"
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-subprocess": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-timeout": "^0.1.5-rc.2",
-    "@deepseek-ai/cordis": "^4.0.2"
+    "@deepseek-ai/dsh-subprocess": "^0.1.6-alpha.2",
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-timeout": "^0.1.6-alpha.2"
   },
   "dependencies": {
     "koffi": "^3.1.0",
     "node-pty": "1.2.0-beta.15",
-    "@deepseek-ai/dsh-win32-process": "^0.1.5-rc.2"
+    "@deepseek-ai/dsh-lazy-require": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-win32-process": "^0.1.6-alpha.2"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-loader-smoke": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-subprocess": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-timeout": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-subprocess": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-loader-smoke": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-timeout": "^0.1.6-alpha.2",
     "@deepseek-ai/cordis": "^4.0.2"
   },
   "scripts": {