@loucompanion/forge-bridge 0.1.3-dev.fbe15023cdfe → 0.1.4-dev.1ff37038366e

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loucompanion/forge-bridge",
-  "version": "0.1.3-dev.fbe15023cdfe",
+  "version": "0.1.4-dev.1ff37038366e",
   "description": "Forge runner bridge CLI for connecting local developer machines to Forge dispatch.",
   "license": "UNLICENSED",
   "type": "module",
@@ -32,16 +32,17 @@
     "url": "https://github.com/coleman399/Forge/issues"
   },
   "engines": {
-    "node": ">=22.13.0"
+    "node": "^22.13.0 || >=24.0.0"
   },
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "vitest run",
+    "test": "node scripts/run-owned-tests.mjs",
+    "test:residue": "node scripts/run-owned-residue-gate.mjs",
     "test:watch": "vitest",
-    "smoke:package": "npm run build && node scripts/smoke-package.mjs",
+    "smoke:package": "tsc -p tsconfig.json && node scripts/smoke-package.mjs",
     "lint": "eslint \"src/**/*.ts\" \"scripts/**/*.mjs\" \"vitest.config.ts\" \"vitest.setup.ts\""
   },
   "dependencies": {
@@ -55,6 +56,7 @@
     "globals": "^17.6.0",
     "typescript": "^5.8.3",
     "typescript-eslint": "^8.61.1",
-    "vitest": "^3.2.3"
+    "vite": "^7.3.7",
+    "vitest": "^4.1.12"
   }
 }

package/runtime/windows-job-supervisor.ps1

@@ -6,6 +6,10 @@ param(
   [Parameter(Mandatory = $true)]
   [string]$PayloadPath,
 
+  [Parameter(Mandatory = $true)]
+  [ValidatePattern("^[0-9a-f]{64}$")]
+  [string]$PayloadSha256,
+
   [string]$GateName
 )
 
@@ -13,8 +17,238 @@ $ErrorActionPreference = "Stop"
 
 Add-Type -TypeDefinition @"
 using System;
+using System.IO;
 using System.Runtime.InteropServices;
 using System.Text;
