@amalgm/shell 0.1.162 → 0.1.163

package/dist/service/systemd.js

@@ -0,0 +1,94 @@
+import { stopKeepalive } from "./control.js";
+/**
+ * Linux: a systemd user unit. The user manager starts it at first login and
+ * stops it at last logout; `Restart=on-failure` with no start limit means a
+ * dying keepalive is always brought back, never parked as `failed`.
+ */
+import { existsSync, rmSync } from "node:fs";
+import { dirname } from "node:path";
+import { systemdQuote, systemdUnavailableOutput, systemdUnitPath } from "@amalgm/core/supervision";
+import { atomicWrite, ensureUserDir } from "../filesystem.js";
+import { keepaliveCommand, osCommand, serviceEnvironment } from "./adapter.js";
+const RESTART_SEC = 5;
+/** SIGTERM to the keepalive, SIGKILL to the whole group after this. */
+const TIMEOUT_STOP_SEC = 30;
+export function renderSystemdUnit(input) {
+    const env = Object.entries(input.environment)
+        .map(([key, value]) => `Environment=${systemdQuote(`${key}=${value}`)}`)
+        .join("\n");
+    return `[Unit]
+Description=Amalgm always-on runtime
+StartLimitIntervalSec=0
+
+[Service]
+Type=exec
+WorkingDirectory=${systemdQuote(input.workingDirectory)}
+${env}
+ExecStart=${input.command.map(systemdQuote).join(" ")}
+Restart=on-failure
+RestartSec=${RESTART_SEC}
+KillMode=mixed
+TimeoutStopSec=${TIMEOUT_STOP_SEC}
+
+[Install]
+WantedBy=default.target
+`;
+}
+/** Does this login have a user manager to talk to? Containers and bare SSH often do not. */
+export function userSystemdAvailable() {
+    const probe = osCommand("systemctl", ["--user", "show-environment"], { tolerate: true });
+    return probe.ok && !systemdUnavailableOutput(`${probe.stdout}\n${probe.stderr}`);
+}
+function unit(identity) {
+    return systemdUnitPath(identity.home, identity.label);
+}
+function systemctl(args, tolerate = false) {
+    return osCommand("systemctl", ["--user", ...args], { tolerate });
+}
+export const systemdOwner = {
+    backend: "systemd",
+    files: (identity) => ({ unit: unit(identity) }),
+    async install(identity, launcher, keepaliveArgs) {
+        await stopKeepalive(identity);
+        const file = unit(identity);
+        ensureUserDir(dirname(file));
+        atomicWrite(file, renderSystemdUnit({
+            command: keepaliveCommand(launcher, keepaliveArgs),
+            environment: serviceEnvironment(identity),
+            workingDirectory: identity.home,
+        }), 0o644);
+        systemctl(["daemon-reload"]);
+        // A selected data home need not be in the OS account's unit search path.
+        // Enabling the absolute file also links it into that account's user manager.
+        systemctl(["enable", file]);
+        systemctl(["restart", identity.label]);
+    },
+    start(identity) {
+        systemctl(["start", identity.label]);
+    },
+    async stop(identity) {
+        await stopKeepalive(identity);
+        systemctl(["stop", identity.label], true);
+    },
+    status(identity) {
+        const registered = existsSync(unit(identity));
+        const show = systemctl(["show", identity.label, "-p", "LoadState", "-p", "ActiveState", "-p", "SubState", "-p", "MainPID"], true);
+        const property = (name) => new RegExp(`^${name}=(.*)$`, "m").exec(show.stdout)?.[1]?.trim() ?? null;
+        const pid = Number(property("MainPID") ?? 0);
+        const active = property("ActiveState");
+        return {
+            registered,
+            loaded: show.ok ? property("LoadState") === "loaded" : null,
+            state: active && property("SubState") ? `${active}/${property("SubState")}` : active,
+            pid: pid > 0 ? pid : null,
+        };
+    },
+    async uninstall(identity) {
+        await stopKeepalive(identity);
+        systemctl(["disable", "--now", identity.label], true);
+        rmSync(unit(identity), { force: true });
+        systemctl(["daemon-reload"], true);
+        systemctl(["reset-failed", identity.label], true);
+    },
+};
+//# sourceMappingURL=systemd.js.map

package/dist/service/systemd.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"systemd.js","sourceRoot":"","sources":["../../src/service/systemd.ts"],"names":[],"mappings":"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"}

package/dist/service/windows-task.d.ts

