@pugi/cli 0.1.0-beta.96 → 0.1.0-beta.98

package/dist/tools/server-tools.js

@@ -0,0 +1,892 @@
+/**
+ * server-tools - Phase 1 runtime evidence primitives (PUGI Phase 1).
+ *
+ * These tools give the model a way to spin up a service, probe its
+ * health endpoint, harvest log tails, and tear it down - turning
+ * "server is running" prose into pid + health 200 evidence.
+ *
+ * Surfaced as four tools:
+ *   - server_start: spawn `command` in `cwd`, poll `healthUrl` until
+ *     status === expectStatus (default 200) OR timeout elapses OR
+ *     the process exits. Persist {pid, port, logPath, command} to
+ *     `.pugi/runs/<runId>/server.json` for later inspection.
+ *   - server_stop: SIGTERM → graceMs → SIGKILL the pid, returning the
+ *     exit code + signal. No-op-safe when the process is already dead.
+ *   - server_health: one-shot HTTP GET against an arbitrary url with a
+ *     timeout. Distinct from `server_start`'s built-in health probe
+ *     because the model frequently needs to re-check liveness after
+ *     migrations / restarts.
+ *   - server_logs: read the trailing N lines of a `runId` (or pid)'s
+ *     log file so the model can diagnose a failure without re-running
+ *     the server.
+ *
+ * The async + sync entry points mirror the bash-tool split so the
+ * engine-loop tool-bridge can dispatch from spawnSync paths too.
+ *
+ * Security posture:
+ *   - server_start / server_stop use the bash permission class via the
+ *     registry so the existing mode-aware permission gate applies. The
+ *     tool itself does NOT call evaluateBashPermission - the bash-class
+ *     entry in registry.ts pins risk=high and concurrencySafe=false.
+ *   - server_logs is read-only against `.pugi/runs/<runId>/server.log`.
+ *     Path traversal is gated by `resolveWorkspacePath` to keep the
+ *     read inside the workspace.
+ *   - env is filtered through the same SAFE_ENV_ALLOW set as bash.ts so
+ *     PUGI_API_KEY / PUGI_LOGIN_TOKEN never leak to the spawned child.
+ *
+ * Brand voice: English only, no emoji, no banned words.
+ */
+import { spawn } from 'node:child_process';
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+/** Default health-poll cadence. */
+export const SERVER_START_DEFAULT_POLL_MS = 500;
+/** Default health-probe timeout - generous because dev servers warm up. */
+export const SERVER_START_DEFAULT_TIMEOUT_MS = 30_000;
+/** Upper bound on the health-probe timeout. */
+export const SERVER_START_MAX_TIMEOUT_MS = 5 * 60 * 1_000;
+/** Default grace window between SIGTERM and SIGKILL. Mirrors bash.ts. */
+export const SERVER_STOP_DEFAULT_GRACE_MS = 5_000;
+/** Upper bound on the stop grace window. */
+export const SERVER_STOP_MAX_GRACE_MS = 60_000;
+/** Default tail size for server_logs. */
+export const SERVER_LOGS_DEFAULT_TAIL = 200;
+/** Upper bound on log tail size to keep the response envelope sized. */
+export const SERVER_LOGS_MAX_TAIL = 2_000;
+/** Sentinel returned when an argument shape fails validation. */
+export const SERVER_INVALID_ARGS = 'SERVER_INVALID_ARGS';
+/**
+ * Subset of process.env we forward to the spawned server. Mirrors the
+ * SAFE_ENV_ALLOW set in bash.ts so PUGI credentials never leak across
+ * the boundary even when an operator passes them via `env`.
+ */
+const SAFE_ENV_ALLOW = new Set([
+    'PATH',
+    'HOME',
+    'USER',
+    'LOGNAME',
+    'SHELL',
+    'LANG',
+    'TZ',
+    'TERM',
+    'PWD',
+    'NODE_ENV',
+    'NODE_OPTIONS',
+    'NODE_VERSION',
+]);
+function buildChildEnv(extra) {
+    const env = {};
+    for (const [key, value] of Object.entries(process.env)) {
+        if (value === undefined)
+            continue;
+        if (SAFE_ENV_ALLOW.has(key) || key.startsWith('LC_')) {
+            env[key] = value;
+        }
+    }
+    // Caller-supplied env overrides system inheritance. We do NOT filter
+    // the caller set - the model is expected to supply concrete keys
+    // (NODE_ENV=development, PORT=3000) and should not be silently
+    // dropped just because the key falls outside the allowlist.
+    if (extra) {
+        for (const [key, value] of Object.entries(extra)) {
+            if (typeof value === 'string')
+                env[key] = value;
+        }
+    }
+    return env;
+}
+/**
+ * Resolve `cwd` against the workspace root. Relative paths root at
+ * workspaceRoot; absolute paths are accepted ONLY when they fall under
+ * workspaceRoot. Anything else collapses to workspaceRoot - defense in
+ * depth so a stale path argument cannot spawn a server outside the
+ * operator's workspace.
+ */
+function resolveCwd(workspaceRoot, requested) {
+    if (!requested)
+        return workspaceRoot;
+    const absolute = isAbsolute(requested) ? requested : resolve(workspaceRoot, requested);
+    const rootAnchor = workspaceRoot.endsWith('/') ? workspaceRoot.slice(0, -1) : workspaceRoot;
+    if (absolute === rootAnchor || absolute.startsWith(`${rootAnchor}/`)) {
+        return absolute;
+    }
+    return workspaceRoot;
+}
+/**
+ * Validate `server_start` arguments. Returns the typed payload on
+ * success or a sentinel string on failure (consistent with the
+ * sleep/brief tool convention).
+ */
+export function parseServerStartArgs(raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        return `${SERVER_INVALID_ARGS}: arguments must be a JSON object`;
+    }
+    const obj = raw;
+    const command = obj['command'];
+    const port = obj['port'];
+    if (typeof command !== 'string' || command.trim() === '') {
+        return `${SERVER_INVALID_ARGS}: command must be a non-empty string`;
+    }
+    if (typeof port !== 'number' || !Number.isInteger(port) || port < 1 || port > 65535) {
+        return `${SERVER_INVALID_ARGS}: port must be an integer in [1, 65535]`;
+    }
+    const cwd = obj['cwd'];
+    if (cwd !== undefined && typeof cwd !== 'string') {
+        return `${SERVER_INVALID_ARGS}: cwd must be a string when provided`;
+    }
+    const healthUrl = obj['healthUrl'];
+    if (healthUrl !== undefined && typeof healthUrl !== 'string') {
+        return `${SERVER_INVALID_ARGS}: healthUrl must be a string when provided`;
+    }
+    const timeoutMs = obj['timeoutMs'];
+    if (timeoutMs !== undefined) {
+        if (typeof timeoutMs !== 'number' || !Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+            return `${SERVER_INVALID_ARGS}: timeoutMs must be a positive number when provided`;
+        }
+    }
+    const expectStatus = obj['expectStatus'];
+    if (expectStatus !== undefined) {
+        if (typeof expectStatus !== 'number' || !Number.isInteger(expectStatus) || expectStatus < 100 || expectStatus > 599) {
+            return `${SERVER_INVALID_ARGS}: expectStatus must be an integer in [100, 599]`;
+        }
+    }
+    const env = obj['env'];
+    if (env !== undefined) {
+        if (typeof env !== 'object' || env === null || Array.isArray(env)) {
+            return `${SERVER_INVALID_ARGS}: env must be a JSON object of string values`;
+        }
+        for (const [k, v] of Object.entries(env)) {
+            if (typeof v !== 'string') {
+                return `${SERVER_INVALID_ARGS}: env["${k}"] must be a string`;
+            }
+        }
+    }
+    const args = {
+        command,
+        port,
+        ...(typeof cwd === 'string' ? { cwd } : {}),
+        ...(typeof healthUrl === 'string' ? { healthUrl } : {}),
+        ...(typeof timeoutMs === 'number' ? { timeoutMs } : {}),
+        ...(typeof expectStatus === 'number' ? { expectStatus } : {}),
+        ...(env !== undefined ? { env: env } : {}),
+    };
+    return args;
+}
+function clampTimeout(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+        return SERVER_START_DEFAULT_TIMEOUT_MS;
+    }
+    return Math.min(value, SERVER_START_MAX_TIMEOUT_MS);
+}
+function clampGrace(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+        return SERVER_STOP_DEFAULT_GRACE_MS;
+    }
+    return Math.min(value, SERVER_STOP_MAX_GRACE_MS);
+}
+function clampTail(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+        return SERVER_LOGS_DEFAULT_TAIL;
+    }
+    return Math.min(Math.floor(value), SERVER_LOGS_MAX_TAIL);
+}
+function ensureRunsDir(workspaceRoot, runId) {
+    const dir = join(workspaceRoot, '.pugi', 'runs', runId);
+    mkdirSync(dir, { recursive: true });
+    return { dir, logPath: join(dir, 'server.log'), metaPath: join(dir, 'server.json') };
+}
+function writeMeta(metaPath, meta) {
+    try {
+        const body = JSON.stringify(meta, null, 2);
+        writeFileSync(metaPath, `${body}\n`, { encoding: 'utf8', mode: 0o600 });
+    }
+    catch {
+        // best-effort - the in-memory return envelope still carries the data
+    }
+}
+/**
+ * Open a write stream to the log file. Uses appendFileSync from the
+ * spawned child's stdout/stderr handlers because spawn's stdio file
+ * descriptor inheritance is fiddly across platforms and we want the
+ * loop to honour the cancel/timeout windows above all else.
+ */
+function openLogWriter(logPath) {
+    // Truncate existing file so reruns of the same runId start fresh.
+    try {
+        writeFileSync(logPath, '', { encoding: 'utf8', mode: 0o600 });
+    }
+    catch {
+        // ignore - appends below will retry through writeFileSync
+    }
+    return (chunk) => {
+        try {
+            const data = typeof chunk === 'string' ? chunk : chunk.toString('utf8');
+            // appendFileSync via writeFileSync + flag 'a' is simpler than
+            // requiring fs/promises in a sync path. We use the node fs append
+            // mode via an opt-in `flag: 'a'` on writeFileSync.
+            writeFileSync(logPath, data, { encoding: 'utf8', flag: 'a' });
+        }
+        catch {
+            // log capture is best-effort - never crash the server tool
+        }
+    };
+}
+/**
+ * Poll the health URL until either:
+ *  - the HTTP call returns the expected status code → ok=true
+ *  - the timeout elapses → ok=false with reason=timeout_waiting_health
+ *  - the spawned child exits before the probe succeeds → ok=false with
+ *    reason=process_exited (the close-watcher flips this flag)
+ */
+async function pollHealth(input) {
+    const start = input.now();
+    const deadline = start + input.timeoutMs;
+    let lastStatus;
+    while (input.now() < deadline) {
+        if (input.hasExited()) {
+            return {
+                ok: false,
+                durationMs: input.now() - start,
+                reason: 'process_exited',
+                ...(lastStatus !== undefined ? { status: lastStatus } : {}),
+            };
+        }
+        try {
+            const ac = new AbortController();
+            const probeTimeout = setTimeout(() => ac.abort(), Math.min(2_000, input.timeoutMs));
+            try {
+                const res = await input.fetchImpl(input.url, { signal: ac.signal });
+                lastStatus = res.status;
+                if (res.status === input.expectStatus) {
+                    return { ok: true, status: res.status, durationMs: input.now() - start };
+                }
+            }
+            finally {
+                clearTimeout(probeTimeout);
+            }
+        }
+        catch {
+            // network refused / dns / abort - keep polling, the server is
+            // probably still warming up
+        }
+        await input.sleeper(SERVER_START_DEFAULT_POLL_MS);
+    }
+    return {
+        ok: false,
+        durationMs: input.now() - start,
+        reason: 'timeout_waiting_health',
+        ...(lastStatus !== undefined ? { status: lastStatus } : {}),
+    };
+}
+/**
+ * Dispatch entry: parse args, spawn the server, poll its health, and
+ * return a structured envelope. The pid is persisted to
+ * `.pugi/runs/<runId>/server.json` so a later `server_stop` / operator
+ * cleanup script can find it.
+ */
+export async function dispatchServerStart(ctx, raw) {
+    const parsed = parseServerStartArgs(raw);
+    if (typeof parsed === 'string')
+        return parsed;
+    const args = parsed;
+    const now = ctx.now ?? (() => Date.now());
+    const sleeper = ctx.sleeper ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const fetchImpl = ctx.fetch ?? globalThis.fetch;
+    const spawnImpl = ctx.spawnImpl ?? spawn;
+    if (typeof fetchImpl !== 'function') {
+        const result = {
+            ok: false,
+            runId: '',
+            logPath: '',
+            metaPath: '',
+            durationMs: 0,
+            error: 'no_fetch_available',
+        };
+        return JSON.stringify(result);
+    }
+    const runId = `srv-${randomUUID()}`;
+    const { logPath, metaPath } = ensureRunsDir(ctx.workspaceRoot, runId);
+    const writer = openLogWriter(logPath);
+    const cwd = resolveCwd(ctx.workspaceRoot, args.cwd);
+    const env = buildChildEnv(args.env);
+    const timeoutMs = clampTimeout(args.timeoutMs);
+    const healthUrl = args.healthUrl ?? `http://localhost:${args.port}/health`;
+    const expectStatus = args.expectStatus ?? 200;
+    const startedAt = now();
+    let child;
+    try {
+        child = spawnImpl('/bin/sh', ['-c', args.command], {
+            cwd,
+            env,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            detached: false,
+        });
+    }
+    catch (error) {
+        const message = error.message;
+        writer(`[server_start] spawn failed: ${message}\n`);
+        const result = {
+            ok: false,
+            runId,
+            logPath,
+            metaPath,
+            durationMs: now() - startedAt,
+            error: `spawn_failed: ${message}`,
+        };
+        writeMeta(metaPath, {
+            ok: false,
+            command: args.command,
+            cwd,
+            port: args.port,
+            healthUrl,
+            error: result.error,
+            startedAt: new Date(startedAt).toISOString(),
+        });
+        return JSON.stringify(result);
+    }
+    let exited = false;
+    let exitCode;
+    let exitSignal;
+    child.on('exit', (code, signal) => {
+        exited = true;
+        exitCode = code ?? undefined;
+        exitSignal = signal ?? undefined;
+    });
+    child.stdout?.on('data', (chunk) => writer(chunk));
+    child.stderr?.on('data', (chunk) => writer(chunk));
+    child.on('error', (error) => {
+        writer(`[server_start] child error: ${error.message}\n`);
+    });
+    const pid = child.pid;
+    const meta = {
+        runId,
+        pid: pid ?? -1,
+        command: args.command,
+        cwd,
+        port: args.port,
+        healthUrl,
+        expectStatus,
+        startedAt: new Date(startedAt).toISOString(),
+        logPath,
+    };
+    writeMeta(metaPath, meta);
+    const probe = await pollHealth({
+        url: healthUrl,
+        expectStatus,
+        timeoutMs,
+        fetchImpl,
+        sleeper,
+        now,
+        hasExited: () => exited,
+    });
+    if (probe.ok) {
+        const result = {
+            ok: true,
+            runId,
+            pid,
+            port: args.port,
+            healthStatus: probe.status,
+            logPath,
+            metaPath,
+            durationMs: probe.durationMs,
+        };
+        writeMeta(metaPath, { ...meta, status: 'healthy', healthStatus: probe.status });
+        return JSON.stringify(result);
+    }
+    // Failure path - surface the reason. The child may still be running
+    // (timeout) or already dead (process_exited). The caller decides what
+    // to do with the pid; we do NOT auto-kill so the operator can inspect
+    // a hung process via `pugi jobs` / `ps`.
+    const result = {
+        ok: false,
+        runId,
+        ...(pid !== undefined ? { pid } : {}),
+        port: args.port,
+        logPath,
+        metaPath,
+        durationMs: probe.durationMs,
+        error: probe.reason ?? 'unknown_failure',
+        ...(exitCode !== undefined ? { exitCode } : {}),
+    };
+    writeMeta(metaPath, {
+        ...meta,
+        status: probe.reason ?? 'failed',
+        ...(exitCode !== undefined ? { exitCode } : {}),
+        ...(exitSignal !== undefined ? { exitSignal } : {}),
+    });
+    return JSON.stringify(result);
+}
+export function parseServerStopArgs(raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        return `${SERVER_INVALID_ARGS}: arguments must be a JSON object`;
+    }
+    const obj = raw;
+    const pid = obj['pid'];
+    if (typeof pid !== 'number' || !Number.isInteger(pid) || pid <= 0) {
+        return `${SERVER_INVALID_ARGS}: pid must be a positive integer`;
+    }
+    const graceMs = obj['graceMs'];
+    if (graceMs !== undefined) {
+        if (typeof graceMs !== 'number' || !Number.isFinite(graceMs) || graceMs < 0) {
+            return `${SERVER_INVALID_ARGS}: graceMs must be a non-negative number when provided`;
+        }
+    }
+    return {
+        pid,
+        ...(typeof graceMs === 'number' ? { graceMs } : {}),
+    };
+}
+/**
+ * SIGTERM the pid, wait up to graceMs for natural exit, then SIGKILL.
+ * Returns `ok: true` when the kill chain ran without error - both
+ * "already exited" and "killed by SIGKILL" count as success because
+ * the desired outcome (pid no longer running) was achieved.
+ */
+export async function dispatchServerStop(ctx, raw) {
+    const parsed = parseServerStopArgs(raw);
+    if (typeof parsed === 'string')
+        return parsed;
+    const args = parsed;
+    const now = ctx.now ?? (() => Date.now());
+    const sleeper = ctx.sleeper ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const killImpl = ctx.killImpl ??
+        ((pid, signal) => {
+            process.kill(pid, signal);
+        });
+    const graceMs = clampGrace(args.graceMs);
+    const start = now();
+    const isAlive = (pid) => {
+        try {
+            killImpl(pid, 0);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    if (!isAlive(args.pid)) {
+        const result = {
+            ok: true,
+            pid: args.pid,
+            durationMs: now() - start,
+            signal: undefined,
+        };
+        return JSON.stringify(result);
+    }
+    try {
+        killImpl(args.pid, 'SIGTERM');
+    }
+    catch (error) {
+        const message = error.message;
+        const result = {
+            ok: false,
+            pid: args.pid,
+            durationMs: now() - start,
+            error: `sigterm_failed: ${message}`,
+        };
+        return JSON.stringify(result);
+    }
+    // Poll for exit during the grace window.
+    const deadline = now() + graceMs;
+    let killedSignal = 'SIGTERM';
+    while (now() < deadline) {
+        if (!isAlive(args.pid)) {
+            const result = {
+                ok: true,
+                pid: args.pid,
+                signal: killedSignal,
+                durationMs: now() - start,
+            };
+            return JSON.stringify(result);
+        }
+        await sleeper(50);
+    }
+    // Grace expired - escalate to SIGKILL.
+    try {
+        killImpl(args.pid, 'SIGKILL');
+        killedSignal = 'SIGKILL';
+    }
+    catch (error) {
+        const message = error.message;
+        const result = {
+            ok: false,
+            pid: args.pid,
+            durationMs: now() - start,
+            error: `sigkill_failed: ${message}`,
+        };
+        return JSON.stringify(result);
+    }
+    // Brief poll after SIGKILL - kernel should clean up promptly.
+    const killDeadline = now() + 1_000;
+    while (now() < killDeadline) {
+        if (!isAlive(args.pid)) {
+            const result = {
+                ok: true,
+                pid: args.pid,
+                signal: killedSignal,
+                durationMs: now() - start,
+            };
+            return JSON.stringify(result);
+        }
+        await sleeper(50);
+    }
+    const result = {
+        ok: false,
+        pid: args.pid,
+        durationMs: now() - start,
+        error: 'process_still_alive_after_sigkill',
+    };
+    return JSON.stringify(result);
+}
+export function parseServerHealthArgs(raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        return `${SERVER_INVALID_ARGS}: arguments must be a JSON object`;
+    }
+    const obj = raw;
+    const url = obj['url'];
+    if (typeof url !== 'string' || url.trim() === '') {
+        return `${SERVER_INVALID_ARGS}: url must be a non-empty string`;
+    }
+    const timeoutMs = obj['timeoutMs'];
+    if (timeoutMs !== undefined) {
+        if (typeof timeoutMs !== 'number' || !Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+            return `${SERVER_INVALID_ARGS}: timeoutMs must be a positive number when provided`;
+        }
+    }
+    const expectStatus = obj['expectStatus'];
+    if (expectStatus !== undefined) {
+        if (typeof expectStatus !== 'number' || !Number.isInteger(expectStatus) || expectStatus < 100 || expectStatus > 599) {
+            return `${SERVER_INVALID_ARGS}: expectStatus must be an integer in [100, 599]`;
+        }
+    }
+    return {
+        url,
+        ...(typeof timeoutMs === 'number' ? { timeoutMs } : {}),
+        ...(typeof expectStatus === 'number' ? { expectStatus } : {}),
+    };
+}
+/** Cap on the body we return to the model - keeps the envelope small. */
+export const SERVER_HEALTH_BODY_CAP_BYTES = 1024;
+/** Default health-probe timeout. */
+export const SERVER_HEALTH_DEFAULT_TIMEOUT_MS = 5_000;
+/** Upper bound on a single one-shot health-probe timeout. */
+export const SERVER_HEALTH_MAX_TIMEOUT_MS = 60_000;
+function clampHealthTimeout(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+        return SERVER_HEALTH_DEFAULT_TIMEOUT_MS;
+    }
+    return Math.min(value, SERVER_HEALTH_MAX_TIMEOUT_MS);
+}
+/**
+ * One-shot HTTP GET against the supplied URL. Caller can pin the
+ * expected status (default 200); anything else surfaces as ok=false
+ * with the actual status preserved so the model can branch on it.
+ */
+export async function dispatchServerHealth(ctx, raw) {
+    const parsed = parseServerHealthArgs(raw);
+    if (typeof parsed === 'string')
+        return parsed;
+    const args = parsed;
+    const now = ctx.now ?? (() => Date.now());
+    const fetchImpl = ctx.fetch ?? globalThis.fetch;
+    const expectStatus = args.expectStatus ?? 200;
+    const timeoutMs = clampHealthTimeout(args.timeoutMs);
+    if (typeof fetchImpl !== 'function') {
+        const result = {
+            ok: false,
+            status: 0,
+            durationMs: 0,
+            error: 'no_fetch_available',
+        };
+        return JSON.stringify(result);
+    }
+    const start = now();
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), timeoutMs);
+    try {
+        const res = await fetchImpl(args.url, { signal: ac.signal });
+        const text = await res.text();
+        const body = text.length > SERVER_HEALTH_BODY_CAP_BYTES ? text.slice(0, SERVER_HEALTH_BODY_CAP_BYTES) : text;
+        const result = {
+            ok: res.status === expectStatus,
+            status: res.status,
+            durationMs: now() - start,
+            body,
+        };
+        return JSON.stringify(result);
+    }
+    catch (error) {
+        const message = error.message;
+        const aborted = error.name === 'AbortError' || ac.signal.aborted;
+        const result = {
+            ok: false,
+            status: 0,
+            durationMs: now() - start,
+            error: aborted
+                ? `timeout_after_${timeoutMs}ms`
+                : message === '' ? 'health_request_failed' : `health_request_failed: ${message}`,
+        };
+        return JSON.stringify(result);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export function parseServerLogsArgs(raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        return `${SERVER_INVALID_ARGS}: arguments must be a JSON object`;
+    }
+    const obj = raw;
+    const runId = obj['runId'];
+    const pid = obj['pid'];
+    const tail = obj['tail'];
+    if (runId !== undefined && typeof runId !== 'string') {
+        return `${SERVER_INVALID_ARGS}: runId must be a string when provided`;
+    }
+    // /triple-review P1 (Claude reviewer): runId flows
+    // unchecked into `join(workspaceRoot, '.pugi', 'runs', runId, 'server.log')`.
+    // A runId of `../../etc/passwd` (or other `..` traversal) escapes
+    // the workspace and reads arbitrary files via the surfaced `lines[]`.
+    // Pin к the `srv-<uuid>` shape that `dispatchServerStart` mints
+    // (`srv-` + `randomUUID()` = lowercase hex + dashes).
+    if (typeof runId === 'string' && !/^srv-[a-f0-9-]{36}$/.test(runId)) {
+        return `${SERVER_INVALID_ARGS}: runId must match srv-<uuid> shape`;
+    }
+    if (pid !== undefined) {
+        if (typeof pid !== 'number' || !Number.isInteger(pid) || pid <= 0) {
+            return `${SERVER_INVALID_ARGS}: pid must be a positive integer when provided`;
+        }
+    }
+    if (tail !== undefined) {
+        if (typeof tail !== 'number' || !Number.isFinite(tail) || tail <= 0) {
+            return `${SERVER_INVALID_ARGS}: tail must be a positive number when provided`;
+        }
+    }
+    if (runId === undefined && pid === undefined) {
+        // Allow "latest" by resolving the most recent runs dir at dispatch
+        // time; nothing to validate here.
+    }
+    return {
+        ...(typeof runId === 'string' ? { runId } : {}),
+        ...(typeof pid === 'number' ? { pid } : {}),
+        ...(typeof tail === 'number' ? { tail } : {}),
+    };
+}
+function resolveLatestRunId(workspaceRoot) {
+    const dir = join(workspaceRoot, '.pugi', 'runs');
+    if (!existsSync(dir))
+        return undefined;
+    try {
+        // We avoid statSync per-entry to keep the tool cheap; the runId
+        // includes a uuid so lexicographic sort is stable enough for the
+        // "latest run" answer when the operator does not pin one.
+        const entries = readdirSync(dir, { withFileTypes: true })
+            .filter((e) => e.isDirectory() && e.name.startsWith('srv-'))
+            .map((e) => e.name)
+            .sort();
+        return entries[entries.length - 1];
+    }
+    catch {
+        return undefined;
+    }
+}
+function resolveRunIdByPid(workspaceRoot, pid) {
+    const dir = join(workspaceRoot, '.pugi', 'runs');
+    if (!existsSync(dir))
+        return undefined;
+    try {
+        const entries = readdirSync(dir, { withFileTypes: true })
+            .filter((e) => e.isDirectory() && e.name.startsWith('srv-'))
+            .map((e) => e.name);
+        for (const id of entries) {
+            try {
+                const metaPath = join(dir, id, 'server.json');
+                if (!existsSync(metaPath))
+                    continue;
+                const raw = readFileSync(metaPath, 'utf8');
+                const meta = JSON.parse(raw);
+                if (meta && meta['pid'] === pid)
+                    return id;
+            }
+            catch {
+                // skip unreadable meta files
+            }
+        }
+    }
+    catch {
+        // ignore
+    }
+    return undefined;
+}
+/**
+ * Read the trailing N lines of `<runId>/server.log`. When neither
+ * runId nor pid is supplied, the dispatcher falls back to the latest
+ * run dir (sorted lexicographically by runId). When pid is supplied,
+ * the dispatcher walks every run dir looking for a meta.json whose
+ * pid matches.
+ */
+export async function dispatchServerLogs(ctx, raw) {
+    const parsed = parseServerLogsArgs(raw);
+    if (typeof parsed === 'string')
+        return parsed;
+    const args = parsed;
+    const tail = clampTail(args.tail);
+    let runId = args.runId;
+    if (!runId && typeof args.pid === 'number') {
+        runId = resolveRunIdByPid(ctx.workspaceRoot, args.pid);
+    }
+    if (!runId) {
+        runId = resolveLatestRunId(ctx.workspaceRoot);
+    }
+    if (!runId) {
+        const result = {
+            ok: false,
+            logPath: '',
+            lines: [],
+            totalLines: 0,
+            error: 'no_run_found',
+        };
+        return JSON.stringify(result);
+    }
+    const logPath = join(ctx.workspaceRoot, '.pugi', 'runs', runId, 'server.log');
+    if (!existsSync(logPath)) {
+        const result = {
+            ok: false,
+            logPath,
+            lines: [],
+            totalLines: 0,
+            error: 'log_not_found',
+        };
+        return JSON.stringify(result);
+    }
+    let body = '';
+    try {
+        body = readFileSync(logPath, 'utf8');
+    }
+    catch (error) {
+        const message = error.message;
+        const result = {
+            ok: false,
+            logPath,
+            lines: [],
+            totalLines: 0,
+            error: `read_failed: ${message}`,
+        };
+        return JSON.stringify(result);
+    }
+    const allLines = body.split('\n');
+    // Trim trailing empty produced by a final newline so the line count
+    // reflects "actual log lines" not "lines + trailing blank".
+    if (allLines.length > 0 && allLines[allLines.length - 1] === '') {
+        allLines.pop();
+    }
+    const lines = allLines.length > tail ? allLines.slice(allLines.length - tail) : allLines;
+    const result = {
+        ok: true,
+        logPath,
+        lines,
+        totalLines: allLines.length,
+    };
+    return JSON.stringify(result);
+}
+/* ----------------------- JSON schema fragments ----------------------- */
+export const serverStartJsonSchema = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['command', 'port'],
+    properties: {
+        command: {
+            type: 'string',
+            description: 'Shell command to spawn, e.g. "npm run dev" or "node server.js".',
+        },
+        cwd: {
+            type: 'string',
+            description: 'Workspace-relative cwd for the spawn. Absolute paths must fall inside the workspace.',
+        },
+        port: {
+            type: 'integer',
+            minimum: 1,
+            maximum: 65535,
+            description: 'Expected listening port. Used in the default healthUrl when no healthUrl is supplied.',
+        },
+        healthUrl: {
+            type: 'string',
+            description: 'Optional HTTP health URL. Defaults to http://localhost:<port>/health.',
+        },
+        timeoutMs: {
+            type: 'number',
+            description: `Health-probe timeout in ms. Default ${SERVER_START_DEFAULT_TIMEOUT_MS}, max ${SERVER_START_MAX_TIMEOUT_MS}.`,
+        },
+        expectStatus: {
+            type: 'integer',
+            minimum: 100,
+            maximum: 599,
+            description: 'Expected HTTP status. Default 200.',
+        },
+        env: {
+            type: 'object',
+            description: 'Optional env override map. Values must be strings.',
+            additionalProperties: { type: 'string' },
+        },
+    },
+};
+export const serverStopJsonSchema = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['pid'],
+    properties: {
+        pid: {
+            type: 'integer',
+            minimum: 1,
+            description: 'Process id of a server started via `server_start`.',
+        },
+        graceMs: {
+            type: 'number',
+            minimum: 0,
+            description: `SIGTERM → SIGKILL grace window in ms. Default ${SERVER_STOP_DEFAULT_GRACE_MS}, max ${SERVER_STOP_MAX_GRACE_MS}.`,
+        },
+    },
+};
+export const serverHealthJsonSchema = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['url'],
+    properties: {
+        url: {
+            type: 'string',
+            description: 'Fully-qualified HTTP/HTTPS URL to probe.',
+        },
+        timeoutMs: {
+            type: 'number',
+            description: `Single-shot probe timeout in ms. Default ${SERVER_HEALTH_DEFAULT_TIMEOUT_MS}, max ${SERVER_HEALTH_MAX_TIMEOUT_MS}.`,
+        },
+        expectStatus: {
+            type: 'integer',
+            minimum: 100,
+            maximum: 599,
+            description: 'Expected HTTP status. Default 200.',
+        },
+    },
+};
+export const serverLogsJsonSchema = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        runId: {
+            type: 'string',
+            description: 'Run identifier returned by `server_start`. Falls back to the latest run when omitted.',
+        },
+        pid: {
+            type: 'integer',
+            minimum: 1,
+            description: 'Optional process id; the dispatcher finds the matching run dir.',
+        },
+        tail: {
+            type: 'number',
+            minimum: 1,
+            description: `Trailing lines to return. Default ${SERVER_LOGS_DEFAULT_TAIL}, max ${SERVER_LOGS_MAX_TAIL}.`,
+        },
+    },
+};
+//# sourceMappingURL=server-tools.js.map