@zswarm/core 0.2.3 → 0.2.5

package/dist/host/crew-windows.js

@@ -0,0 +1,556 @@
+import { execFile } from "node:child_process";
+import { ZellijError } from "../errors.js";
+import { encodePowerShellCommand } from "../zellij/ipc.js";
+/**
+ * Windows half of `zswarm crew`.
+ *
+ * A background Zellij session started with `zellij attach --create-background`
+ * on Windows renders empty pane grids and drops pasted input, because nothing
+ * is attached in a real console. The fix is two Scheduled Tasks under
+ * `\zswarm\` plus a minimized attached-client console window:
+ *
+ *   zswarm-crew-<session>        starts the session (interactive, highest)
+ *   zswarm-crew-<session>-watch  `crew check` every two minutes, so the crew
+ *                                restarts only when the session or its first
+ *                                layout pane is gone, and the client window is
+ *                                reopened when it is gone but the session lives
+ *
+ * This module is pure PowerShell text (unit-tested by text) plus thin async
+ * wrappers. It deliberately mirrors `buildServeTaskScript` in
+ * `ops/serve-install.ts`: same preamble helpers, same base64 UTF-8 round-trip
+ * for the cmd.exe action body, same `-EncodedCommand` invocation. It must not
+ * import `./crew.js`; that module imports this one.
+ */
+/** Scheduled-task folder every crew task lives in. */
+export const CREW_TASK_FOLDER = "\\zswarm\\";
+/** Watchdog cadence, matching the Linux/macOS `crew-<s>-watch` timer. */
+export const CREW_WATCH_MINUTES = 2;
+/** Same shape the `zswarm crew` session validator uses; duplicated to avoid a cycle. */
+const CREW_SESSION = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+/** Overall helper deadline when `timeoutMs` is omitted. Registering two tasks is two calls. */
+const DEFAULT_CREW_TIMEOUT_MS = 20_000;
+function checkSession(session) {
+    const text = session?.trim() ?? "";
+    if (!CREW_SESSION.test(text)) {
+        throw new ZellijError("bad_arg", `invalid session name ${JSON.stringify(session)}`);
+    }
+    return text;
+}
+/** `zswarm-crew-<session>`: task names, and the client window's title marker. */
+export function crewTaskNames(session) {
+    const start = `zswarm-crew-${checkSession(session)}`;
+    return { folder: CREW_TASK_FOLDER, start, watch: `${start}-watch` };
+}
+/** The token that proves a console window is this crew's client: its title and
+ *  the string in its launcher's command line. */
+export function crewClientMarker(session) {
+    return `zswarm-crew-${checkSession(session)}`;
+}
+/**
+ * A task registration is a readable, long-lived artifact, so only the two
+ * variables a crew task cannot discover on its own are serialized — never the
+ * caller's whole environment, which can hold tokens. PATH is deliberately not
+ * one of them: the task runs as the signed-in user and inherits their PATH, and
+ * a host PATH (kilometres of it on Windows) would blow the ~32k Windows
+ * command-line limit once the action is base64-encoded inside this script.
+ */
+const CREW_TASK_ENV_KEYS = ["ZSWARM_BIN", "ZSWARM_STATE_DIR"];
+function crewEnvAssignments(env) {
+    const assignments = [];
+    for (const key of CREW_TASK_ENV_KEYS) {
+        const value = env[key]?.trim();
+        if (!value)
+            continue;
+        if (/[\0\r\n"%]/.test(value)) {
+            throw new ZellijError("bad_arg", `${key} must not contain quotes, newlines, or %`);
+        }
+        assignments.push(`set "${key}=${value}"`);
+    }
+    return assignments;
+}
+/** The cmd.exe action body for a task: `set "K=V"&& ...` then the CLI argv. */
+export function crewTaskCommand(input) {
+    if (input.mode !== "start" && input.mode !== "check") {
+        throw new ZellijError("bad_arg", `unknown crew task mode ${String(input.mode)}`);
+    }
+    const session = checkSession(input.session);
+    for (const [label, value] of [
+        ["execPath", input.launch.execPath],
+        ["scriptPath", input.launch.scriptPath],
+    ]) {
+        if (!value || /[\0\r\n"]/.test(value)) {
+            throw new ZellijError("bad_arg", `crew task ${label} must not contain quotes or newlines`);
+        }
+    }
+    const argv = `"${input.launch.execPath}" "${input.launch.scriptPath}" crew ${input.mode} ${session}`;
+    const assignments = crewEnvAssignments(input.env);
+    const line = assignments.length === 0 ? argv : `${assignments.join("&& ")}&& ${argv}`;
+    // The task action is `cmd.exe /c <line>`, and cmd strips the first and last
+    // quote of a `/c "..."` tail: on a line that starts with the program's own
+    // quote that costs the program its opening quote ("The filename, directory
+    // name, or volume label syntax is incorrect"). Wrapping the whole line in one
+    // more pair makes the stripping harmless — the line still ends with the
+    // unquoted session name, so nothing after it is lost.
+    return `"${line}"`;
+}
+const PS_PREAMBLE = [
+    "$ErrorActionPreference = 'Stop'",
+    "$ProgressPreference = 'SilentlyContinue'",
+    "[Console]::OutputEncoding = New-Object System.Text.UTF8Encoding $false",
+    "function Get-ZswarmIdentity {",
+    "  $id = [System.Security.Principal.WindowsIdentity]::GetCurrent()",
+    "  if (-not $id -or -not $id.User -or [string]::IsNullOrWhiteSpace($id.User.Value)) {",
+    "    throw 'cannot resolve the current Windows SID for the Interactive crew task'",
+    "  }",
+    "  $name = [string]$id.Name",
+    "  if ([string]::IsNullOrWhiteSpace($name)) {",
+    "    throw 'cannot resolve the current Windows account name for the Interactive crew task'",
+    "  }",
+    "  return @{ name = $name; sid = [string]$id.User.Value }",
+    "}",
+    "function Resolve-ZswarmSid($account) {",
+    "  if ($null -eq $account) { return $null }",
+    "  $text = [string]$account",
+    "  if ([string]::IsNullOrWhiteSpace($text)) { return $null }",
+    "  if ($text -match '^S-\\d-') { return $text }",
+    "  try {",
+    "    $nt = New-Object System.Security.Principal.NTAccount($text)",
+    "    $sid = $nt.Translate([System.Security.Principal.SecurityIdentifier])",
+    "    if (-not $sid -or [string]::IsNullOrWhiteSpace($sid.Value)) { return $null }",
+    "    return [string]$sid.Value",
+    "  } catch {",
+    "    return $null",
+    "  }",
+    "}",
+    "function Assert-ZswarmCurrentOwner($task) {",
+    "  $identity = Get-ZswarmIdentity",
+    "  $existingSid = Resolve-ZswarmSid ([string]$task.Principal.UserId)",
+    "  if ([string]::IsNullOrWhiteSpace($existingSid) -or $existingSid -ne $identity.sid) {",
+    "    throw 'a zswarm crew task is owned by a different or unverified Windows account'",
+    "  }",
+    "  return $identity",
+    "}",
+    "function Write-ZswarmJson($obj) {",
+    "  $json = $obj | ConvertTo-Json -Compress -Depth 6",
+    "  [Console]::Out.Write($json)",
+    "}",
+    `function Get-ZswarmTask($name) { Get-ScheduledTask -TaskName $name -TaskPath '${CREW_TASK_FOLDER}' -ErrorAction Stop }`,
+    "function Test-ZswarmMissing($err) {",
+    "  return $err.CategoryInfo.Category -eq 'ObjectNotFound' -or ([string]$err.FullyQualifiedErrorId -match 'ObjectNotFound')",
+    "}",
+].join("\n");
+/** The client scripts do not schedule anything, so they only need JSON output. */
+const PS_CLIENT_PREAMBLE = [
+    "$ErrorActionPreference = 'Stop'",
+    "$ProgressPreference = 'SilentlyContinue'",
+    "[Console]::OutputEncoding = New-Object System.Text.UTF8Encoding $false",
+    "function Write-ZswarmJson($obj) {",
+    "  $json = $obj | ConvertTo-Json -Compress -Depth 6",
+    "  [Console]::Out.Write($json)",
+    "}",
+].join("\n");
+/**
+ * PIDs of our client windows. Image name alone is never identity: the marker
+ * must be in the command line, because every other `powershell.exe` (including
+ * this helper's own `-EncodedCommand` process) has an unrelated command line.
+ */
+function psClientPidLine(marker) {
+    // Match the whole `title <marker> &&` token crewClientCommand writes, not the
+    // bare marker: crew "crew" must never match crew "crew-2"'s window.
+    return `$clientPids = @(Get-CimInstance Win32_Process | Where-Object { ($_.Name -eq 'cmd.exe' -or $_.Name -eq 'powershell.exe') -and $_.CommandLine -and $_.CommandLine.Contains('title ${marker} &&') } | ForEach-Object { [int]$_.ProcessId })`;
+}
+/** Pure PowerShell text, unit-tested by text. */
+export function buildCrewTaskScript(action, params) {
+    const names = crewTaskNames(params.session);
+    if (action === "register") {
+        // Base64 UTF-8 round-trip, exactly like serve's register: neither the
+        // command nor its quoting ever appears in the script text.
+        const startB64 = Buffer.from(params.startCommand ?? "", "utf8").toString("base64");
+        const watchB64 = Buffer.from(params.watchCommand ?? "", "utf8").toString("base64");
+        const interval = Math.max(1, Math.floor(params.intervalMinutes ?? CREW_WATCH_MINUTES));
+        return [
+            PS_PREAMBLE,
+            `$cmd = [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('${startB64}'))`,
+            `$startName = '${names.start}'`,
+            `$watchName = '${names.watch}'`,
+            "$identity = Get-ZswarmIdentity",
+            "foreach ($name in @($startName, $watchName)) {",
+            "  try {",
+            "    $existing = Get-ZswarmTask $name",
+            "    [void](Assert-ZswarmCurrentOwner $existing)",
+            "  } catch {",
+            "    if (-not (Test-ZswarmMissing $_)) { throw }",
+            "  }",
+            "}",
+            "$userId = $identity.name",
+            // Highest, unlike serve's Limited: the crew must own the desktop session
+            // and its Zellij console window.
+            "$principal = New-ScheduledTaskPrincipal -UserId $userId -LogonType Interactive -RunLevel Highest",
+            "$settings = New-ScheduledTaskSettingsSet -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries -StartWhenAvailable",
+            "$startAction = New-ScheduledTaskAction -Execute 'cmd.exe' -Argument ('/c ' + $cmd)",
+            "$startTrigger = New-ScheduledTaskTrigger -AtLogOn -User $userId",
+            `Register-ScheduledTask -TaskName $startName -TaskPath '${CREW_TASK_FOLDER}' -Action $startAction -Principal $principal -Trigger $startTrigger -Settings $settings -Force | Out-Null`,
+            `$cmd = [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('${watchB64}'))`,
+            "$watchAction = New-ScheduledTaskAction -Execute 'cmd.exe' -Argument ('/c ' + $cmd)",
+            // A once-trigger with a long repetition is the supported way to run an
+            // interval task for a user; an AtLogOn trigger would only run once.
+            `$watchTrigger = New-ScheduledTaskTrigger -Once -At (Get-Date) -RepetitionInterval (New-TimeSpan -Minutes ${interval}) -RepetitionDuration (New-TimeSpan -Days 3650)`,
+            `Register-ScheduledTask -TaskName $watchName -TaskPath '${CREW_TASK_FOLDER}' -Action $watchAction -Principal $principal -Trigger $watchTrigger -Settings $settings -Force | Out-Null`,
+            "Write-ZswarmJson @{",
+            "  registered = $true",
+            "  userId = $userId",
+            "  userSid = $identity.sid",
+            "  logonType = 'Interactive'",
+            "  runLevel = 'Highest'",
+            `  folder = '${CREW_TASK_FOLDER}'`,
+            "  startTask = $startName",
+            "  watchTask = $watchName",
+            "}",
+        ].join("\n");
+    }
+    if (action === "inspect") {
+        const marker = crewClientMarker(params.session);
+        return [
+            PS_PREAMBLE,
+            `$startName = '${names.start}'`,
+            `$watchName = '${names.watch}'`,
+            `$marker = '${marker}'`,
+            "$tasks = @{}",
+            "foreach ($pair in @(@{ key = 'start'; name = $startName }, @{ key = 'watch'; name = $watchName })) {",
+            "  try {",
+            "    $task = Get-ZswarmTask $pair.name",
+            "  } catch {",
+            "    if (Test-ZswarmMissing $_) {",
+            "      $tasks[$pair.key] = @{ exists = $false; state = 'missing'; lastResult = $null; lastRunTime = $null; userId = $null; userSid = $null; logonType = $null; runLevel = $null; execute = $null; arguments = $null }",
+            "      continue",
+            "    }",
+            "    throw",
+            "  }",
+            "  $action = @($task.Actions)[0]",
+            `  $info = Get-ScheduledTaskInfo -TaskName $pair.name -TaskPath '${CREW_TASK_FOLDER}'`,
+            "  $lastRun = $null",
+            "  if ($info.LastRunTime -and $info.LastRunTime.Year -gt 1900) { $lastRun = $info.LastRunTime.ToString('o') }",
+            "  $tasks[$pair.key] = @{",
+            "    exists = $true",
+            "    state = [string]$task.State",
+            "    lastResult = $info.LastTaskResult",
+            "    lastRunTime = $lastRun",
+            "    userId = [string]$task.Principal.UserId",
+            "    userSid = (Resolve-ZswarmSid ([string]$task.Principal.UserId))",
+            "    logonType = [string]$task.Principal.LogonType",
+            "    runLevel = [string]$task.Principal.RunLevel",
+            "    execute = [string]$action.Execute",
+            "    arguments = [string]$action.Arguments",
+            "  }",
+            "}",
+            psClientPidLine(marker),
+            "Write-ZswarmJson @{",
+            "  start = $tasks['start']",
+            "  watch = $tasks['watch']",
+            "  clientPresent = ($clientPids.Count -gt 0)",
+            "  clientPids = @($clientPids)",
+            "  clientCount = $clientPids.Count",
+            "}",
+        ].join("\n");
+    }
+    if (action === "start") {
+        return [
+            PS_PREAMBLE,
+            `$startName = '${names.start}'`,
+            `$watchName = '${names.watch}'`,
+            "foreach ($name in @($startName, $watchName)) {",
+            "  try {",
+            "    $task = Get-ZswarmTask $name",
+            "    [void](Assert-ZswarmCurrentOwner $task)",
+            `    Start-ScheduledTask -TaskName $name -TaskPath '${CREW_TASK_FOLDER}'`,
+            "  } catch {",
+            "    if (-not (Test-ZswarmMissing $_)) { throw }",
+            "  }",
+            "}",
+            "Write-ZswarmJson @{ started = $true; startTask = $startName; watchTask = $watchName }",
+        ].join("\n");
+    }
+    return [
+        PS_PREAMBLE,
+        `$startName = '${names.start}'`,
+        `$watchName = '${names.watch}'`,
+        "foreach ($name in @($startName, $watchName)) {",
+        "  try {",
+        "    $task = Get-ZswarmTask $name",
+        "    [void](Assert-ZswarmCurrentOwner $task)",
+        "    try {",
+        `      Stop-ScheduledTask -TaskName $name -TaskPath '${CREW_TASK_FOLDER}'`,
+        "    } catch {",
+        "      if (-not (Test-ZswarmMissing $_)) { throw }",
+        "    }",
+        `    Unregister-ScheduledTask -TaskName $name -TaskPath '${CREW_TASK_FOLDER}' -Confirm:$false`,
+        "  } catch {",
+        "    if (-not (Test-ZswarmMissing $_)) { throw }",
+        "  }",
+        "}",
+        "Write-ZswarmJson @{ cleared = $true; startTask = $startName; watchTask = $watchName }",
+    ].join("\n");
+}
+/**
+ * The command line the client window runs. The marker is both the window title
+ * and the token `ensure`/`close` look for in a process command line; the crew
+ * CLI does the actual `zellij attach --create`, so the window can read the crew
+ * dir (and its env file) itself instead of taking secrets on a command line.
+ */
+export function crewClientCommand(input) {
+    const session = checkSession(input.session);
+    const quote = (value) => `"${value.replace(/"/g, '""')}"`;
+    return `title ${crewClientMarker(session)} && ${quote(input.launch.execPath)} ${quote(input.launch.scriptPath)} crew client ${session}`;
+}
+/** The minimized attached-client window that makes a Windows Zellij session render. */
+export function buildCrewClientScript(action, params) {
+    const session = checkSession(params.session);
+    const marker = crewClientMarker(session);
+    if (action === "ensure") {
+        // `cmd.exe /c <line>`: Start-Process joins -ArgumentList with spaces and
+        // does not re-quote the elements, so cmd.exe gets the whole line as its /c
+        // command with no quoting layers of our own. `title` names the window and
+        // puts the marker in the launcher's command line, which is what later finds
+        // and closes this window. The launcher stays alive while its child runs, so
+        // its process is also the tree `close` kills.
+        const line = params.clientCommand ?? crewClientCommand({
+            session,
+            launch: { execPath: "node", scriptPath: "zswarm" },
+        });
+        return [
+            PS_CLIENT_PREAMBLE,
+            `$marker = '${marker}'`,
+            `$line = '${line.replace(/'/g, "''")}'`,
+            psClientPidLine(marker),
+            "if ($clientPids.Count -gt 0) {",
+            "  Write-ZswarmJson @{ opened = $false; present = $true; pid = $clientPids[0]; title = $marker; count = $clientPids.Count }",
+            "  exit 0",
+            "}",
+            "$proc = Start-Process -FilePath 'cmd.exe' -WindowStyle Minimized -PassThru -ArgumentList @('/c', $line)",
+            "Write-ZswarmJson @{ opened = $true; present = $true; pid = [int]$proc.Id; title = $marker; count = 1 }",
+        ].join("\n");
+    }
+    return [
+        PS_CLIENT_PREAMBLE,
+        `$marker = '${marker}'`,
+        psClientPidLine(marker),
+        "$closed = @()",
+        "foreach ($clientPid in $clientPids) {",
+        "  # The window is the launcher's console, so the tree has to go with it:",
+        "  # /T reaches the attached `zellij` client that shares that console.",
+        "  & taskkill.exe /PID $clientPid /T /F 2>$null | Out-Null",
+        "  $closed += $clientPid",
+        "}",
+        "Write-ZswarmJson @{ closed = @($closed); count = $closed.Count }",
+    ].join("\n");
+}
+/** Last line that parses as a JSON object, else the first; null when none does. */
+export function parseCrewJson(stdout) {
+    let found = null;
+    for (const line of stdout.split(/\r?\n/)) {
+        const text = line.trim();
+        if (!text.startsWith("{") || !text.endsWith("}"))
+            continue;
+        let value;
+        try {
+            value = JSON.parse(text);
+        }
+        catch {
+            continue;
+        }
+        if (value && typeof value === "object" && !Array.isArray(value)) {
+            found = value;
+        }
+    }
+    if (found)
+        return found;
+    // A single pretty-printed object spans lines and never parses per line.
+    const text = stdout.trim();
+    if (!text.startsWith("{") || !text.endsWith("}"))
+        return null;
+    try {
+        const value = JSON.parse(text);
+        if (value && typeof value === "object" && !Array.isArray(value)) {
+            return value;
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+/**
+ * `powershell -EncodedCommand` costs two bytes of UTF-16 per script character,
+ * then base64 inflates that by 4/3; Windows refuses a command line over ~32k
+ * characters with a bare `ENAMETOOLONG`, so a script that cannot fit is
+ * reported as itself instead of as a spawn failure.
+ */
+const MAX_ENCODED_SCRIPT = 30_000;
+/** Powershell runner used in production; injected in tests. Never throws. */
+export const defaultPowerShellExec = (script, options) => {
+    const timeout = Math.floor(options.timeoutMs);
+    if (timeout <= 0) {
+        return Promise.resolve({ code: 1, stdout: "", stderr: "no remaining budget" });
+    }
+    const encoded = encodePowerShellCommand(script);
+    if (encoded.length > MAX_ENCODED_SCRIPT) {
+        return Promise.resolve({
+            code: 1,
+            stdout: "",
+            stderr: `the generated PowerShell is ${encoded.length} characters, too long for a Windows command line`,
+        });
+    }
+    return new Promise((resolve) => {
+        execFile("powershell.exe", [
+            "-NoProfile",
+            "-ExecutionPolicy",
+            "Bypass",
+            "-EncodedCommand",
+            encoded,
+        ], {
+            windowsHide: true,
+            timeout,
+            signal: options.signal,
+            maxBuffer: 1024 * 1024,
+        }, (error, stdout, stderr) => {
+            if (error) {
+                const err = error;
+                const text = String(stderr ?? "").trim();
+                resolve({ code: 1, stdout: String(stdout ?? ""), stderr: text || err.message });
+                return;
+            }
+            resolve({ code: 0, stdout: String(stdout ?? ""), stderr: String(stderr ?? "") });
+        });
+    });
+};
+function crewTimeout(timeoutMs) {
+    return Math.max(1, Math.floor(timeoutMs ?? DEFAULT_CREW_TIMEOUT_MS));
+}
+async function crewRun(run, script, timeoutMs, signal) {
+    const result = await run(script, { timeoutMs, signal });
+    if (result.code !== 0) {
+        const detail = (result.stderr || result.stdout).trim().slice(0, 300);
+        throw new ZellijError("failed", detail || "zswarm crew helper failed");
+    }
+    const parsed = parseCrewJson(result.stdout);
+    if (!parsed)
+        throw new ZellijError("failed", "zswarm crew helper returned no JSON");
+    return parsed;
+}
+function asTaskState(name, task, raw) {
+    const info = raw && typeof raw === "object" && !Array.isArray(raw) ? raw : {};
+    const exists = info.exists === true;
+    return {
+        name,
+        task,
+        path: `${CREW_TASK_FOLDER}${task}`,
+        state: exists ? String(info.state ?? "Unknown") : "missing",
+        active: exists,
+        lastResult: typeof info.lastResult === "number" ? info.lastResult : null,
+        lastRun: typeof info.lastRunTime === "string" && info.lastRunTime ? info.lastRunTime : null,
+    };
+}
+function clientPids(value) {
+    // A one-element `@(...)` can serialize as a scalar, not an array.
+    if (typeof value === "number" && Number.isFinite(value))
+        return [value];
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((item) => typeof item === "number" && Number.isFinite(item));
+}
+export async function inspectCrewTasks(input) {
+    const session = checkSession(input.session);
+    const script = buildCrewTaskScript("inspect", { session });
+    const data = await crewRun(input.runPowerShell, script, crewTimeout(input.timeoutMs), input.signal);
+    const names = crewTaskNames(session);
+    const pids = clientPids(data.clientPids);
+    const count = typeof data.clientCount === "number" && Number.isFinite(data.clientCount)
+        ? data.clientCount
+        : pids.length;
+    return {
+        tasks: [
+            asTaskState("start", names.start, data.start),
+            asTaskState("watch", names.watch, data.watch),
+        ],
+        client: {
+            present: data.clientPresent === true,
+            pid: pids.length > 0 ? pids[0] : null,
+            count,
+        },
+    };
+}
+export async function installCrewTasks(input) {
+    const session = checkSession(input.session);
+    const names = crewTaskNames(session);
+    const intervalMinutes = Math.max(1, Math.floor(input.intervalMinutes ?? CREW_WATCH_MINUTES));
+    const timeoutMs = crewTimeout(input.timeoutMs);
+    const script = buildCrewTaskScript("register", {
+        session,
+        startCommand: input.startCommand,
+        watchCommand: input.watchCommand,
+        intervalMinutes,
+    });
+    await crewRun(input.runPowerShell, script, timeoutMs, input.signal);
+    // Start both now, the way the Linux oneshot unit is started on install: the
+    // start task builds the session and opens the client window; the watchdog's
+    // first run is a no-op while that session is healthy.
+    await crewRun(input.runPowerShell, buildCrewTaskScript("start", { session }), timeoutMs, input.signal);
+    const inspected = await inspectCrewTasks({
+        session,
+        runPowerShell: input.runPowerShell,
+        timeoutMs,
+        signal: input.signal,
+    });
+    return {
+        lines: [
+            `${names.folder}${names.start} registered and started`,
+            `${names.folder}${names.watch} registered and started`,
+        ],
+        notes: [
+            "A Windows scheduled task runs in the signed-in interactive desktop session, so the crew needs a logged-in user: a logoff ends the client window and the session it renders.",
+            `The start task builds the session and keeps an attached client window titled ${names.start}; the watchdog runs crew check every ${intervalMinutes} minute(s) and reopens that window when it is gone.`,
+        ],
+        tasks: inspected.tasks,
+        client: inspected.client,
+    };
+}
+export async function removeCrewTasks(input) {
+    const session = checkSession(input.session);
+    const names = crewTaskNames(session);
+    const timeoutMs = crewTimeout(input.timeoutMs);
+    const script = buildCrewTaskScript("unregister", { session });
+    await crewRun(input.runPowerShell, script, timeoutMs, input.signal);
+    const inspected = await inspectCrewTasks({
+        session,
+        runPowerShell: input.runPowerShell,
+        timeoutMs,
+        signal: input.signal,
+    });
+    return {
+        lines: [`${names.folder}${names.start} removed`, `${names.folder}${names.watch} removed`],
+        tasks: inspected.tasks,
+    };
+}
+export async function ensureCrewClient(input) {
+    const session = checkSession(input.session);
+    const title = crewClientMarker(session);
+    const script = buildCrewClientScript("ensure", { session, clientCommand: input.clientCommand });
+    const data = await crewRun(input.runPowerShell, script, crewTimeout(input.timeoutMs), input.signal);
+    const pid = typeof data.pid === "number" && Number.isFinite(data.pid) ? data.pid : null;
+    const count = typeof data.count === "number" && Number.isFinite(data.count) ? data.count : pid === null ? 0 : 1;
+    return {
+        opened: data.opened === true,
+        pid,
+        title: typeof data.title === "string" && data.title ? data.title : title,
+        present: data.present === true,
+        count,
+    };
+}
+export async function closeCrewClient(input) {
+    const session = checkSession(input.session);
+    const script = buildCrewClientScript("close", { session });
+    const data = await crewRun(input.runPowerShell, script, crewTimeout(input.timeoutMs), input.signal);
+    const closed = clientPids(data.closed);
+    const count = typeof data.count === "number" && Number.isFinite(data.count) ? data.count : closed.length;
+    return { closed, count };
+}

package/dist/host/crew.d.ts

@@ -1,3 +1,4 @@
+import { type PowerShellExec } from "./crew-windows.js";
 import { type Runner, type ServiceAccount, type ServiceHost, type ServiceSpec } from "./services.js";
 export declare const CREW_WATCH_SEC = 120;
 export type CrewDeps = {
@@ -23,6 +24,24 @@ export type CrewDeps = {
     log?: (line: string) => void;
     /** Restarts a systemd user unit (the watchdog on Linux); injected in tests. */
     restartUnit?: (unit: string) => number;
+    /** The account the crew runs for; injected in tests (a win32 account cannot run real tasks in CI). */
+    account?: ServiceAccount;
+    /** Runs the crew's scheduled-task PowerShell on Windows; injected in tests. */
+    runPowerShell?: PowerShellExec;
+    /** The CLI launcher the client window runs; defaults to this process's. */
+    launch?: {
+        execPath: string;
+        scriptPath: string;
+    };
+    /** The attached client window on Windows; injected in tests. */
+    client?: {
+        ensure: (session: string) => Promise<{
+            opened: boolean;
+            pid: number | null;
+            count: number;
+        }>;
+        close: (session: string) => Promise<number[]>;
+    };
 };
 /** Env the Linux watchdog unit carries: restart this unit instead of starting Zellij itself. */
 export declare const CREW_UNIT_ENV = "ZSWARM_CREW_UNIT";
@@ -34,6 +53,13 @@ export declare function firstLayoutPane(kdl: string): string | undefined;
 export declare function parseEnvFile(text: string): Record<string, string>;
 /** Start the session from its layout and prove the first pane exists; up to three tries. */
 export declare function crewStart(session: string, deps?: CrewDeps): Promise<number>;
+/**
+ * `crew client`: what the minimized console window runs. It reads the crew dir
+ * (so an env file's variables reach Zellij without being written into a task or
+ * a command line) and attaches with `--create`, which is what makes a Windows
+ * session render — a background-only session leaves pane grids empty.
+ */
+export declare function crewClient(session: string, deps?: CrewDeps): number;
 /** Watchdog: restart the session if its server died or its first pane is gone. */
 export declare function crewCheck(session: string, deps?: CrewDeps): Promise<number>;
 export type CrewUpInput = {
@@ -54,6 +80,8 @@ export type CrewUpInput = {
     /** Copies crew files into the crew dir; injected in tests. */
     copy?: (account: ServiceAccount, from: string, to: string, secret: boolean) => void;
     writeMeta?: (account: ServiceAccount, path: string, text: string) => void;
+    /** Runs the crew's scheduled-task PowerShell on Windows; injected in tests. */
+    runPowerShell?: PowerShellExec;
 };
 export declare function crewServiceSpecs(input: {
     account: ServiceAccount;
@@ -64,7 +92,7 @@ export declare function crewServiceSpecs(input: {
     };
     env: NodeJS.ProcessEnv;
 }): ServiceSpec[];
-export declare function crewUp(input: CrewUpInput): Record<string, unknown>;
+export declare function crewUp(input: CrewUpInput): Promise<Record<string, unknown>>;
 export declare function crewStatus(input: {
     session: string;
     runAs?: string;
@@ -72,6 +100,7 @@ export declare function crewStatus(input: {
     account?: ServiceAccount;
     run?: Runner;
     deps?: CrewDeps;
+    runPowerShell?: PowerShellExec;
 }): Promise<Record<string, unknown>>;
 export declare function crewDown(input: {
     session: string;
@@ -80,4 +109,5 @@ export declare function crewDown(input: {
     account?: ServiceAccount;
     run?: Runner;
     fs?: ServiceHost["fs"];
-}): Record<string, unknown>;
+    runPowerShell?: PowerShellExec;
+}): Promise<Record<string, unknown>>;