@petercjl/topazlabscli 0.2.3 → 0.2.5

package/README.md

@@ -15,7 +15,7 @@ npm install --global @petercjl/topazlabscli
 topazlabscli skill install --agent all
 ```
 
-The CLI checks npm for a newer stable release before operational commands, at most once every six hours. It first uses the registry already configured for npm and automatically tries `https://registry.npmmirror.com/` if that registry is unavailable. The successful registry is used to download the complete update tarball before the installed version is touched, without changing the user's `.npmrc`. When an update is available the CLI upgrades itself from that local tarball, refreshes installed Agent Skills, and then resumes the original command. It discovers npm through the running Node installation, preserves SealSeek's managed global prefix/cache, and discovers Windows OpenSSH through the standard system location, so it also works in Agent runtimes with a restricted `PATH`. A temporary registry outage does not block video processing. `topazlabscli update` forces an immediate manual update.
+The CLI checks npm for a newer stable release before operational commands, at most once every six hours. It first uses the registry already configured for npm and automatically tries `https://registry.npmmirror.com/` if that registry is unavailable. The successful registry is used to download the exact discovered version as a complete tarball before the installed version is touched, without changing the user's `.npmrc`. When an update is available the CLI upgrades itself from that local tarball, refreshes installed Agent Skills, and then resumes the original command. It discovers npm through the running Node installation, preserves SealSeek's managed global prefix/cache, and discovers Windows OpenSSH through the standard system location, so it also works in Agent runtimes with a restricted `PATH`. A temporary registry outage does not block video processing. `topazlabscli update` forces an immediate manual update.
 
 On Windows, SealSeek Skills are installed into `%USERPROFILE%\.sealseek\workspace\skills` when that workspace is present. The CLI automatically uses a managed copy because SealSeek rejects junctions that resolve outside the workspace Skill root; subsequent CLI updates refresh the copy from the npm package. The copy includes a local runtime manifest so the Agent can invoke the canonical package even when its PATH is restricted. `SEALSEEK_SKILLS_HOME` remains available as an explicit override.
 
@@ -55,7 +55,7 @@ topazlabscli doctor --json
 topazlabscli model status --json
 ```
 
-The worker uses a global Windows mutex and one queue consumer, so jobs from multiple clients run serially.
+The CLI automatically upgrades the remote worker when the bundled worker version changes. `process` and `job wait` keep the queue runner attached to the active SSH command, while a global mutex and one queue consumer serialize jobs from multiple clients. This avoids Windows Agent runtimes terminating a detached SSH child. An abandoned `running` record is converted to a terminal `WORKER_LOST` failure instead of waiting forever.
 
 ## Process a video
 
@@ -74,7 +74,7 @@ topazlabscli job wait JOB_ID --json
 topazlabscli job download JOB_ID --output .\output-1080p.mp4 --json
 ```
 