@@ -0,0 +1,16 @@
+export declare function encodePowerShell(source: string): string;
+/** Microsoft command-line quoting, applied directly to ProcessStartInfo.
+ * No cmd.exe, environment expansion, or shell interpretation is involved. */
+export declare function quoteWindowsArgument(value: string): string;
+export declare function powershellExecutable(env?: NodeJS.ProcessEnv): string;
+/** The scheduler must observe the controller's real lifetime and exit code.
+ * A hidden, waiting host wrapper does not make any recovery decisions. */
+export declare function windowsControllerAction(command: readonly string[], workingDirectory: string): string;
+export type WindowsTaskOperation = 'install' | 'start' | 'disable' | 'stop' | 'status' | 'uninstall';
+/** All interpolated input is encoded JSON data. Task Scheduler runs under the
+ * current account's interactive token and never stores an account password. */
+export declare function windowsTaskOperation(input: {
+    readonly operation: WindowsTaskOperation;
+    readonly name: string;
+    readonly action?: string;
+}): string;

package/dist/service/windows-task.js

@@ -0,0 +1,82 @@
+import { win32 } from 'node:path';
+import { CHILD_RESTART_POLICY } from '@amalgm/core/supervision';
+export function encodePowerShell(source) {
+    return Buffer.from(source, 'utf16le').toString('base64');
+}
+/** Microsoft command-line quoting, applied directly to ProcessStartInfo.
+ * No cmd.exe, environment expansion, or shell interpretation is involved. */
+export function quoteWindowsArgument(value) {
+    if (value.includes('\0'))
+        throw new Error('A process argument cannot contain NUL.');
+    return `"${value.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\+)$/, '$1$1')}"`;
+}
+export function powershellExecutable(env = process.env) {
+    return win32.join(env.SystemRoot || 'C:\\Windows', 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe');
+}
+function jsonExpression(value) {
+    const encoded = Buffer.from(JSON.stringify(value), 'utf8').toString('base64');
+    return `ConvertFrom-Json ([Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('${encoded}')))`;
+}
+/** The scheduler must observe the controller's real lifetime and exit code.
+ * A hidden, waiting host wrapper does not make any recovery decisions. */
+export function windowsControllerAction(command, workingDirectory) {
+    if (!command.length || !command[0])
+        throw new Error('The controller needs an executable.');
+    return encodePowerShell(`
+$ErrorActionPreference = 'Stop'
+$launch = ${jsonExpression({ executable: command[0], arguments: command.slice(1).map(quoteWindowsArgument).join(' '), workingDirectory })}
+$start = New-Object System.Diagnostics.ProcessStartInfo
+$start.FileName = $launch.executable
+$start.Arguments = $launch.arguments
+$start.WorkingDirectory = $launch.workingDirectory
+$start.UseShellExecute = $false
+$start.CreateNoWindow = $true
+$runtimeProcess = [System.Diagnostics.Process]::Start($start)
+try {
+  $runtimeProcess.WaitForExit()
+  $result = $runtimeProcess.ExitCode
+} finally { $runtimeProcess.Dispose() }
+exit $result
+`);
+}
+/** All interpolated input is encoded JSON data. Task Scheduler runs under the
+ * current account's interactive token and never stores an account password. */
+export function windowsTaskOperation(input) {
+    const request = { ...input, executable: powershellExecutable(),
+        restartCount: CHILD_RESTART_POLICY.maxRestarts,
+        // Task Scheduler's supported minimum is one minute.
+        // https://learn.microsoft.com/windows/win32/taskschd/taskschedulerschema-restarttype-complextype
+        restartIntervalMs: Math.max(60_000, CHILD_RESTART_POLICY.initialDelayMs) };
+    return encodePowerShell(`
+$ErrorActionPreference = 'Stop'
+$request = ${jsonExpression(request)}
+$task = Get-ScheduledTask -TaskPath '\\' | Where-Object { $_.TaskName -ceq $request.name } | Select-Object -First 1
+switch ($request.operation) {
+  'install' {
+    $sid = [Security.Principal.WindowsIdentity]::GetCurrent().User.Value
+    $principal = New-ScheduledTaskPrincipal -UserId $sid -LogonType Interactive -RunLevel Limited
+    $trigger = New-ScheduledTaskTrigger -AtLogOn -User $sid
+    $action = New-ScheduledTaskAction -Execute $request.executable -Argument ('-NoProfile -NonInteractive -WindowStyle Hidden -EncodedCommand ' + $request.action)
+    $settings = New-ScheduledTaskSettingsSet -MultipleInstances IgnoreNew -StartWhenAvailable -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries -ExecutionTimeLimit ([TimeSpan]::Zero) -RestartCount $request.restartCount -RestartInterval ([TimeSpan]::FromMilliseconds($request.restartIntervalMs)) -Hidden
+    Register-ScheduledTask -TaskPath '\\' -TaskName $request.name -Action $action -Trigger $trigger -Principal $principal -Settings $settings -Force | Out-Null
+    Start-ScheduledTask -TaskPath '\\' -TaskName $request.name
+  }
+  'start' {
+    if (-not $task) { throw 'The Amalgm runtime task is not registered.' }
+    Enable-ScheduledTask -InputObject $task | Out-Null
+    Start-ScheduledTask -InputObject $task
+  }
+  'disable' { if ($task) { Disable-ScheduledTask -InputObject $task | Out-Null } }
+  'stop' { if ($task) { Stop-ScheduledTask -InputObject $task } }
+  'uninstall' { if ($task) { Unregister-ScheduledTask -InputObject $task -Confirm:$false } }
+  'status' {
+    if ($task) {
+      $info = Get-ScheduledTaskInfo -InputObject $task
+      @{ registered = $true; state = [string]$task.State; lastResult = $info.LastTaskResult } | ConvertTo-Json -Compress
+    } else { @{ registered = $false } | ConvertTo-Json -Compress }
+  }
+  default { throw 'Unknown runtime task operation.' }
+}
+`);
+}
+//# sourceMappingURL=windows-task.js.map

package/dist/service/windows-task.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"windows-task.js","sourceRoot":"","sources":["../../src/service/windows-task.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAEhE,MAAM,UAAU,gBAAgB,CAAC,MAAc;IAC7C,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AAC3D,CAAC;AAED;6EAC6E;AAC7E,MAAM,UAAU,oBAAoB,CAAC,KAAa;IAChD,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;IACpF,OAAO,IAAI,KAAK,CAAC,OAAO,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,CAAC,GAAG,CAAC;AAC9E,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,MAAyB,OAAO,CAAC,GAAG;IACvE,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,UAAU,IAAI,aAAa,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,EAAE,gBAAgB,CAAC,CAAC;AAChH,CAAC;AAED,SAAS,cAAc,CAAC,KAAc;IACpC,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAC9E,OAAO,kFAAkF,OAAO,MAAM,CAAC;AACzG,CAAC;AAED;0EAC0E;AAC1E,MAAM,UAAU,uBAAuB,CAAC,OAA0B,EAAE,gBAAwB;IAC1F,IAAI,CAAC,OAAO,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC;IAC3F,OAAO,gBAAgB,CAAC;;YAEd,cAAc,CAAC,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,gBAAgB,EAAE,CAAC;;;;;;;;;;;;;CAaxI,CAAC,CAAC;AACH,CAAC;AAID;+EAC+E;AAC/E,MAAM,UAAU,oBAAoB,CAAC,KAIpC;IACC,MAAM,OAAO,GAAG,EAAE,GAAG,KAAK,EAAE,UAAU,EAAE,oBAAoB,EAAE;QAC5D,YAAY,EAAE,oBAAoB,CAAC,WAAW;QAC9C,oDAAoD;QACpD,iGAAiG;QACjG,iBAAiB,EAAE,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,oBAAoB,CAAC,cAAc,CAAC,EAAE,CAAC;IAC7E,OAAO,gBAAgB,CAAC;;aAEb,cAAc,CAAC,OAAO,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4BnC,CAAC,CAAC;AACH,CAAC"}

package/dist/service/windows.d.ts

@@ -0,0 +1,2 @@
+import { type ServiceOwner } from './adapter.js';
+export declare const windowsOwner: ServiceOwner;

package/dist/service/windows.js

@@ -0,0 +1,65 @@
+/** Windows Task Scheduler owns a hidden controller in the current account's
+ * logged-in lifetime, including Core's bounded automatic crash recovery. */
+import { existsSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { windowsStartupScriptPath } from '@amalgm/core/supervision';
+import { atomicJson } from '../filesystem.js';
+import { keepaliveStatus, stopKeepalive } from './control.js';
+import { keepaliveCommand, osCommand } from './adapter.js';
+import { powershellExecutable, windowsControllerAction, windowsTaskOperation } from './windows-task.js';
+const definition = (identity) => join(identity.serviceDir, 'windows-task.json');
+const task = (identity, operation, action) => osCommand(powershellExecutable(), ['-NoProfile', '-NonInteractive', '-EncodedCommand', windowsTaskOperation({
+        operation, name: identity.label, ...(action ? { action } : {}),
+    })]);
+async function waitForController(identity) {
+    const deadline = Date.now() + 15_000;
+    while (Date.now() < deadline) {
+        if ((await keepaliveStatus(identity))?.alive)
+            return;
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    throw new Error(`The Windows task for ${identity.label} did not report an authenticated controller; see ${identity.serviceDir}`);
+}
+export const windowsOwner = {
+    backend: 'windows',
+    files: (identity) => ({ task: definition(identity) }),
+    async install(identity, launcher, keepaliveArgs) {
+        await stopKeepalive(identity);
+        const action = windowsControllerAction(keepaliveCommand(launcher, keepaliveArgs), identity.home);
+        task(identity, 'install', action);
+        await waitForController(identity);
+        atomicJson(definition(identity), { name: identity.label, action, binding: identity.binding });
+        // Retire only the known previous registration after the new owner is live.
+        rmSync(windowsStartupScriptPath(identity.labelScope, { home: identity.home, appData: process.env.APPDATA }), { force: true });
+    },
+    async start(identity) {
+        if ((await keepaliveStatus(identity))?.alive)
+            return;
+        task(identity, 'start');
+        await waitForController(identity);
+    },
+    async stop(identity) {
+        task(identity, 'disable');
+        await stopKeepalive(identity);
+        task(identity, 'stop');
+    },
+    async status(identity) {
+        const native = JSON.parse(task(identity, 'status').stdout);
+        const controller = await keepaliveStatus(identity);
+        return {
+            registered: native.registered && existsSync(definition(identity)), loaded: native.registered,
+            state: controller?.alive ? 'running' : native.state?.toLowerCase() || 'not registered',
+            pid: controller?.alive ? controller.pid : null,
+            ...(native.lastResult ? { detail: `Task Scheduler result: ${native.lastResult}` } : {}),
+        };
+    },
+    async uninstall(identity) {
+        task(identity, 'disable');
+        await stopKeepalive(identity);
+        task(identity, 'stop');
+        task(identity, 'uninstall');
+        rmSync(definition(identity), { force: true });
+        rmSync(windowsStartupScriptPath(identity.labelScope, { home: identity.home, appData: process.env.APPDATA }), { force: true });
+    },
+};
+//# sourceMappingURL=windows.js.map

package/dist/service/windows.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"windows.js","sourceRoot":"","sources":["../../src/service/windows.ts"],"names":[],"mappings":"AAAA;4EAC4E;AAC5E,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAC7C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE9D,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAqB,MAAM,cAAc,CAAC;AAC9E,OAAO,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,oBAAoB,EAA6B,MAAM,mBAAmB,CAAC;AAEnI,MAAM,UAAU,GAAG,CAAC,QAAyB,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,UAAU,EAAE,mBAAmB,CAAC,CAAC;AACjG,MAAM,IAAI,GAAG,CAAC,QAAyB,EAAE,SAA+B,EAAE,MAAe,EAAE,EAAE,CAAC,SAAS,CACrG,oBAAoB,EAAE,EAAE,CAAC,YAAY,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,oBAAoB,CAAC;QAChG,SAAS,EAAE,IAAI,EAAE,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC/D,CAAC,CAAC,CACJ,CAAC;AAEF,KAAK,UAAU,iBAAiB,CAAC,QAAyB;IACxD,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,MAAM,CAAC;IACrC,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,EAAE,CAAC;QAC7B,IAAI,CAAC,MAAM,eAAe,CAAC,QAAQ,CAAC,CAAC,EAAE,KAAK;YAAE,OAAO;QACrD,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC;IAC3D,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,wBAAwB,QAAQ,CAAC,KAAK,oDAAoD,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC;AACnI,CAAC;AAED,MAAM,CAAC,MAAM,YAAY,GAAiB;IACxC,OAAO,EAAE,SAAS;IAClB,KAAK,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;IACrD,KAAK,CAAC,OAAO,CAAC,QAAQ,EAAE,QAAQ,EAAE,aAAa;QAC7C,MAAM,aAAa,CAAC,QAAQ,CAAC,CAAC;QAC9B,MAAM,MAAM,GAAG,uBAAuB,CAAC,gBAAgB,CAAC,QAAQ,EAAE,aAAa,CAAC,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;QACjG,IAAI,CAAC,QAAQ,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;QAClC,MAAM,iBAAiB,CAAC,QAAQ,CAAC,CAAC;QAClC,UAAU,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,EAAE,IAAI,EAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;QAC9F,2EAA2E;QAC3E,MAAM,CAAC,wBAAwB,CAAC,QAAQ,CAAC,UAAU,EAAE,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAChI,CAAC;IACD,KAAK,CAAC,KAAK,CAAC,QAAQ;QAClB,IAAI,CAAC,MAAM,eAAe,CAAC,QAAQ,CAAC,CAAC,EAAE,KAAK;YAAE,OAAO;QACrD,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QACxB,MAAM,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IACpC,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,QAAQ;QACjB,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;QAC1B,MAAM,aAAa,CAAC,QAAQ,CAAC,CAAC;QAC9B,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IACzB,CAAC;IACD,KAAK,CAAC,MAAM,CAAC,QAAQ;QACnB,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,MAAM,CAAiE,CAAC;QAC3H,MAAM,UAAU,GAAG,MAAM,eAAe,CAAC,QAAQ,CAAC,CAAC;QACnD,OAAO;YACL,UAAU,EAAE,MAAM,CAAC,UAAU,IAAI,UAAU,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,UAAU;YAC5F,KAAK,EAAE,UAAU,EAAE,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,gBAAgB;YACtF,GAAG,EAAE,UAAU,EAAE,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI;YAC9C,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,0BAA0B,MAAM,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACxF,CAAC;IACJ,CAAC;IACD,KAAK,CAAC,SAAS,CAAC,QAAQ;QACtB,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;QAC1B,MAAM,aAAa,CAAC,QAAQ,CAAC,CAAC;QAC9B,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QACvB,IAAI,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;QAC5B,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAC9C,MAAM,CAAC,wBAAwB,CAAC,QAAQ,CAAC,UAAU,EAAE,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAChI,CAAC;CACF,CAAC"}

package/dist/user-ground-host.d.ts

@@ -68,6 +68,8 @@ export interface UserGroundHostOptions {
     readonly tunnelUrl: string;
     readonly tunnelToken: string;
     readonly runtimeVersion: string;
+    /** Installation-wide host admission, before any writer touches ground. */
+    readonly reserveWritableRoot?: (path: string) => void;
     readonly declaration?: UserHomeDeclaration;
     readonly now?: () => Date;
     /** Product diagnostics consume this; Core's `/healthz` remains liveness-only. */
@@ -256,6 +258,7 @@ export declare class UserGroundHost {
      * stay one read each. A lone artifact is a set of one. */
     private downloadContentSet;
     private downloadContent;
+    private reserveGroundRoots;
     private ensureWatchers;
     private scheduleRescan;
     /** A finite cold command may suppress Detect while it owns publication, but

package/dist/user-ground-host.js

@@ -171,6 +171,7 @@ export class UserGroundHost {
             converge: async (identity) => {
                 this.converged = false;
                 this.activeIdentity = normalizedIdentity(identity);
+                this.reserveGroundRoots(this.activeIdentity);
                 const local = this.localPort(this.activeIdentity);
                 const result = await convergeUserGround(this.activeIdentity, {
                     sha256Hex,
@@ -312,6 +313,7 @@ export class UserGroundHost {
         const register = createFilesRegisterPorts({
             userRoot,
             deviceId: identity.deviceId,
+            reserveWritableRoot: this.options.reserveWritableRoot,
             onReferenceDeclared: () => this.scheduleRescan(),
             findKnownWorkspaceId: ({ absolutePath, deviceNumber, inode }) => findKnownEntityId(this.databasePath(identity), absolutePath, deviceNumber, inode),
         });
@@ -363,6 +365,7 @@ export class UserGroundHost {
                 return current;
             },
             materializeWorkspace: async (input) => {
+                this.options.reserveWritableRoot?.(join(input.destinationParent, input.workspace.name));
                 const groundWaitStarted = performance.now();
                 this.stage({
                     primitive: "download",
@@ -2060,9 +2063,19 @@ export class UserGroundHost {
             throw new Error(`download set did not seal ${artifact.contentHash}`);
         return local;
     }
+    reserveGroundRoots(identity) {
+        if (!this.options.reserveWritableRoot)
+            return;
+        const userRoot = this.userRoot(identity);
+        this.options.reserveWritableRoot(userRoot);
+        for (const { directory } of materializedWorkspaceBindings(workspaceBindingDir(userRoot, identity.deviceId))) {
+            this.options.reserveWritableRoot(directory);
+        }
+    }
     ensureWatchers(identity, authoritativeBaselineRootIds = []) {
         if (this.closing)
             return this.watchHost.health();
+        this.reserveGroundRoots(identity);
         const started = performance.now();
         const root = this.userRoot(identity);
         const wanted = new Map([[root, {