+using Microsoft.Win32.SafeHandles;
+
+// A provider created suspended exists (so its exact identity can be recorded)
+// but runs no code until Resume. Providers such as Claude stop waiting for
+// stdin after a few seconds, so the start grant must gate execution, not input.
+public sealed class ForgeSuspendedProcess : IDisposable
+{
+    [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
+    private struct STARTUPINFO
+    {
+        public int cb;
+        public string lpReserved;
+        public string lpDesktop;
+        public string lpTitle;
+        public int dwX;
+        public int dwY;
+        public int dwXSize;
+        public int dwYSize;
+        public int dwXCountChars;
+        public int dwYCountChars;
+        public int dwFillAttribute;
+        public int dwFlags;
+        public short wShowWindow;
+        public short cbReserved2;
+        public IntPtr lpReserved2;
+        public IntPtr hStdInput;
+        public IntPtr hStdOutput;
+        public IntPtr hStdError;
+    }
+
+    [StructLayout(LayoutKind.Sequential)]
+    private struct PROCESS_INFORMATION
+    {
+        public IntPtr hProcess;
+        public IntPtr hThread;
+        public int dwProcessId;
+        public int dwThreadId;
+    }
+
+    [StructLayout(LayoutKind.Sequential)]
+    private struct SECURITY_ATTRIBUTES
+    {
+        public int nLength;
+        public IntPtr lpSecurityDescriptor;
+        public bool bInheritHandle;
+    }
+
+    private const uint CREATE_SUSPENDED = 0x00000004;
+    private const uint CREATE_NO_WINDOW = 0x08000000;
+    private const int STARTF_USESTDHANDLES = 0x00000100;
+    private const int HANDLE_FLAG_INHERIT = 0x00000001;
+    private const uint INFINITE = 0xFFFFFFFF;
+
+    [DllImport("kernel32.dll", SetLastError = true)]
+    private static extern bool CreatePipe(
+        out SafeFileHandle readPipe,
+        out SafeFileHandle writePipe,
+        ref SECURITY_ATTRIBUTES attributes,
+        int size);
+
+    [DllImport("kernel32.dll", SetLastError = true)]
+    private static extern bool SetHandleInformation(SafeFileHandle handle, int mask, int flags);
+
+    [DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
+    private static extern bool CreateProcess(
+        string applicationName,
+        StringBuilder commandLine,
+        IntPtr processAttributes,
+        IntPtr threadAttributes,
+        bool inheritHandles,
+        uint creationFlags,
+        IntPtr environment,
+        string currentDirectory,
+        ref STARTUPINFO startupInfo,
+        out PROCESS_INFORMATION processInformation);
+
+    [DllImport("kernel32.dll", SetLastError = true)]
+    private static extern uint ResumeThread(IntPtr thread);
+
+    [DllImport("kernel32.dll", SetLastError = true)]
+    private static extern uint WaitForSingleObject(IntPtr handle, uint milliseconds);
+
+    [DllImport("kernel32.dll", SetLastError = true)]
+    private static extern bool GetExitCodeProcess(IntPtr process, out uint exitCode);
+
+    [DllImport("kernel32.dll", SetLastError = true)]
+    private static extern bool TerminateProcess(IntPtr process, uint exitCode);
+
+    [DllImport("kernel32.dll", SetLastError = true)]
+    private static extern bool CloseHandle(IntPtr handle);
+
+    private IntPtr process;
+    private IntPtr thread;
+
+    private ForgeSuspendedProcess(PROCESS_INFORMATION information, Stream input, Stream output, Stream error)
+    {
+        process = information.hProcess;
+        thread = information.hThread;
+        Id = information.dwProcessId;
+        StandardInput = input;
+        StandardOutput = output;
+        StandardError = error;
+    }
+
+    public int Id { get; private set; }
+    public Stream StandardInput { get; private set; }
+    public Stream StandardOutput { get; private set; }
+    public Stream StandardError { get; private set; }
+
+    // Builds the same command line System.Diagnostics.Process does, so command
+    // resolution is unchanged from the unsuspended launch.
+    public static ForgeSuspendedProcess Start(string fileName, string arguments, string workingDirectory)
+    {
+        SafeFileHandle inputRead = null, inputWrite = null;
+        SafeFileHandle outputRead = null, outputWrite = null;
+        SafeFileHandle errorRead = null, errorWrite = null;
+        bool started = false;
+        try
+        {
+            CreateChildPipe(out inputRead, out inputWrite, false);
+            CreateChildPipe(out outputRead, out outputWrite, true);
+            CreateChildPipe(out errorRead, out errorWrite, true);
+
+            var startupInfo = new STARTUPINFO();
+            startupInfo.cb = Marshal.SizeOf(typeof(STARTUPINFO));
+            startupInfo.dwFlags = STARTF_USESTDHANDLES;
+            startupInfo.hStdInput = inputRead.DangerousGetHandle();
+            startupInfo.hStdOutput = outputWrite.DangerousGetHandle();
+            startupInfo.hStdError = errorWrite.DangerousGetHandle();
+
+            string trimmed = fileName.Trim();
+            bool quoted = trimmed.StartsWith("\"", StringComparison.Ordinal) && trimmed.EndsWith("\"", StringComparison.Ordinal);
+            var commandLine = new StringBuilder();
+            if (!quoted) commandLine.Append('"');
+            commandLine.Append(trimmed);
+            if (!quoted) commandLine.Append('"');
+            if (!String.IsNullOrEmpty(arguments)) commandLine.Append(' ').Append(arguments);
+
+            PROCESS_INFORMATION information;
+            if (!CreateProcess(
+                null,
+                commandLine,
+                IntPtr.Zero,
+                IntPtr.Zero,
+                true,
+                CREATE_SUSPENDED | CREATE_NO_WINDOW,
+                IntPtr.Zero,
+                String.IsNullOrEmpty(workingDirectory) ? null : workingDirectory,
+                ref startupInfo,
+                out information))
+            {
+                throw new System.ComponentModel.Win32Exception(Marshal.GetLastWin32Error(), "CreateProcess failed.");
+            }
+
+            started = true;
+            return new ForgeSuspendedProcess(
+                information,
+                new FileStream(inputWrite, FileAccess.Write, 4096, false),
+                new FileStream(outputRead, FileAccess.Read, 4096, false),
+                new FileStream(errorRead, FileAccess.Read, 4096, false));
+        }
+        finally
+        {
+            // The child owns its ends now; keeping them open would hide EOF.
+            if (inputRead != null) inputRead.Dispose();
+            if (outputWrite != null) outputWrite.Dispose();
+            if (errorWrite != null) errorWrite.Dispose();
+            if (!started)
+            {
+                if (inputWrite != null) inputWrite.Dispose();
+                if (outputRead != null) outputRead.Dispose();
+                if (errorRead != null) errorRead.Dispose();
+            }
+        }
+    }
+
+    // Only the child's end is inheritable; the supervisor's end stays private.
+    private static void CreateChildPipe(out SafeFileHandle read, out SafeFileHandle write, bool parentReads)
+    {
+        var attributes = new SECURITY_ATTRIBUTES();
+        attributes.nLength = Marshal.SizeOf(typeof(SECURITY_ATTRIBUTES));
+        attributes.bInheritHandle = true;
+        if (!CreatePipe(out read, out write, ref attributes, 0))
+        {
+            throw new System.ComponentModel.Win32Exception(Marshal.GetLastWin32Error(), "CreatePipe failed.");
+        }
+        SafeFileHandle parentEnd = parentReads ? read : write;
+        if (!SetHandleInformation(parentEnd, HANDLE_FLAG_INHERIT, 0))
+        {
+            throw new System.ComponentModel.Win32Exception(Marshal.GetLastWin32Error(), "SetHandleInformation failed.");
+        }
+    }
+
+    public void Resume()
+    {
+        if (ResumeThread(thread) == UInt32.MaxValue)
+        {
+            throw new System.ComponentModel.Win32Exception(Marshal.GetLastWin32Error(), "ResumeThread failed.");
+        }
+    }
+
+    public int WaitForExit()
+    {
+        if (WaitForSingleObject(process, INFINITE) != 0)
+        {
+            throw new System.ComponentModel.Win32Exception(Marshal.GetLastWin32Error(), "WaitForSingleObject failed.");
+        }
+        uint exitCode;
+        if (!GetExitCodeProcess(process, out exitCode))
+        {
+            throw new System.ComponentModel.Win32Exception(Marshal.GetLastWin32Error(), "GetExitCodeProcess failed.");
+        }
+        return unchecked((int)exitCode);
+    }
+
+    public void Kill()
+    {
+        TerminateProcess(process, 1);
+    }
+
+    public void Dispose()
+    {
+        StandardInput.Dispose();
+        StandardOutput.Dispose();
+        StandardError.Dispose();
+        if (thread != IntPtr.Zero) { CloseHandle(thread); thread = IntPtr.Zero; }
+        if (process != IntPtr.Zero) { CloseHandle(process); process = IntPtr.Zero; }
+    }
+}
 
 public static class ForgeWindowsJob
 {
@@ -73,6 +307,14 @@ public static class ForgeWindowsJob
     [DllImport("kernel32.dll", SetLastError = true)]
     public static extern bool TerminateJobObject(IntPtr job, uint exitCode);
 
+    [DllImport("kernel32.dll", SetLastError = true)]
+    private static extern bool QueryInformationJobObject(
+        IntPtr job,
+        int informationClass,
+        IntPtr information,
+        uint informationLength,
+        out uint returnLength);
+
     [DllImport("kernel32.dll", SetLastError = true)]
     public static extern bool CloseHandle(IntPtr handle);
 
@@ -109,6 +351,28 @@ public static class ForgeWindowsJob
         return job;
     }
 
+    public static ulong PeakJobMemoryUsed(IntPtr job)
+    {
+        int size = Marshal.SizeOf(typeof(JOBOBJECT_EXTENDED_LIMIT_INFORMATION));
+        IntPtr pointer = Marshal.AllocHGlobal(size);
+        try
+        {
+            uint returned;
+            if (!QueryInformationJobObject(job, JobObjectExtendedLimitInformation, pointer, (uint)size, out returned))
+            {
+                throw new System.ComponentModel.Win32Exception(Marshal.GetLastWin32Error(), "QueryInformationJobObject failed.");
+            }
+            var information = (JOBOBJECT_EXTENDED_LIMIT_INFORMATION)Marshal.PtrToStructure(
+                pointer,
+                typeof(JOBOBJECT_EXTENDED_LIMIT_INFORMATION));
+            return information.PeakJobMemoryUsed.ToUInt64();
+        }
+        finally
+        {
+            Marshal.FreeHGlobal(pointer);
+        }
+    }
+
     public static string BuildArguments(object[] arguments)
     {
         var result = new StringBuilder();
@@ -162,7 +426,19 @@ function Read-ForgeSupervisorPayload {
   if (-not [IO.Path]::IsPathRooted($PayloadPath)) {
     throw "The supervisor payload path must be absolute."
   }
-  $json = [IO.File]::ReadAllText($PayloadPath, [Text.Encoding]::UTF8)
+  $bytes = [IO.File]::ReadAllBytes($PayloadPath)
+  $hasher = [Security.Cryptography.SHA256]::Create()
+  try {
+    $actualSha256 = -join ($hasher.ComputeHash($bytes) | ForEach-Object { $_.ToString("x2") })
+  }
+  finally {
+    $hasher.Dispose()
+  }
+  if (-not [string]::Equals($actualSha256, $PayloadSha256, [StringComparison]::Ordinal)) {
+    throw "The supervisor payload does not match its expected SHA-256 identity."
+  }
+  $utf8 = New-Object Text.UTF8Encoding($false, $true)
+  $json = $utf8.GetString($bytes)
   return $json | ConvertFrom-Json
 }
 
@@ -208,7 +484,32 @@ function New-ForgeChildProcess(
   }
 }
 
-function Write-ForgeProviderReady([object]$request, [Diagnostics.Process]$provider) {
+function New-ForgeSuspendedProvider([string]$command, [object[]]$arguments, [string]$workingDirectory) {
+  $maximumAttempts = 3
+  for ($attempt = 1; $attempt -le $maximumAttempts; $attempt += 1) {
+    try {
+      $provider = [ForgeSuspendedProcess]::Start(
+        $command,
+        [ForgeWindowsJob]::BuildArguments($arguments),
+        $workingDirectory)
+      $provider | Add-Member -NotePropertyName ForgeStartAttempt -NotePropertyValue $attempt
+      return $provider
+    }
+    catch {
+      $nativeError = $_.Exception
+      while ($nativeError.InnerException) {
+        $nativeError = $nativeError.InnerException
+      }
+      $retryable = $nativeError -is [ComponentModel.Win32Exception] -and $nativeError.NativeErrorCode -in @(5, 32, 33)
+      if (-not $retryable -or $attempt -eq $maximumAttempts) {
+        throw
+      }
+      Start-Sleep -Milliseconds (100 * $attempt)
+    }
+  }
+}
+
+function Write-ForgeProviderReady([object]$request, [object]$provider) {
   $readyPath = [string]$request.readyPath
   if ([string]::IsNullOrWhiteSpace($readyPath) -or -not [IO.Path]::IsPathRooted($readyPath)) {
     throw "The provider-ready path must be absolute."
@@ -219,14 +520,17 @@ function Write-ForgeProviderReady([object]$request, [Diagnostics.Process]$provid
     throw "The provider-ready path must be beside the supervisor payload."
   }
 
+  # The supervisor holds the provider's process handle, so this PID cannot be
+  # reused before its start time is read.
+  $providerStartTime = (Get-Process -Id $provider.Id -ErrorAction Stop).StartTime.ToUniversalTime()
   $ready = @{
     schemaVersion = 1
     supervisorId = [string]$request.supervisorId
     rootPid = [int]$env:FORGE_SUPERVISOR_ROOT_PID
     rootIdentity = [string]$env:FORGE_SUPERVISOR_ROOT_IDENTITY
     providerPid = $provider.Id
-    providerCreatedAt = $provider.StartTime.ToUniversalTime().ToString("O")
-    providerIdentity = "win32:$($provider.StartTime.ToUniversalTime().Ticks)"
+    providerCreatedAt = $providerStartTime.ToString("O")
+    providerIdentity = "win32:$($providerStartTime.Ticks)"
     startAttempt = [int]$provider.ForgeStartAttempt
   } | ConvertTo-Json -Compress
   $temporaryPath = "$readyPath.$([Guid]::NewGuid().ToString('N')).tmp"
@@ -253,13 +557,17 @@ function Wait-ForgeProviderStartGrant([object]$request) {
   throw "Timed out waiting for the provider start grant."
 }
 
-function Start-ForgeOutputCopies([Diagnostics.Process]$child) {
+function Start-ForgeStreamCopies([IO.Stream]$output, [IO.Stream]$errorOutput) {
   return @(
-    $child.StandardOutput.BaseStream.CopyToAsync([Console]::OpenStandardOutput()),
-    $child.StandardError.BaseStream.CopyToAsync([Console]::OpenStandardError())
+    $output.CopyToAsync([Console]::OpenStandardOutput()),
+    $errorOutput.CopyToAsync([Console]::OpenStandardError())
   )
 }
 
+function Start-ForgeOutputCopies([Diagnostics.Process]$child) {
+  return Start-ForgeStreamCopies $child.StandardOutput.BaseStream $child.StandardError.BaseStream
+}
+
 function Write-ForgeStandardInput([Diagnostics.Process]$child, [string]$inputText) {
   if ($inputText.Length -gt 0) {
     $child.StandardInput.Write($inputText)
@@ -267,6 +575,45 @@ function Write-ForgeStandardInput([Diagnostics.Process]$child, [string]$inputTex
   $child.StandardInput.Close()
 }
 
+function Write-ForgeMemoryTelemetry([object]$request, [IntPtr]$job) {
+  $telemetryPath = [string]$request.memoryTelemetryPath
+  if ([string]::IsNullOrWhiteSpace($telemetryPath) -or -not [IO.Path]::IsPathRooted($telemetryPath)) {
+    throw "The memory telemetry path must be absolute."
+  }
+  $payloadDirectory = [IO.Path]::GetDirectoryName([IO.Path]::GetFullPath($PayloadPath))
+  $telemetryDirectory = [IO.Path]::GetDirectoryName([IO.Path]::GetFullPath($telemetryPath))
+  if (-not [string]::Equals($payloadDirectory, $telemetryDirectory, [StringComparison]::OrdinalIgnoreCase)) {
+    throw "The memory telemetry path must be beside the supervisor payload."
+  }
+  $telemetry = @{
+    schemaVersion = 1
+    peakMemoryBytes = [ForgeWindowsJob]::PeakJobMemoryUsed($job)
+    sampleCount = 1
+    source = "windows_job_object_peak_job_memory"
+    observedAt = [DateTimeOffset]::UtcNow.ToString("O")
+  } | ConvertTo-Json -Compress
+  $temporaryPath = "$telemetryPath.$([Guid]::NewGuid().ToString('N')).tmp"
+  try {
+    [IO.File]::WriteAllText($temporaryPath, "$telemetry`n", (New-Object Text.UTF8Encoding($false)))
+    [IO.File]::Move($temporaryPath, $telemetryPath)
+  }
+  finally {
+    if ([IO.File]::Exists($temporaryPath)) {
+      try { [IO.File]::Delete($temporaryPath) } catch { }
+    }
+  }
+}
+
+function Write-ForgeMemoryTelemetryBestEffort([object]$request, [IntPtr]$job) {
+  try {
+    Write-ForgeMemoryTelemetry $request $job
+  }
+  catch {
+    # Telemetry is optional. Provider output, descendant cleanup, and the real
+    # provider exit code remain authoritative if querying or persisting it fails.
+  }
+}
+
 if ($Mode -eq "Inner") {
   if ([string]::IsNullOrWhiteSpace($GateName)) {
     throw "The inner supervisor requires a gate name."
@@ -284,17 +631,33 @@ if ($Mode -eq "Inner") {
     $gate.Dispose()
   }
 
-  $provider = New-ForgeChildProcess ([string]$request.command) @($request.args) ([string]$request.cwd) $true
-  Write-ForgeProviderReady $request $provider
-  $copies = Start-ForgeOutputCopies $provider
-  Wait-ForgeProviderStartGrant $request
-  Write-ForgeStandardInput $provider $inputText
-  $provider.WaitForExit()
+  # The provider exists for the ready record but runs nothing until the start
+  # grant. Its input is written only after Resume: a prompt larger than the pipe
+  # buffer would otherwise block against a reader that cannot run.
+  $provider = New-ForgeSuspendedProvider ([string]$request.command) @($request.args) ([string]$request.cwd)
+  try {
+    Write-ForgeProviderReady $request $provider
+    $copies = Start-ForgeStreamCopies $provider.StandardOutput $provider.StandardError
+    Wait-ForgeProviderStartGrant $request
+    $provider.Resume()
+  }
+  catch {
+    $provider.Kill()
+    $provider.Dispose()
+    throw
+  }
+  # Same encoding System.Diagnostics.Process uses for redirected input.
+  $inputWriter = New-Object IO.StreamWriter($provider.StandardInput, [Console]::InputEncoding, 4096)
+  if ($inputText.Length -gt 0) {
+    $inputWriter.Write($inputText)
+  }
+  $inputWriter.Close()
+  $exitCode = $provider.WaitForExit()
   if (-not [Threading.Tasks.Task]::WaitAll([Threading.Tasks.Task[]]$copies, 1000)) {
     $provider.StandardOutput.Dispose()
     $provider.StandardError.Dispose()
   }
-  exit $provider.ExitCode
+  exit $exitCode
 }
 
 $inputText = [Console]::In.ReadToEnd()
@@ -323,6 +686,8 @@ try {
     "Inner",
     "-PayloadPath",
     $PayloadPath,
+    "-PayloadSha256",
+    $PayloadSha256,
     "-GateName",
     $gateNameValue
   )
@@ -343,6 +708,7 @@ try {
   }
 
   $exitCode = $inner.ExitCode
+  Write-ForgeMemoryTelemetryBestEffort $request $job
   [ForgeWindowsJob]::TerminateJobObject($job, 1) | Out-Null
   [Threading.Tasks.Task]::WaitAll([Threading.Tasks.Task[]]$copies, 2000) | Out-Null
   exit $exitCode