-Version 0.2 includes one preset: `seedance-human-1080p`, using Proteus v4 (`prob-4`), source FPS, aspect-preserving 1080p output, and NVIDIA H.264 encoding.
+Version 0.2 includes one preset: `seedance-human-1080p`, using Proteus v4 (`prob-4`), source FPS, aspect-preserving 1080p output, and NVIDIA H.264 encoding. The client reads MP4 track dimensions before upload so the worker does not depend on launching Topaz's bundled FFprobe through a remote shell.
 
 ## Configuration
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@petercjl/topazlabscli",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Cross-Agent CLI and portable Skill for queued remote Topaz Video AI processing",
   "type": "module",
   "bin": {
@@ -19,7 +19,7 @@
   },
   "scripts": {
     "test": "node --test",
-    "check": "node --check bin/topazlabscli.mjs && node --check src/cli.mjs && node --check src/runtime.mjs && node --check src/update.mjs && npm test"
+    "check": "node --check bin/topazlabscli.mjs && node --check src/cli.mjs && node --check src/media.mjs && node --check src/runtime.mjs && node --check src/ssh.mjs && node --check src/update.mjs && npm test"
   },
   "publishConfig": {
     "access": "public",

package/skill/topazlabscli/SKILL.md

@@ -32,6 +32,7 @@ Use the CLI as the single execution surface. Do not reproduce SSH, SFTP, queue,
 - Connection failure: report `CONNECTION_FAILED` and the endpoint attempts. The CLI does not start, reconfigure, or grant access to a VPN.
 - Worker/model not ready: run `worker status` or `model status`; stop with the returned dependency error. Installing/licensing Topaz and downloading models remain GUI administration tasks.
 - Long-running work: use `job submit`, return the job ID, then `job wait` when the user asks to remain attached. Do not resubmit merely because a wait timed out.
+- Remote runner loss: `process` and `job wait` keep the queue runner attached through the active SSH command instead of relying on a detached client process. `job status` and `job wait` convert an abandoned `running` record into a terminal `WORKER_LOST` failure. Report it and resubmit only when the user requests another processing attempt.
 - Cancellation: queued work may cancel immediately. A running task records a cancellation request but is not forcibly killed in version 0.2.
 - Missing capability: return `CAPABILITY_UNAVAILABLE` or the CLI's structured error. Do not invent a platform-specific workaround.
 
@@ -39,7 +40,9 @@ Use the CLI as the single execution surface. Do not reproduce SSH, SFTP, queue,
 
 Configuration, hostnames, addresses, usernames, SSH identities, VPN details, media, Topaz binaries, models, and credentials are external to this Skill and npm package. Installation does not grant access to a workstation. Treat the configured server and Topaz license as user-managed resources.
 
-Before operational commands, the CLI performs a cached npm update check. It tries the user's current npm registry and then its built-in reachable-registry fallback without changing the user's global npm configuration. A newer stable package is fully downloaded from the registry that answered the version check before the installed version is touched, then installed Agent Skills are refreshed and the original command resumes under the new version. The CLI resolves npm through the running Agent's Node installation when PATH is restricted. Registry, npm, and Skill-refresh failures produce a warning and continue with the installed version. Treat `doctor`'s `updates.registry` check as advisory; a failed update source does not make video processing unavailable.
+Before submitting a job, the CLI compares the remote worker version with its bundled worker and upgrades the remote worker when required. Queue execution stays attached to the invoking CLI command; the Agent must wait for the command's terminal JSON result and must not background or abandon it.
+
+Before operational commands, the CLI performs a cached npm update check. It tries the user's current npm registry and then its built-in reachable-registry fallback without changing the user's global npm configuration. The exact version returned by that check is fully downloaded from the same registry before the installed version is touched, then installed Agent Skills are refreshed and the original command resumes under the new version. The CLI resolves npm through the running Agent's Node installation when PATH is restricted. Registry, npm, and Skill-refresh failures produce a warning and continue with the installed version. Treat `doctor`'s `updates.registry` check as advisory; a failed update source does not make video processing unavailable.
 
 Do not overwrite a local output unless the user has authorized that exact existing target. The remote worker retains job inputs, outputs, status, and logs for operator review; cleanup is an administrative action outside version 0.2.
 

package/src/cli.mjs

@@ -6,13 +6,15 @@ import { loadConfig, saveConfig, resolveTarget } from "./config.mjs";
 import { configPath, workerScript } from "./paths.mjs";
 import { CliError, requireValue } from "./errors.mjs";
 import { run } from "./process.mjs";
-import { psLiteral, runPowerShell, selectEndpoint, sftpGet, sftpPut, startPowerShellDetached } from "./ssh.mjs";
+import { probeMp4Dimensions } from "./media.mjs";
+import { psLiteral, runPowerShell, selectEndpoint, sftpGet, sftpPut } from "./ssh.mjs";
 import { skillInstall, skillSource, skillStatus } from "./skill.mjs";
 import { installLatestPackage, maybeAutoUpdate, queryLatestVersion, updateRegistryWarning } from "./update.mjs";
 
 const require = createRequire(import.meta.url);
 const pkg = require("../package.json");
 const PRESET = "seedance-human-1080p";
+const WORKER_VERSION = "0.2.0";
 
 const CAPABILITIES = {
   schema_version: 1,
@@ -99,10 +101,10 @@ function parseRemoteJson(result, code = "REMOTE_ERROR") {
   catch { throw new CliError("REMOTE_OUTPUT_INVALID", "Remote worker did not return valid JSON.", { output: text }); }
 }
 
-async function remoteAction(target, endpoint, action, params = {}) {
+async function remoteAction(target, endpoint, action, params = {}, { timeout = 7 } = {}) {
   const encoded = Buffer.from(JSON.stringify(params), "utf8").toString("base64");
   const extra = Object.keys(params).length ? `-PayloadBase64 ${psLiteral(encoded)}` : "";
-  return parseRemoteJson(await runPowerShell(target, endpoint, workerInvocation(remoteRoot(target), action, extra)));
+  return parseRemoteJson(await runPowerShell(target, endpoint, workerInvocation(remoteRoot(target), action, extra), { timeout }));
 }
 
 async function getConnectedTarget(requested) {
@@ -111,18 +113,44 @@ async function getConnectedTarget(requested) {
   return { target, ...selected };
 }
 
+async function installWorker(target, endpoint) {
+  const root = remoteRoot(target);
+  const remote = `${root}\\.topazlabscli\\worker\\topazlabs-worker.ps1`;
+  const workerDirectory = `${root}\\.topazlabscli\\worker`;
+  const prep = `$p=${psLiteral(workerDirectory)}; New-Item -ItemType Directory -Force -Path $p | Out-Null; [Console]::Out.Write('{"ok":true}')`;
+  parseRemoteJson(await runPowerShell(target, endpoint, prep));
+  await sftpPut(target, endpoint, workerScript, remote);
+  return remoteAction(target, endpoint, "Install");
+}
+
+async function ensureWorker(target, endpoint) {
+  let status = null;
+  try { status = await remoteAction(target, endpoint, "Status"); }
+  catch { /* Install or repair the worker below. */ }
+  if (!status?.installed || status.worker_version !== WORKER_VERSION) return installWorker(target, endpoint);
+  return status;
+}
+
 async function submitJob(inputPath, requestedTarget, preset = PRESET) {
   const input = path.resolve(inputPath);
   if (!fs.existsSync(input) || !fs.statSync(input).isFile()) throw new CliError("INPUT_NOT_FOUND", `Video not found: ${input}`);
   if (preset !== PRESET) throw new CliError("PRESET_UNSUPPORTED", `Unsupported preset: ${preset}`);
+  let source;
+  try { source = probeMp4Dimensions(input); }
+  catch (error) { throw new CliError("INPUT_METADATA_UNSUPPORTED", `Could not read MP4 video dimensions: ${error.message}`); }
   const { target, endpoint, attempts } = await getConnectedTarget(requestedTarget);
   const id = `${new Date().toISOString().replace(/[-:.TZ]/g, "").slice(0, 14)}-${crypto.randomBytes(3).toString("hex")}`;
   const safeName = path.basename(input).replace(/[^A-Za-z0-9._-]/g, "_");
+  const worker = await ensureWorker(target, endpoint);
   const prepared = await remoteAction(target, endpoint, "Prepare", { id, input_name: safeName });
   await sftpPut(target, endpoint, input, prepared.input_path);
-  const job = await remoteAction(target, endpoint, "Enqueue", { id, input_name: safeName, preset });
-  const runnerPid = startPowerShellDetached(target, endpoint, workerInvocation(remoteRoot(target), "Run"));
-  return { ...job, target: target.name, endpoint: endpoint.name, runner_pid: runnerPid, connection_attempts: attempts };
+  const job = await remoteAction(target, endpoint, "Enqueue", { id, input_name: safeName, preset, source_width: source.width, source_height: source.height });
+  return { ...job, target: target.name, endpoint: endpoint.name, worker_version: worker.worker_version, connection_attempts: attempts };
+}
+
+async function runQueue(requestedTarget, timeoutSeconds = 86400) {
+  const { target, endpoint } = await getConnectedTarget(requestedTarget);
+  return { ...(await remoteAction(target, endpoint, "Run", {}, { timeout: timeoutSeconds })), target: target.name, endpoint: endpoint.name };
 }
 
 async function waitJob(id, requestedTarget, intervalSeconds = 10, timeoutSeconds = 86400) {
@@ -271,13 +299,7 @@ export async function main(rawArgs) {
     const requested = option(args, "--target");
     const { target, endpoint, attempts } = await getConnectedTarget(requested);
     if (action === "install") {
-      const root = remoteRoot(target);
-      const remote = `${root}\\.topazlabscli\\worker\\topazlabs-worker.ps1`;
-      const workerDirectory = `${root}\\.topazlabscli\\worker`;
-      const prep = `$p=${psLiteral(workerDirectory)}; New-Item -ItemType Directory -Force -Path $p | Out-Null; [Console]::Out.Write('{"ok":true}')`;
-      parseRemoteJson(await runPowerShell(target, endpoint, prep));
-      await sftpPut(target, endpoint, workerScript, remote);
-      const installed = await remoteAction(target, endpoint, "Install");
+      const installed = await installWorker(target, endpoint);
       return output({ ...installed, target: target.name, endpoint: endpoint.name, connection_attempts: attempts }, json);
     }
     if (action === "status") return output(await remoteAction(target, endpoint, "Status"), json);
@@ -303,7 +325,12 @@ export async function main(rawArgs) {
       const { target, endpoint } = await getConnectedTarget(requested);
       return output(await remoteAction(target, endpoint, "JobStatus", { id }), json);
     }
-    if (action === "wait") return output(await waitJob(id, requested, Number(option(args, "--interval") || 10), Number(option(args, "--timeout") || 86400)), json);
+    if (action === "wait") {
+      const timeout = Number(option(args, "--timeout") || 86400);
+      const interval = Number(option(args, "--interval") || 10);
+      await runQueue(requested, timeout);
+      return output(await waitJob(id, requested, interval, timeout), json);
+    }
     if (action === "download") return output(await downloadJob(id, requested, option(args, "--output")), json);
     if (action === "cancel") {
       const { target, endpoint } = await getConnectedTarget(requested);
@@ -316,10 +343,12 @@ export async function main(rawArgs) {
     const input = requireValue(args.shift(), "INPUT_REQUIRED", "process requires a video.");
     const destination = option(args, "--output") || defaultOutputPath(input);
     const requested = option(args, "--target");
+    const timeout = Number(option(args, "--timeout") || 86400);
     const submitted = await submitJob(input, requested, option(args, "--preset") || PRESET);
-    const finished = await waitJob(submitted.id, requested, Number(option(args, "--interval") || 10), Number(option(args, "--timeout") || 86400));
+    const runner = await runQueue(requested, timeout);
+    const finished = await waitJob(submitted.id, requested, Number(option(args, "--interval") || 10), timeout);
     if (finished.state !== "completed") throw new CliError("JOB_FAILED", `Job ${submitted.id} ended as ${finished.state}.`, finished);
-    return output({ submitted, finished, downloaded: await downloadJob(submitted.id, requested, destination) }, json);
+    return output({ submitted, runner, finished, downloaded: await downloadJob(submitted.id, requested, destination) }, json);
   }
 
   if (command === "skill") {
@@ -337,7 +366,7 @@ export async function main(rawArgs) {
     const query = await queryLatestVersion(pkg, config);
     if (!query.ok) throw new CliError("UPDATE_FAILED", updateRegistryWarning(query.attempts), { attempts: query.attempts });
     const previousSkills = skillStatus("all");
-    const result = await installLatestPackage(pkg, query.registry);
+    const result = await installLatestPackage(pkg, query.latest, query.registry);
     if (result.code !== 0) throw new CliError("UPDATE_FAILED", result.stderr.trim() || "npm update failed.");
     const skills = [];
     for (const existing of previousSkills.filter((item) => item.installed)) {

package/src/media.mjs

@@ -0,0 +1,47 @@
+import fs from "node:fs";
+
+function readAt(fd, position, length) {
+  const buffer = Buffer.alloc(length);
+  const count = fs.readSync(fd, buffer, 0, length, position);
+  if (count !== length) throw new Error("Unexpected end of media file.");
+  return buffer;
+}
+
+function boxes(fd, start, end) {
+  const items = [];
+  let position = start;
+  while (position + 8 <= end) {
+    const header = readAt(fd, position, 8);
+    let size = header.readUInt32BE(0);
+    const type = header.toString("ascii", 4, 8);
+    let headerSize = 8;
+    if (size === 1) {
+      size = Number(readAt(fd, position + 8, 8).readBigUInt64BE(0));
+      headerSize = 16;
+    } else if (size === 0) size = end - position;
+    if (!Number.isSafeInteger(size) || size < headerSize || position + size > end) break;
+    items.push({ type, start: position, dataStart: position + headerSize, end: position + size });
+    position += size;
+  }
+  return items;
+}
+
+export function probeMp4Dimensions(file) {
+  const fd = fs.openSync(file, "r");
+  try {
+    const size = fs.fstatSync(fd).size;
+    const moov = boxes(fd, 0, size).find((item) => item.type === "moov");
+    if (!moov) throw new Error("MP4 moov box was not found.");
+    for (const trak of boxes(fd, moov.dataStart, moov.end).filter((item) => item.type === "trak")) {
+      const tkhd = boxes(fd, trak.dataStart, trak.end).find((item) => item.type === "tkhd");
+      if (!tkhd || tkhd.end - tkhd.dataStart < 8) continue;
+      const dimensions = readAt(fd, tkhd.end - 8, 8);
+      const width = Math.round(dimensions.readUInt32BE(0) / 65536);
+      const height = Math.round(dimensions.readUInt32BE(4) / 65536);
+      if (width > 0 && height > 0) return { width, height };
+    }
+    throw new Error("A video track with dimensions was not found.");
+  } finally {
+    fs.closeSync(fd);
+  }
+}

package/src/ssh.mjs

@@ -1,6 +1,5 @@
 import fs from "node:fs";
 import path from "node:path";
-import { spawn } from "node:child_process";
 import { run } from "./process.mjs";
 import { resolveExecutable } from "./runtime.mjs";
 import { CliError } from "./errors.mjs";
@@ -20,22 +19,17 @@ export function encodePowerShell(script) {
   return Buffer.from(script, "utf16le").toString("base64");
 }
 
+export function powerShellCommand(script) {
+  const encoded = encodePowerShell(script);
+  return `"&([scriptblock]::Create([Text.Encoding]::Unicode.GetString([Convert]::FromBase64String('${encoded}'))))"`;
+}
+
 export async function runPowerShell(target, endpoint, script, { timeout = 7 } = {}) {
   const args = [...commonArgs(target, endpoint, { timeout }), destination(target, endpoint),
-    "powershell.exe", "-NoLogo", "-NoProfile", "-NonInteractive", "-EncodedCommand", encodePowerShell(script)];
+    "powershell.exe", "-NoLogo", "-NoProfile", "-NonInteractive", "-Command", powerShellCommand(script)];
   return run("ssh", args, { timeoutMs: (timeout + 3) * 1000 });
 }
 
-export function startPowerShellDetached(target, endpoint, script) {
-  const args = [...commonArgs(target, endpoint, { timeout: 10 }), destination(target, endpoint),
-    "powershell.exe", "-NoLogo", "-NoProfile", "-NonInteractive", "-EncodedCommand", encodePowerShell(script)];
-  const executable = resolveExecutable("ssh");
-  const child = spawn(executable.command, [...executable.argsPrefix, ...args], { detached: true, stdio: "ignore", windowsHide: true });
-  child.on("error", () => {});
-  child.unref();
-  return child.pid;
-}
-
 export async function selectEndpoint(target) {
   const attempts = [];
   for (const endpoint of target.endpoints) {

package/src/update.mjs

@@ -116,12 +116,12 @@ function registryFailureMessage(attempts) {
   return `Unable to check npm for updates: ${attempts.map((item) => `${item.registry} (${item.detail})`).join("; ")}`;
 }
 
-export async function installLatestPackage(pkg, registry, dependencies = {}) {
+export async function installLatestPackage(pkg, latest, registry, dependencies = {}) {
   const env = dependencies.env || process.env;
   const execute = dependencies.run || run;
   const temporary = fs.mkdtempSync(path.join(os.tmpdir(), "topazlabscli-update-"));
   try {
-    const packed = await execute("npm", ["pack", `${pkg.name}@latest`, "--json", "--pack-destination", temporary, "--registry", registry], {
+    const packed = await execute("npm", ["pack", `${pkg.name}@${latest}`, "--json", "--pack-destination", temporary, "--registry", registry], {
       env,
       timeoutMs: dependencies.timeoutMs || UPDATE_TIMEOUT_MS
     });
@@ -169,7 +169,7 @@ export async function maybeAutoUpdate(rawArgs, pkg, dependencies = {}) {
   const installedSkills = getSkillStatus("all").filter((item) => item.installed);
   let install;
   try {
-    install = await installLatestPackage(pkg, registry, dependencies);
+    install = await installLatestPackage(pkg, latest, registry, dependencies);
   } catch (error) {
     return { checked: true, warning: `Automatic npm update failed: ${error.message}`, latest, registry };
   }

package/worker/windows/topazlabs-worker.ps1

@@ -8,12 +8,13 @@ param(
 )
 
 $ErrorActionPreference = 'Stop'
-$WorkerVersion = '0.1.1'
+$WorkerVersion = '0.2.0'
 $StateRoot = Join-Path $Root '.topazlabscli'
 $QueueRoot = Join-Path $StateRoot 'queue'
 $JobsRoot = Join-Path $StateRoot 'jobs'
 $WorkerRoot = Join-Path $StateRoot 'worker'
 $ConfigPath = Join-Path $StateRoot 'worker-config.json'
+$RunnerStatePath = Join-Path $StateRoot 'runner.json'
 
 function Write-Json($Value) {
   [Console]::Out.Write(($Value | ConvertTo-Json -Depth 8 -Compress))
@@ -77,6 +78,34 @@ function Get-ModelStatus($Config) {
   }
 }
 
+function Test-JobProcessActive([string]$Id) {
+  $escaped = [Regex]::Escape($Id)
+  return $null -ne (Get-CimInstance Win32_Process -ErrorAction SilentlyContinue | Where-Object {
+    $_.Name -match '^(ffmpeg|ffprobe)\.exe$' -and $_.CommandLine -match $escaped
+  } | Select-Object -First 1)
+}
+
+function Test-RunnerProcessActive {
+  if (-not (Test-Path -LiteralPath $RunnerStatePath)) { return $false }
+  try {
+    $runner = Get-Content -Raw -LiteralPath $RunnerStatePath | ConvertFrom-Json
+    $process = Get-Process -Id ([int]$runner.pid) -ErrorAction SilentlyContinue
+    return ($null -ne $process -and $process.ProcessName -eq 'powershell')
+  } catch { return $false }
+}
+
+function Repair-StaleJobs {
+  if (Test-RunnerProcessActive) { return }
+  Get-ChildItem -LiteralPath $JobsRoot -Directory -ErrorAction SilentlyContinue | ForEach-Object {
+    $statusPath = Join-Path $_.FullName 'status.json'
+    if (-not (Test-Path -LiteralPath $statusPath)) { return }
+    $status = Get-Content -Raw -LiteralPath $statusPath | ConvertFrom-Json
+    if ($status.state -eq 'running' -and -not (Test-JobProcessActive ([string]$status.id))) {
+      Set-JobStatus ([string]$status.id) @{ state = 'failed'; completed_at = (Get-Date).ToUniversalTime().ToString('o'); error_code = 'WORKER_LOST'; error = 'The remote queue runner exited before the job completed. Resubmit the job.' } | Out-Null
+    }
+  }
+}
+
 function Invoke-Job($Job, $Config) {
   $id = [string]$Job.id
   $jobDir = Job-Directory $id
@@ -89,11 +118,9 @@ function Invoke-Job($Job, $Config) {
   if (-not (Test-Path -LiteralPath $Config.ffmpeg)) { throw "Topaz ffmpeg is missing: $($Config.ffmpeg)" }
 
   Set-JobStatus $id @{ state = 'running'; started_at = (Get-Date).ToUniversalTime().ToString('o'); input_path = $inputPath; output_path = $outputPath; output_name = $outputName; preset = $Job.preset } | Out-Null
-  $probeText = & $Config.ffprobe -v error -select_streams v:0 -show_entries stream=width,height -of json -- $inputPath
-  if ($LASTEXITCODE -ne 0) { throw 'ffprobe failed.' }
-  $probe = $probeText | ConvertFrom-Json
-  $width = [int]$probe.streams[0].width
-  $height = [int]$probe.streams[0].height
+  $width = [int]$Job.source_width
+  $height = [int]$Job.source_height
+  if ($width -le 0 -or $height -le 0) { throw 'Source dimensions are missing from the queued job.' }
   if ($width -ge $height) {
     $targetHeight = 1080
     $targetWidth = [int](2 * [Math]::Round((1080.0 * $width / $height) / 2.0))
@@ -140,8 +167,9 @@ switch ($Action) {
     $current = Read-WorkerConfig
     $current.worker_version = $WorkerVersion
     $current | ConvertTo-Json | Set-Content -LiteralPath $ConfigPath -Encoding UTF8
+    Repair-StaleJobs
     $model = Get-ModelStatus $current
-    Write-Json @{ ok = $true; installed = $true; worker_version = $WorkerVersion; root = $Root; model_ready = $model.model_ready }
+    Write-Json @{ ok = $true; installed = $true; worker_version = $WorkerVersion; root = $Root; runner = 'attached-ssh'; model_ready = $model.model_ready }
   }
   'Status' {
     $installed = Test-Path -LiteralPath $ConfigPath
@@ -178,12 +206,17 @@ switch ($Action) {
   'Run' {
     $created = $false
     $mutex = New-Object Threading.Mutex($true, 'Global\TopazLabsCliQueue', [ref]$created)
-    if (-not $created) { exit 0 }
+    if (-not $created) { Write-Json @{ ok = $true; runner = 'attached-ssh'; state = 'already-running' }; exit 0 }
     try {
+      @{ pid = $PID; started_at = (Get-Date).ToUniversalTime().ToString('o') } | ConvertTo-Json | Set-Content -LiteralPath $RunnerStatePath -Encoding UTF8
       $config = Read-WorkerConfig
       while ($true) {
         $next = Get-ChildItem -LiteralPath $QueueRoot -Filter '*.json' | Sort-Object CreationTimeUtc, Name | Select-Object -First 1
-        if ($null -eq $next) { break }
+        if ($null -eq $next) {
+          Start-Sleep -Seconds 2
+          $next = Get-ChildItem -LiteralPath $QueueRoot -Filter '*.json' | Sort-Object CreationTimeUtc, Name | Select-Object -First 1
+          if ($null -eq $next) { break }
+        }
         $job = Get-Content -Raw -LiteralPath $next.FullName | ConvertFrom-Json
         Remove-Item -Force -LiteralPath $next.FullName
         $cancelPath = Join-Path (Job-Directory ([string]$job.id)) 'cancel.requested'
@@ -197,14 +230,17 @@ switch ($Action) {
         }
       }
     } finally {
+      Remove-Item -Force -ErrorAction SilentlyContinue -LiteralPath $RunnerStatePath
       $mutex.ReleaseMutex()
       $mutex.Dispose()
     }
+    Write-Json @{ ok = $true; runner = 'attached-ssh'; state = 'idle' }
   }
   'JobStatus' {
     $payload = Read-Payload
     $path = Status-Path ([string]$payload.id)
     if (-not (Test-Path -LiteralPath $path)) { throw 'Job not found.' }
+    Repair-StaleJobs
     [Console]::Out.Write((Get-Content -Raw -LiteralPath $path).Trim())
   }
   'ListJobs' {