@alvax-ai/adapter-utils 0.1.0

package/dist/server-utils.js

@@ -0,0 +1,1580 @@
+import { spawn } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import { constants as fsConstants, promises as fs } from "node:fs";
+import path from "node:path";
+import { sanitizeRemoteExecutionEnv } from "./remote-execution-env.js";
+import { buildSshSpawnTarget } from "./ssh.js";
+import { redactCommandText } from "./command-redaction.js";
+function resolveProcessGroupId(child) {
+    if (process.platform === "win32")
+        return null;
+    return typeof child.pid === "number" && child.pid > 0 ? child.pid : null;
+}
+function signalRunningProcess(running, signal) {
+    if (process.platform !== "win32" && running.processGroupId && running.processGroupId > 0) {
+        try {
+            process.kill(-running.processGroupId, signal);
+            return;
+        }
+        catch {
+            // Fall back to the direct child signal if group signaling fails.
+        }
+    }
+    if (!running.child.killed) {
+        running.child.kill(signal);
+    }
+}
+export const runningProcesses = new Map();
+export const MAX_CAPTURE_BYTES = 4 * 1024 * 1024;
+export const MAX_EXCERPT_BYTES = 32 * 1024;
+const TERMINAL_RESULT_SCAN_OVERLAP_CHARS = 64 * 1024;
+const SENSITIVE_ENV_KEY = /(key|token|secret|password|passwd|authorization|cookie)/i;
+const REDACTED_LOG_VALUE = "***REDACTED***";
+const ALVAX_SKILL_ROOT_RELATIVE_CANDIDATES = [
+    "../../skills",
+    "../../../../../skills",
+];
+const MATERIALIZED_SKILL_SENTINEL = ".alvax-materialized-skill.json";
+const MATERIALIZED_SKILL_LOCK_OWNER = "owner.json";
+const MATERIALIZED_SKILL_LOCK_STALE_MS = 30_000;
+export const DEFAULT_ALVAX_AGENT_PROMPT_TEMPLATE = [
+    "You are agent {{agent.id}} ({{agent.name}}). Continue your Alvax work.",
+    "",
+    "Execution contract:",
+    "- Start actionable work in this heartbeat; do not stop at a plan unless the issue asks for planning.",
+    "- Use the current issue context from the prompt and environment variables.",
+    "- If the issue context says the subtree is paused, respond or triage the explicit human wake only; do not resume or cancel the subtree yourself.",
+    "- Write durable progress with POST /api/issues/{{context.issueId}}/comments.",
+    "- Update issue status with PATCH /api/issues/{{context.issueId}}.",
+    "- Read issue documents with GET /api/issues/{{context.issueId}}/documents and GET /api/issues/{{context.issueId}}/documents/:key.",
+    "- Create or update issue documents with PUT /api/issues/{{context.issueId}}/documents/:key.",
+    "- List issue document revisions with GET /api/issues/{{context.issueId}}/documents/:key/revisions.",
+    "- Read issue interactions with GET /api/issues/{{context.issueId}}/interactions.",
+    "- Create child issues directly with POST /api/issues/{{context.issueId}}/children when the needed work is clear.",
+    "- Use POST /api/issues/{{context.issueId}}/interactions with kind: suggest_tasks when the board/user must choose from proposed child work before issues are created.",
+    "- Use POST /api/issues/{{context.issueId}}/interactions with kind: ask_user_questions for structured choices and kind: request_confirmation for concrete approvals.",
+    "- For planning issues, use the `plan` issue document as the source of truth. After a board accepts the plan, create child issues from the approved plan instead of implementing on the planning issue.",
+    "- Register deliverables with POST /api/issues/{{context.issueId}}/work-products.",
+    "- Update deliverables with PATCH /api/work-products/{workProductId}.",
+    "- Delete mistaken deliverables with DELETE /api/work-products/{workProductId}.",
+    "- When asked to make or revise a plan, use document key `plan`. For durable reports, notes, or diagnoses, use a clear lowercase key such as `report`, `notes`, or `diagnosis`. Before updating an existing document, fetch it and send its `latestRevisionId` as `baseRevisionId`. After changing a document, leave a normal issue comment that summarizes progress and names the updated document.",
+    "- Use child issues for parallel or delegated work instead of polling agents, sessions, or processes.",
+    "- For plan approval, update the `plan` issue document first, then create `request_confirmation` targeting the latest plan revision with target type `issue_document`, key `plan`, revisionId set to `latestRevisionId`, and idempotencyKey `confirmation:{issueId}:plan:{revisionId}`.",
+    "- Use `ask_user_questions` for bounded choices.",
+    "- Use continuationPolicy `wake_assignee` when you need to resume after a response.",
+    "- Use continuationPolicy `wake_assignee_on_accept` only when rejection should end the path.",
+    "- Register user-visible deliverables as issue work products.",
+    "- Mark the issue done when complete, blocked when waiting on a named unblock owner/action, or in_review when human review or an issue interaction is genuinely needed.",
+    "- Use Authorization: Bearer $ALVAX_API_KEY and X-Alvax-Run-Id: $ALVAX_RUN_ID on Alvax API requests.",
+    "- Company Knowledge Documents listed in context are read-only company files. Use their localPath when relevant. Do not call Knowledge upload/delete APIs or binary storage mutation APIs.",
+    "- Company Knowledge Data Tables contain structured reusable company knowledge. Use agent-safe Data Table APIs to read rows and to create/update non-destructive table data. Do not store secrets in Data Tables. For destructive Data Table operations, create a linked knowledge_data_table_change_request approval and wait for board approval.",
+    "- If a missing secret blocks the issue, use the $alvax credential_request workflow: create a linked credential_request approval, comment on the source issue, set it to in_review, and wait for board approval. Never ask for secret values in comments.",
+    "- Do not create budget, tool permission, or policy approvals.",
+    "- Do not call approval approve/reject/request-revision routes, secret CRUD APIs, budgets, liveness, routines, goals, or issue-tree-control APIs.",
+    "- Respect company boundaries and the checked-out issue.",
+].join("\n");
+function normalizePathSlashes(value) {
+    return value.replaceAll("\\", "/");
+}
+function isMaintainerOnlySkillTarget(candidate) {
+    return normalizePathSlashes(candidate).includes("/.agents/skills/");
+}
+function skillLocationLabel(value) {
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function buildManagedSkillOrigin(entry) {
+    if (entry.required) {
+        return {
+            origin: "alvax_required",
+            originLabel: "Required by Alvax",
+            readOnly: false,
+        };
+    }
+    return {
+        origin: "company_managed",
+        originLabel: "Managed by Alvax",
+        readOnly: false,
+    };
+}
+function resolveInstalledEntryTarget(skillsHome, entryName, dirent, linkedPath) {
+    const fullPath = path.join(skillsHome, entryName);
+    if (dirent.isSymbolicLink()) {
+        return {
+            targetPath: linkedPath ? path.resolve(path.dirname(fullPath), linkedPath) : null,
+            kind: "symlink",
+        };
+    }
+    if (dirent.isDirectory()) {
+        return { targetPath: fullPath, kind: "directory" };
+    }
+    return { targetPath: fullPath, kind: "file" };
+}
+export function parseObject(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return {};
+    }
+    return value;
+}
+export function asString(value, fallback) {
+    return typeof value === "string" && value.length > 0 ? value : fallback;
+}
+export function asNumber(value, fallback) {
+    return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+export function asBoolean(value, fallback) {
+    return typeof value === "boolean" ? value : fallback;
+}
+export function asStringArray(value) {
+    return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
+export function parseJson(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return null;
+    }
+}
+export function appendWithCap(prev, chunk, cap = MAX_CAPTURE_BYTES) {
+    const combined = prev + chunk;
+    return combined.length > cap ? combined.slice(combined.length - cap) : combined;
+}
+export function appendWithByteCap(prev, chunk, cap = MAX_CAPTURE_BYTES) {
+    const combined = prev + chunk;
+    const bytes = Buffer.byteLength(combined, "utf8");
+    if (bytes <= cap)
+        return combined;
+    const buffer = Buffer.from(combined, "utf8");
+    let start = Math.max(0, bytes - cap);
+    while (start < buffer.length && (buffer[start] & 0xc0) === 0x80)
+        start += 1;
+    return buffer.subarray(start).toString("utf8");
+}
+function resumeReadable(readable) {
+    if (!readable || readable.destroyed)
+        return;
+    readable.resume();
+}
+export function resolvePathValue(obj, dottedPath) {
+    const parts = dottedPath.split(".");
+    let cursor = obj;
+    for (const part of parts) {
+        if (typeof cursor !== "object" || cursor === null || Array.isArray(cursor)) {
+            return "";
+        }
+        cursor = cursor[part];
+    }
+    if (cursor === null || cursor === undefined)
+        return "";
+    if (typeof cursor === "string")
+        return cursor;
+    if (typeof cursor === "number" || typeof cursor === "boolean")
+        return String(cursor);
+    try {
+        return JSON.stringify(cursor);
+    }
+    catch {
+        return "";
+    }
+}
+export function renderTemplate(template, data) {
+    return template.replace(/{{\s*([a-zA-Z0-9_.-]+)\s*}}/g, (_, path) => resolvePathValue(data, path));
+}
+export function joinPromptSections(sections, separator = "\n\n") {
+    return sections
+        .map((value) => (typeof value === "string" ? value.trim() : ""))
+        .filter(Boolean)
+        .join(separator);
+}
+function normalizeAlvaxWakeIssue(value) {
+    const issue = parseObject(value);
+    const id = asString(issue.id, "").trim() || null;
+    const identifier = asString(issue.identifier, "").trim() || null;
+    const title = asString(issue.title, "").trim() || null;
+    const status = asString(issue.status, "").trim() || null;
+    const workMode = asString(issue.workMode, "").trim() || null;
+    const priority = asString(issue.priority, "").trim() || null;
+    if (!id && !identifier && !title)
+        return null;
+    return {
+        id,
+        identifier,
+        title,
+        status,
+        workMode,
+        priority,
+    };
+}
+function normalizeAlvaxWakeComment(value) {
+    const comment = parseObject(value);
+    const author = parseObject(comment.author);
+    const body = asString(comment.body, "");
+    if (!body.trim())
+        return null;
+    return {
+        id: asString(comment.id, "").trim() || null,
+        issueId: asString(comment.issueId, "").trim() || null,
+        body,
+        bodyTruncated: asBoolean(comment.bodyTruncated, false),
+        createdAt: asString(comment.createdAt, "").trim() || null,
+        authorType: asString(author.type, "").trim() || null,
+        authorId: asString(author.id, "").trim() || null,
+    };
+}
+function normalizeAlvaxWakeContinuationSummary(value) {
+    const summary = parseObject(value);
+    const body = asString(summary.body, "").trim();
+    if (!body)
+        return null;
+    return {
+        key: asString(summary.key, "").trim() || null,
+        title: asString(summary.title, "").trim() || null,
+        body,
+        bodyTruncated: asBoolean(summary.bodyTruncated, false),
+        updatedAt: asString(summary.updatedAt, "").trim() || null,
+    };
+}
+function normalizeAlvaxWakeLivenessContinuation(value) {
+    const continuation = parseObject(value);
+    const attempt = asNumber(continuation.attempt, 0);
+    const maxAttempts = asNumber(continuation.maxAttempts, 0);
+    const sourceRunId = asString(continuation.sourceRunId, "").trim() || null;
+    const state = asString(continuation.state, "").trim() || null;
+    const reason = asString(continuation.reason, "").trim() || null;
+    const instruction = asString(continuation.instruction, "").trim() || null;
+    if (!attempt && !maxAttempts && !sourceRunId && !state && !reason && !instruction)
+        return null;
+    return {
+        attempt: attempt > 0 ? attempt : null,
+        maxAttempts: maxAttempts > 0 ? maxAttempts : null,
+        sourceRunId,
+        state,
+        reason,
+        instruction,
+    };
+}
+function normalizeAlvaxWakeChildIssueSummary(value) {
+    const child = parseObject(value);
+    const id = asString(child.id, "").trim() || null;
+    const identifier = asString(child.identifier, "").trim() || null;
+    const title = asString(child.title, "").trim() || null;
+    const status = asString(child.status, "").trim() || null;
+    const priority = asString(child.priority, "").trim() || null;
+    const summary = asString(child.summary, "").trim() || null;
+    if (!id && !identifier && !title && !status && !summary)
+        return null;
+    return { id, identifier, title, status, priority, summary };
+}
+function normalizeAlvaxWakeBlockerSummary(value) {
+    const blocker = parseObject(value);
+    const id = asString(blocker.id, "").trim() || null;
+    const identifier = asString(blocker.identifier, "").trim() || null;
+    const title = asString(blocker.title, "").trim() || null;
+    const status = asString(blocker.status, "").trim() || null;
+    const priority = asString(blocker.priority, "").trim() || null;
+    if (!id && !identifier && !title && !status)
+        return null;
+    return { id, identifier, title, status, priority };
+}
+function normalizeAlvaxWakeTreeHoldSummary(value) {
+    const hold = parseObject(value);
+    const holdId = asString(hold.holdId, "").trim() || null;
+    const rootIssueId = asString(hold.rootIssueId, "").trim() || null;
+    const mode = asString(hold.mode, "").trim() || null;
+    const reason = asString(hold.reason, "").trim() || null;
+    if (!holdId && !rootIssueId && !mode && !reason)
+        return null;
+    return { holdId, rootIssueId, mode, reason };
+}
+function normalizeAlvaxWakeExecutionPrincipal(value) {
+    const principal = parseObject(value);
+    const typeRaw = asString(principal.type, "").trim().toLowerCase();
+    if (typeRaw !== "agent" && typeRaw !== "user")
+        return null;
+    return {
+        type: typeRaw,
+        agentId: asString(principal.agentId, "").trim() || null,
+        userId: asString(principal.userId, "").trim() || null,
+    };
+}
+function normalizeAlvaxWakeExecutionStage(value) {
+    const stage = parseObject(value);
+    const wakeRoleRaw = asString(stage.wakeRole, "").trim().toLowerCase();
+    const wakeRole = wakeRoleRaw === "reviewer" || wakeRoleRaw === "approver" || wakeRoleRaw === "executor"
+        ? wakeRoleRaw
+        : null;
+    const allowedActions = Array.isArray(stage.allowedActions)
+        ? stage.allowedActions
+            .filter((entry) => typeof entry === "string" && entry.trim().length > 0)
+            .map((entry) => entry.trim())
+        : [];
+    const currentParticipant = normalizeAlvaxWakeExecutionPrincipal(stage.currentParticipant);
+    const returnAssignee = normalizeAlvaxWakeExecutionPrincipal(stage.returnAssignee);
+    const reviewRequestRaw = parseObject(stage.reviewRequest);
+    const reviewInstructions = asString(reviewRequestRaw.instructions, "").trim();
+    const reviewRequest = reviewInstructions ? { instructions: reviewInstructions } : null;
+    const stageId = asString(stage.stageId, "").trim() || null;
+    const stageType = asString(stage.stageType, "").trim() || null;
+    const lastDecisionOutcome = asString(stage.lastDecisionOutcome, "").trim() || null;
+    if (!wakeRole && !stageId && !stageType && !currentParticipant && !returnAssignee && !reviewRequest && !lastDecisionOutcome && allowedActions.length === 0) {
+        return null;
+    }
+    return {
+        wakeRole,
+        stageId,
+        stageType,
+        currentParticipant,
+        returnAssignee,
+        reviewRequest,
+        lastDecisionOutcome,
+        allowedActions,
+    };
+}
+export function normalizeAlvaxWakePayload(value) {
+    const payload = parseObject(value);
+    const comments = Array.isArray(payload.comments)
+        ? payload.comments
+            .map((entry) => normalizeAlvaxWakeComment(entry))
+            .filter((entry) => Boolean(entry))
+        : [];
+    const commentWindow = parseObject(payload.commentWindow);
+    const commentIds = Array.isArray(payload.commentIds)
+        ? payload.commentIds
+            .filter((entry) => typeof entry === "string" && entry.trim().length > 0)
+            .map((entry) => entry.trim())
+        : [];
+    const executionStage = normalizeAlvaxWakeExecutionStage(payload.executionStage);
+    const continuationSummary = normalizeAlvaxWakeContinuationSummary(payload.continuationSummary);
+    const livenessContinuation = normalizeAlvaxWakeLivenessContinuation(payload.livenessContinuation);
+    const childIssueSummaries = Array.isArray(payload.childIssueSummaries)
+        ? payload.childIssueSummaries
+            .map((entry) => normalizeAlvaxWakeChildIssueSummary(entry))
+            .filter((entry) => Boolean(entry))
+        : [];
+    const unresolvedBlockerIssueIds = Array.isArray(payload.unresolvedBlockerIssueIds)
+        ? payload.unresolvedBlockerIssueIds
+            .map((entry) => asString(entry, "").trim())
+            .filter(Boolean)
+        : [];
+    const unresolvedBlockerSummaries = Array.isArray(payload.unresolvedBlockerSummaries)
+        ? payload.unresolvedBlockerSummaries
+            .map((entry) => normalizeAlvaxWakeBlockerSummary(entry))
+            .filter((entry) => Boolean(entry))
+        : [];
+    const activeTreeHold = normalizeAlvaxWakeTreeHoldSummary(payload.activeTreeHold);
+    if (comments.length === 0 && commentIds.length === 0 && childIssueSummaries.length === 0 && unresolvedBlockerIssueIds.length === 0 && unresolvedBlockerSummaries.length === 0 && !activeTreeHold && !executionStage && !continuationSummary && !livenessContinuation && !normalizeAlvaxWakeIssue(payload.issue)) {
+        return null;
+    }
+    return {
+        reason: asString(payload.reason, "").trim() || null,
+        issue: normalizeAlvaxWakeIssue(payload.issue),
+        checkedOutByHarness: asBoolean(payload.checkedOutByHarness, false),
+        dependencyBlockedInteraction: asBoolean(payload.dependencyBlockedInteraction, false),
+        treeHoldInteraction: asBoolean(payload.treeHoldInteraction, false),
+        activeTreeHold,
+        unresolvedBlockerIssueIds,
+        unresolvedBlockerSummaries,
+        executionStage,
+        continuationSummary,
+        livenessContinuation,
+        interactionKind: asString(payload.interactionKind, "").trim() || null,
+        interactionStatus: asString(payload.interactionStatus, "").trim() || null,
+        childIssueSummaries,
+        childIssueSummaryTruncated: asBoolean(payload.childIssueSummaryTruncated, false),
+        commentIds,
+        latestCommentId: asString(payload.latestCommentId, "").trim() || null,
+        comments,
+        requestedCount: asNumber(commentWindow.requestedCount, comments.length || commentIds.length),
+        includedCount: asNumber(commentWindow.includedCount, comments.length),
+        missingCount: asNumber(commentWindow.missingCount, 0),
+        truncated: asBoolean(payload.truncated, false),
+        fallbackFetchNeeded: asBoolean(payload.fallbackFetchNeeded, false),
+    };
+}
+export function stringifyAlvaxWakePayload(value) {
+    const normalized = normalizeAlvaxWakePayload(value);
+    if (!normalized)
+        return null;
+    return JSON.stringify(normalized);
+}
+export function readAlvaxIssueWorkModeFromContext(value) {
+    const context = parseObject(value);
+    const issue = parseObject(context.alvaxIssue);
+    const direct = asString(issue.workMode, "").trim();
+    if (direct)
+        return direct;
+    const wake = normalizeAlvaxWakePayload(context.alvaxWake);
+    return wake?.issue?.workMode ?? null;
+}
+export function renderAlvaxWakePrompt(value, options = {}) {
+    const normalized = normalizeAlvaxWakePayload(value);
+    if (!normalized)
+        return "";
+    const resumedSession = options.resumedSession === true;
+    const executionStage = normalized.executionStage;
+    const principalLabel = (principal) => {
+        if (!principal || !principal.type)
+            return "unknown";
+        if (principal.type === "agent")
+            return principal.agentId ? `agent ${principal.agentId}` : "agent";
+        return principal.userId ? `user ${principal.userId}` : "user";
+    };
+    const lines = resumedSession
+        ? [
+            "## Alvax Resume Delta",
+            "",
+            "You are resuming an existing Alvax session.",
+            "This heartbeat is scoped to the issue below. Do not switch to another issue until you have handled this wake.",
+            "Focus on the new wake delta below and continue the current task without restating the full heartbeat boilerplate.",
+            "Fetch the API thread only when `fallbackFetchNeeded` is true or you need broader history than this batch.",
+            "",
+            "Execution contract: take concrete action in this heartbeat when the issue is actionable; do not stop at a plan unless planning was requested. Leave durable progress with comments, issue documents, or issue work products, then set a clear final status before ending the heartbeat: `done`, `blocked` with a named unblock owner/action, `in_review` when human review or an issue interaction is genuinely needed, or `in_progress` only when the current run has a real continuation path. Comments, documents, work products, and `Remaining` bullets are evidence, not valid continuation paths by themselves.",
+            "",
+            `- reason: ${normalized.reason ?? "unknown"}`,
+            `- issue: ${normalized.issue?.identifier ?? normalized.issue?.id ?? "unknown"}${normalized.issue?.title ? ` ${normalized.issue.title}` : ""}`,
+            `- pending comments: ${normalized.includedCount}/${normalized.requestedCount}`,
+            `- latest comment id: ${normalized.latestCommentId ?? "unknown"}`,
+            `- fallback fetch needed: ${normalized.fallbackFetchNeeded ? "yes" : "no"}`,
+        ]
+        : [
+            "## Alvax Wake Payload",
+            "",
+            "Treat this wake payload as the highest-priority change for the current heartbeat.",
+            "This heartbeat is scoped to the issue below. Do not switch to another issue until you have handled this wake.",
+            "Before generic repo exploration or boilerplate heartbeat updates, acknowledge the latest comment and explain how it changes your next action.",
+            "Use this inline wake data first before refetching the issue thread.",
+            "Only fetch the API thread when `fallbackFetchNeeded` is true or you need broader history than this batch.",
+            "",
+            "Execution contract: take concrete action in this heartbeat when the issue is actionable; do not stop at a plan unless planning was requested. Leave durable progress with comments, issue documents, or issue work products, then set a clear final status before ending the heartbeat: `done`, `blocked` with a named unblock owner/action, `in_review` when human review or an issue interaction is genuinely needed, or `in_progress` only when the current run has a real continuation path. Comments, documents, work products, and `Remaining` bullets are evidence, not valid continuation paths by themselves.",
+            "",
+            `- reason: ${normalized.reason ?? "unknown"}`,
+            `- issue: ${normalized.issue?.identifier ?? normalized.issue?.id ?? "unknown"}${normalized.issue?.title ? ` ${normalized.issue.title}` : ""}`,
+            `- pending comments: ${normalized.includedCount}/${normalized.requestedCount}`,
+            `- latest comment id: ${normalized.latestCommentId ?? "unknown"}`,
+            `- fallback fetch needed: ${normalized.fallbackFetchNeeded ? "yes" : "no"}`,
+        ];
+    if (normalized.issue?.status) {
+        lines.push(`- issue status: ${normalized.issue.status}`);
+    }
+    if (normalized.issue?.workMode) {
+        lines.push(`- issue work mode: ${normalized.issue.workMode}`);
+    }
+    if (normalized.issue?.priority) {
+        lines.push(`- issue priority: ${normalized.issue.priority}`);
+    }
+    if (normalized.issue?.workMode === "planning") {
+        const hasWakeComments = normalized.comments.length > 0;
+        const acceptedPlanContinuation = !hasWakeComments &&
+            normalized.interactionKind === "request_confirmation" && normalized.interactionStatus === "accepted";
+        let directive = "Make the plan only. Do not write code or perform implementation work.";
+        if (hasWakeComments) {
+            directive = "Update the plan only. Do not write code or perform implementation work.";
+        }
+        if (acceptedPlanContinuation) {
+            directive = "Create child issues from the approved plan only. Do not write code or perform implementation work on the planning issue.";
+        }
+        lines.push(`- planning directive: ${directive}`);
+        if (acceptedPlanContinuation) {
+            lines.push("- accepted-plan continuation: you may create child implementation issues from the approved plan, but must not start implementation work on the planning issue itself");
+        }
+    }
+    if (normalized.checkedOutByHarness) {
+        lines.push("- checkout: already claimed by the harness for this run");
+    }
+    if (normalized.dependencyBlockedInteraction) {
+        lines.push("- dependency-blocked interaction: yes");
+        lines.push("- execution scope: respond or triage the human comment; do not treat blocker-dependent deliverable work as unblocked");
+        if (normalized.unresolvedBlockerSummaries.length > 0) {
+            const blockers = normalized.unresolvedBlockerSummaries
+                .map((blocker) => `${blocker.identifier ?? blocker.id ?? "unknown"}${blocker.title ? ` ${blocker.title}` : ""}${blocker.status ? ` (${blocker.status})` : ""}`)
+                .join("; ");
+            lines.push(`- unresolved blockers: ${blockers}`);
+        }
+        else if (normalized.unresolvedBlockerIssueIds.length > 0) {
+            lines.push(`- unresolved blocker issue ids: ${normalized.unresolvedBlockerIssueIds.join(", ")}`);
+        }
+    }
+    if (normalized.treeHoldInteraction) {
+        lines.push("- tree-hold interaction: yes");
+        lines.push("- execution scope: respond or triage the human comment; the subtree remains paused until an explicit resume action");
+        if (normalized.activeTreeHold) {
+            const hold = normalized.activeTreeHold;
+            lines.push(`- active tree hold: ${hold.holdId ?? "unknown"}${hold.rootIssueId ? ` rooted at ${hold.rootIssueId}` : ""}${hold.mode ? ` (${hold.mode})` : ""}`);
+        }
+    }
+    if (normalized.missingCount > 0) {
+        lines.push(`- omitted comments: ${normalized.missingCount}`);
+    }
+    if (executionStage) {
+        lines.push(`- execution wake role: ${executionStage.wakeRole ?? "unknown"}`, `- execution stage: ${executionStage.stageType ?? "unknown"}`, `- execution participant: ${principalLabel(executionStage.currentParticipant)}`, `- execution return assignee: ${principalLabel(executionStage.returnAssignee)}`, `- last decision outcome: ${executionStage.lastDecisionOutcome ?? "none"}`);
+        if (executionStage.allowedActions.length > 0) {
+            lines.push(`- allowed actions: ${executionStage.allowedActions.join(", ")}`);
+        }
+        if (executionStage.reviewRequest) {
+            lines.push("", "Review request instructions:", executionStage.reviewRequest.instructions);
+        }
+        lines.push("");
+        if (executionStage.wakeRole === "reviewer" || executionStage.wakeRole === "approver") {
+            lines.push(`You are waking as the active ${executionStage.wakeRole} for this issue.`, "Do not execute the task itself or continue executor work.", "Review the issue and choose one of the allowed actions above.", "If you request changes, the workflow routes back to the stored return assignee.", "");
+        }
+        else if (executionStage.wakeRole === "executor") {
+            lines.push("You are waking because changes were requested in the execution workflow.", "Address the requested changes on this issue and resubmit when the work is ready.", "");
+        }
+    }
+    if (normalized.continuationSummary) {
+        lines.push("", "Issue continuation summary:", normalized.continuationSummary.body);
+        if (normalized.continuationSummary.bodyTruncated) {
+            lines.push("[continuation summary truncated]");
+        }
+    }
+    if (normalized.livenessContinuation) {
+        const continuation = normalized.livenessContinuation;
+        lines.push("", "Run liveness continuation:");
+        if (continuation.attempt) {
+            lines.push(`- attempt: ${continuation.attempt}${continuation.maxAttempts ? `/${continuation.maxAttempts}` : ""}`);
+        }
+        if (continuation.sourceRunId) {
+            lines.push(`- source run: ${continuation.sourceRunId}`);
+        }
+        if (continuation.state) {
+            lines.push(`- liveness state: ${continuation.state}`);
+        }
+        if (continuation.reason) {
+            lines.push(`- reason: ${continuation.reason}`);
+        }
+        if (continuation.instruction) {
+            lines.push(`- instruction: ${continuation.instruction}`);
+        }
+    }
+    if (normalized.childIssueSummaries.length > 0) {
+        lines.push("", "Direct child issue summaries:");
+        for (const child of normalized.childIssueSummaries) {
+            const label = child.identifier ?? child.id ?? "unknown";
+            lines.push(`- ${label}${child.title ? ` ${child.title}` : ""}${child.status ? ` (${child.status})` : ""}`);
+            if (child.summary) {
+                lines.push(`  ${child.summary}`);
+            }
+        }
+        if (normalized.childIssueSummaryTruncated) {
+            lines.push("[child issue summaries truncated]");
+        }
+    }
+    if (normalized.checkedOutByHarness) {
+        lines.push("", "The harness already checked out this issue for the current run.", "Do not call `/api/issues/{id}/checkout` again unless you intentionally switch to a different task.", "");
+    }
+    if (normalized.comments.length > 0) {
+        lines.push("New comments in order:");
+    }
+    for (const [index, comment] of normalized.comments.entries()) {
+        const authorLabel = comment.authorId
+            ? `${comment.authorType ?? "unknown"} ${comment.authorId}`
+            : comment.authorType ?? "unknown";
+        lines.push(`${index + 1}. comment ${comment.id ?? "unknown"} at ${comment.createdAt ?? "unknown"} by ${authorLabel}`, comment.body);
+        if (comment.bodyTruncated) {
+            lines.push("[comment body truncated]");
+        }
+        lines.push("");
+    }
+    return lines.join("\n").trim();
+}
+export function redactEnvForLogs(env) {
+    const redacted = {};
+    for (const [key, value] of Object.entries(env)) {
+        redacted[key] = SENSITIVE_ENV_KEY.test(key) ? REDACTED_LOG_VALUE : value;
+    }
+    return redacted;
+}
+export function redactCommandTextForLogs(command) {
+    return redactCommandText(command, REDACTED_LOG_VALUE);
+}
+export function buildInvocationEnvForLogs(env, options = {}) {
+    const merged = { ...env };
+    const runtimeEnv = options.runtimeEnv ?? {};
+    for (const key of options.includeRuntimeKeys ?? []) {
+        if (key in merged)
+            continue;
+        const value = runtimeEnv[key];
+        if (typeof value !== "string" || value.length === 0)
+            continue;
+        merged[key] = value;
+    }
+    const resolvedCommand = options.resolvedCommand?.trim();
+    if (resolvedCommand) {
+        merged[options.resolvedCommandEnvKey ?? "ALVAX_RESOLVED_COMMAND"] = redactCommandTextForLogs(resolvedCommand);
+    }
+    return redactEnvForLogs(merged);
+}
+export function buildAlvaxEnv(agent) {
+    const resolveHostForUrl = (rawHost) => {
+        const host = rawHost.trim();
+        if (!host || host === "0.0.0.0" || host === "::")
+            return "localhost";
+        if (host.includes(":") && !host.startsWith("[") && !host.endsWith("]"))
+            return `[${host}]`;
+        return host;
+    };
+    const vars = {
+        ALVAX_AGENT_ID: agent.id,
+        ALVAX_COMPANY_ID: agent.companyId,
+    };
+    const runtimeHost = resolveHostForUrl(process.env.ALVAX_LISTEN_HOST ?? process.env.HOST ?? "localhost");
+    const runtimePort = process.env.ALVAX_LISTEN_PORT ?? process.env.PORT ?? "3100";
+    const apiUrl = process.env.ALVAX_RUNTIME_API_URL ??
+        process.env.ALVAX_API_URL ??
+        `http://${runtimeHost}:${runtimePort}`;
+    vars.ALVAX_API_URL = apiUrl;
+    return vars;
+}
+export function applyAlvaxWorkspaceEnv(env, input) {
+    const mappings = [
+        ["ALVAX_WORKSPACE_CWD", input.workspaceCwd],
+        ["ALVAX_WORKSPACE_SOURCE", input.workspaceSource],
+        ["ALVAX_WORKSPACE_STRATEGY", input.workspaceStrategy],
+        ["ALVAX_WORKSPACE_ID", input.workspaceId],
+        ["ALVAX_WORKSPACE_REPO_URL", input.workspaceRepoUrl],
+        ["ALVAX_WORKSPACE_REPO_REF", input.workspaceRepoRef],
+        ["ALVAX_WORKSPACE_BRANCH", input.workspaceBranch],
+        ["ALVAX_WORKSPACE_WORKTREE_PATH", input.workspaceWorktreePath],
+        ["AGENT_HOME", input.agentHome],
+    ];
+    for (const [key, value] of mappings) {
+        if (typeof value === "string" && value.length > 0) {
+            env[key] = value;
+        }
+    }
+    return env;
+}
+export function shapeAlvaxWorkspaceEnvForExecution(input) {
+    const workspaceCwd = typeof input.workspaceCwd === "string" && input.workspaceCwd.trim().length > 0
+        ? input.workspaceCwd.trim()
+        : null;
+    const workspaceWorktreePath = typeof input.workspaceWorktreePath === "string" && input.workspaceWorktreePath.trim().length > 0
+        ? input.workspaceWorktreePath.trim()
+        : null;
+    const workspaceHints = Array.isArray(input.workspaceHints) ? input.workspaceHints : [];
+    if (!input.executionTargetIsRemote) {
+        return {
+            workspaceCwd,
+            workspaceWorktreePath,
+            workspaceHints,
+        };
+    }
+    const executionCwd = typeof input.executionCwd === "string" && input.executionCwd.trim().length > 0
+        ? input.executionCwd.trim()
+        : null;
+    // On a remote target we must never fall back to the local workspaceCwd —
+    // doing so leaks host paths into the remote env (the exact failure mode
+    // this helper exists to prevent). Callers are expected to resolve
+    // executionCwd via adapterExecutionTargetRemoteCwd before calling this
+    // helper, which always returns a non-empty string. Surface a warning so
+    // future callers don't silently regress to the leak.
+    if (executionCwd === null) {
+        // eslint-disable-next-line no-console
+        console.warn("[alvax] shapeAlvaxWorkspaceEnvForExecution called with executionCwd=null on a remote target; " +
+            "stripping workspaceCwd to avoid leaking local paths into the remote environment.");
+    }
+    const realizedWorkspaceCwd = executionCwd;
+    const localWorkspaceCwd = workspaceCwd ? path.resolve(workspaceCwd) : null;
+    const shapedWorkspaceHints = workspaceHints.map((hint) => {
+        const nextHint = { ...hint };
+        const hintCwd = typeof nextHint.cwd === "string" ? nextHint.cwd.trim() : "";
+        if (!hintCwd)
+            return nextHint;
+        if (localWorkspaceCwd && path.resolve(hintCwd) === localWorkspaceCwd) {
+            if (realizedWorkspaceCwd) {
+                nextHint.cwd = realizedWorkspaceCwd;
+            }
+            else {
+                delete nextHint.cwd;
+            }
+            return nextHint;
+        }
+        delete nextHint.cwd;
+        return nextHint;
+    });
+    return {
+        workspaceCwd: realizedWorkspaceCwd,
+        workspaceWorktreePath: null,
+        workspaceHints: shapedWorkspaceHints,
+    };
+}
+export function sanitizeInheritedAlvaxEnv(baseEnv) {
+    const env = { ...baseEnv };
+    for (const key of Object.keys(env)) {
+        if (!key.startsWith("ALVAX_"))
+            continue;
+        if (key === "ALVAX_RUNTIME_API_URL")
+            continue;
+        if (key === "ALVAX_LISTEN_HOST")
+            continue;
+        if (key === "ALVAX_LISTEN_PORT")
+            continue;
+        delete env[key];
+    }
+    return env;
+}
+export function defaultPathForPlatform() {
+    if (process.platform === "win32") {
+        return "C:\\Windows\\System32;C:\\Windows;C:\\Windows\\System32\\Wbem";
+    }
+    return "/usr/local/bin:/opt/homebrew/bin:/usr/local/sbin:/usr/bin:/bin:/usr/sbin:/sbin";
+}
+function windowsPathExts(env) {
+    return (env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";").filter(Boolean);
+}
+async function pathExists(candidate) {
+    try {
+        await fs.access(candidate, process.platform === "win32" ? fsConstants.F_OK : fsConstants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function resolveCommandPath(command, cwd, env) {
+    const hasPathSeparator = command.includes("/") || command.includes("\\");
+    if (hasPathSeparator) {
+        const absolute = path.isAbsolute(command) ? command : path.resolve(cwd, command);
+        return (await pathExists(absolute)) ? absolute : null;
+    }
+    const pathValue = env.PATH ?? env.Path ?? "";
+    const delimiter = process.platform === "win32" ? ";" : ":";
+    const dirs = pathValue.split(delimiter).filter(Boolean);
+    const exts = process.platform === "win32" ? windowsPathExts(env) : [""];
+    const hasExtension = process.platform === "win32" && path.extname(command).length > 0;
+    for (const dir of dirs) {
+        const candidates = process.platform === "win32"
+            ? hasExtension
+                ? [path.join(dir, command)]
+                : exts.map((ext) => path.join(dir, `${command}${ext}`))
+            : [path.join(dir, command)];
+        for (const candidate of candidates) {
+            if (await pathExists(candidate))
+                return candidate;
+        }
+    }
+    return null;
+}
+export async function resolveCommandForLogs(command, cwd, env, options = {}) {
+    const remote = options.remoteExecution ?? null;
+    if (remote) {
+        return `ssh://${remote.username}@${remote.host}:${remote.port}/${remote.remoteCwd} :: ${command}`;
+    }
+    return (await resolveCommandPath(command, cwd, env)) ?? command;
+}
+function quoteForCmd(arg) {
+    if (!arg.length)
+        return '""';
+    const escaped = arg.replace(/"/g, '""');
+    return /[\s"&<>|^()]/.test(escaped) ? `"${escaped}"` : escaped;
+}
+export function sanitizeSshRemoteEnv(env, inheritedEnv = process.env) {
+    return sanitizeRemoteExecutionEnv(env, inheritedEnv);
+}
+function resolveWindowsCmdShell(env) {
+    const fallbackRoot = env.SystemRoot || process.env.SystemRoot || "C:\\Windows";
+    return path.join(fallbackRoot, "System32", "cmd.exe");
+}
+async function resolveSpawnTarget(command, args, cwd, env, options = {}) {
+    const remote = options.remoteExecution ?? null;
+    if (remote) {
+        const sshResolved = await resolveCommandPath("ssh", process.cwd(), env);
+        if (!sshResolved) {
+            throw new Error('Command not found in PATH: "ssh"');
+        }
+        const spawnTarget = await buildSshSpawnTarget({
+            spec: remote,
+            command,
+            args,
+            env: Object.fromEntries(Object.entries(options.remoteEnv ?? {}).filter((entry) => typeof entry[1] === "string")),
+        });
+        return {
+            command: sshResolved,
+            args: spawnTarget.args,
+            cwd: process.cwd(),
+            cleanup: spawnTarget.cleanup,
+        };
+    }
+    const resolved = await resolveCommandPath(command, cwd, env);
+    const executable = resolved ?? command;
+    if (process.platform !== "win32") {
+        return { command: executable, args };
+    }
+    if (/\.(cmd|bat)$/i.test(executable)) {
+        // Always use cmd.exe for .cmd/.bat wrappers. Some environments override
+        // ComSpec to PowerShell, which breaks cmd-specific flags like /d /s /c.
+        const shell = resolveWindowsCmdShell(env);
+        const commandLine = [quoteForCmd(executable), ...args.map(quoteForCmd)].join(" ");
+        return {
+            command: shell,
+            args: ["/d", "/s", "/c", commandLine],
+        };
+    }
+    return { command: executable, args };
+}
+export function ensurePathInEnv(env) {
+    if (typeof env.PATH === "string" && env.PATH.length > 0)
+        return env;
+    if (typeof env.Path === "string" && env.Path.length > 0)
+        return env;
+    return { ...env, PATH: defaultPathForPlatform() };
+}
+export async function ensureAbsoluteDirectory(cwd, opts = {}) {
+    if (!path.isAbsolute(cwd)) {
+        throw new Error(`Working directory must be an absolute path: "${cwd}"`);
+    }
+    const assertDirectory = async () => {
+        const stats = await fs.stat(cwd);
+        if (!stats.isDirectory()) {
+            throw new Error(`Working directory is not a directory: "${cwd}"`);
+        }
+    };
+    try {
+        await assertDirectory();
+        return;
+    }
+    catch (err) {
+        const code = err.code;
+        if (!opts.createIfMissing || code !== "ENOENT") {
+            if (code === "ENOENT") {
+                throw new Error(`Working directory does not exist: "${cwd}"`);
+            }
+            throw err instanceof Error ? err : new Error(String(err));
+        }
+    }
+    try {
+        await fs.mkdir(cwd, { recursive: true });
+        await assertDirectory();
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        throw new Error(`Could not create working directory "${cwd}": ${reason}`);
+    }
+}
+export async function resolveAlvaxSkillsDir(moduleDir, additionalCandidates = []) {
+    const candidates = [
+        ...ALVAX_SKILL_ROOT_RELATIVE_CANDIDATES.map((relativePath) => path.resolve(moduleDir, relativePath)),
+        ...additionalCandidates.map((candidate) => path.resolve(candidate)),
+    ];
+    const seenRoots = new Set();
+    for (const root of candidates) {
+        if (seenRoots.has(root))
+            continue;
+        seenRoots.add(root);
+        const isDirectory = await fs.stat(root).then((stats) => stats.isDirectory()).catch(() => false);
+        if (isDirectory)
+            return root;
+    }
+    return null;
+}
+async function readSkillRequired(skillDir) {
+    try {
+        const content = await fs.readFile(path.join(skillDir, "SKILL.md"), "utf8");
+        const normalized = content.replace(/\r\n/g, "\n");
+        if (!normalized.startsWith("---\n"))
+            return true;
+        const closing = normalized.indexOf("\n---\n", 4);
+        if (closing < 0)
+            return true;
+        const frontmatter = normalized.slice(4, closing);
+        return !/^\s*required\s*:\s*false\s*$/m.test(frontmatter);
+    }
+    catch {
+        return true;
+    }
+}
+export async function listAlvaxSkillEntries(moduleDir, additionalCandidates = []) {
+    const root = await resolveAlvaxSkillsDir(moduleDir, additionalCandidates);
+    if (!root)
+        return [];
+    try {
+        const entries = await fs.readdir(root, { withFileTypes: true });
+        const dirs = entries.filter((entry) => entry.isDirectory());
+        return Promise.all(dirs.map(async (entry) => {
+            const skillDir = path.join(root, entry.name);
+            const required = await readSkillRequired(skillDir);
+            return {
+                key: `alvaxai/alvax/${entry.name}`,
+                runtimeName: entry.name,
+                source: skillDir,
+                required,
+                requiredReason: required
+                    ? "Bundled Alvax skills are always available for local adapters."
+                    : null,
+            };
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+export async function readInstalledSkillTargets(skillsHome) {
+    const entries = await fs.readdir(skillsHome, { withFileTypes: true }).catch(() => []);
+    const out = new Map();
+    for (const entry of entries) {
+        const fullPath = path.join(skillsHome, entry.name);
+        const linkedPath = entry.isSymbolicLink() ? await fs.readlink(fullPath).catch(() => null) : null;
+        out.set(entry.name, resolveInstalledEntryTarget(skillsHome, entry.name, entry, linkedPath));
+    }
+    return out;
+}
+export function buildPersistentSkillSnapshot(options) {
+    const { adapterType, availableEntries, desiredSkills, installed, skillsHome, locationLabel, installedDetail, missingDetail, externalConflictDetail, externalDetail, } = options;
+    const availableByKey = new Map(availableEntries.map((entry) => [entry.key, entry]));
+    const desiredSet = new Set(desiredSkills);
+    const entries = [];
+    const warnings = [...(options.warnings ?? [])];
+    for (const available of availableEntries) {
+        const installedEntry = installed.get(available.runtimeName) ?? null;
+        const desired = desiredSet.has(available.key);
+        let state = "available";
+        let managed = false;
+        let detail = null;
+        if (installedEntry?.targetPath === available.source) {
+            managed = true;
+            state = desired ? "installed" : "stale";
+            detail = installedDetail ?? null;
+        }
+        else if (installedEntry) {
+            state = "external";
+            detail = desired ? externalConflictDetail : externalDetail;
+        }
+        else if (desired) {
+            state = "missing";
+            detail = missingDetail;
+        }
+        entries.push({
+            key: available.key,
+            runtimeName: available.runtimeName,
+            desired,
+            managed,
+            state,
+            sourcePath: available.source,
+            targetPath: path.join(skillsHome, available.runtimeName),
+            detail,
+            required: Boolean(available.required),
+            requiredReason: available.requiredReason ?? null,
+            ...buildManagedSkillOrigin(available),
+        });
+    }
+    for (const desiredSkill of desiredSkills) {
+        if (availableByKey.has(desiredSkill))
+            continue;
+        warnings.push(`Desired skill "${desiredSkill}" is not available from the Alvax skills directory.`);
+        entries.push({
+            key: desiredSkill,
+            runtimeName: null,
+            desired: true,
+            managed: true,
+            state: "missing",
+            sourcePath: null,
+            targetPath: null,
+            detail: "Alvax cannot find this skill in the local runtime skills directory.",
+            origin: "external_unknown",
+            originLabel: "External or unavailable",
+            readOnly: false,
+        });
+    }
+    for (const [name, installedEntry] of installed.entries()) {
+        if (availableEntries.some((entry) => entry.runtimeName === name))
+            continue;
+        entries.push({
+            key: name,
+            runtimeName: name,
+            desired: false,
+            managed: false,
+            state: "external",
+            origin: "user_installed",
+            originLabel: "User-installed",
+            locationLabel: skillLocationLabel(locationLabel),
+            readOnly: true,
+            sourcePath: null,
+            targetPath: installedEntry.targetPath ?? path.join(skillsHome, name),
+            detail: externalDetail,
+        });
+    }
+    entries.sort((left, right) => left.key.localeCompare(right.key));
+    return {
+        adapterType,
+        supported: true,
+        mode: "persistent",
+        desiredSkills,
+        entries,
+        warnings,
+    };
+}
+function normalizeConfiguredAlvaxRuntimeSkills(value) {
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    for (const rawEntry of value) {
+        const entry = parseObject(rawEntry);
+        const key = asString(entry.key, asString(entry.name, "")).trim();
+        const runtimeName = asString(entry.runtimeName, asString(entry.name, "")).trim();
+        const source = asString(entry.source, "").trim();
+        if (!key || !runtimeName || !source)
+            continue;
+        out.push({
+            key,
+            runtimeName,
+            source,
+            required: asBoolean(entry.required, false),
+            requiredReason: typeof entry.requiredReason === "string" && entry.requiredReason.trim().length > 0
+                ? entry.requiredReason.trim()
+                : null,
+        });
+    }
+    return out;
+}
+export async function readAlvaxRuntimeSkillEntries(config, moduleDir, additionalCandidates = []) {
+    const configuredEntries = normalizeConfiguredAlvaxRuntimeSkills(config.alvaxRuntimeSkills);
+    if (configuredEntries.length > 0)
+        return configuredEntries;
+    return listAlvaxSkillEntries(moduleDir, additionalCandidates);
+}
+export async function readAlvaxSkillMarkdown(moduleDir, skillKey) {
+    const normalized = skillKey.trim().toLowerCase();
+    if (!normalized)
+        return null;
+    const entries = await listAlvaxSkillEntries(moduleDir);
+    const match = entries.find((entry) => entry.key === normalized);
+    if (!match)
+        return null;
+    try {
+        return await fs.readFile(path.join(match.source, "SKILL.md"), "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+export function readAlvaxSkillSyncPreference(config) {
+    const raw = config.alvaxSkillSync;
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        return { explicit: false, desiredSkills: [] };
+    }
+    const syncConfig = raw;
+    const desiredValues = syncConfig.desiredSkills;
+    const desired = Array.isArray(desiredValues)
+        ? desiredValues
+            .filter((value) => typeof value === "string")
+            .map((value) => value.trim())
+            .filter(Boolean)
+        : [];
+    return {
+        explicit: Object.prototype.hasOwnProperty.call(raw, "desiredSkills"),
+        desiredSkills: Array.from(new Set(desired)),
+    };
+}
+function canonicalizeDesiredAlvaxSkillReference(reference, availableEntries) {
+    const normalizedReference = reference.trim().toLowerCase();
+    if (!normalizedReference)
+        return "";
+    const exactKey = availableEntries.find((entry) => entry.key.trim().toLowerCase() === normalizedReference);
+    if (exactKey)
+        return exactKey.key;
+    const byRuntimeName = availableEntries.filter((entry) => typeof entry.runtimeName === "string" && entry.runtimeName.trim().toLowerCase() === normalizedReference);
+    if (byRuntimeName.length === 1)
+        return byRuntimeName[0].key;
+    const slugMatches = availableEntries.filter((entry) => entry.key.trim().toLowerCase().split("/").pop() === normalizedReference);
+    if (slugMatches.length === 1)
+        return slugMatches[0].key;
+    return normalizedReference;
+}
+export function resolveAlvaxDesiredSkillNames(config, availableEntries) {
+    const preference = readAlvaxSkillSyncPreference(config);
+    const requiredSkills = availableEntries
+        .filter((entry) => entry.required)
+        .map((entry) => entry.key);
+    if (!preference.explicit) {
+        return Array.from(new Set(requiredSkills));
+    }
+    const desiredSkills = preference.desiredSkills
+        .map((reference) => canonicalizeDesiredAlvaxSkillReference(reference, availableEntries))
+        .filter(Boolean);
+    return Array.from(new Set([...requiredSkills, ...desiredSkills]));
+}
+export function writeAlvaxSkillSyncPreference(config, desiredSkills) {
+    const next = { ...config };
+    const raw = next.alvaxSkillSync;
+    const current = typeof raw === "object" && raw !== null && !Array.isArray(raw)
+        ? { ...raw }
+        : {};
+    current.desiredSkills = Array.from(new Set(desiredSkills
+        .map((value) => value.trim())
+        .filter(Boolean)));
+    next.alvaxSkillSync = current;
+    return next;
+}
+export async function ensureAlvaxSkillSymlink(source, target, linkSkill = (linkSource, linkTarget) => fs.symlink(linkSource, linkTarget)) {
+    const resolvedSource = path.resolve(source);
+    const existing = await fs.lstat(target).catch(() => null);
+    if (!existing) {
+        await linkSkill(resolvedSource, target);
+        return "created";
+    }
+    if (!existing.isSymbolicLink()) {
+        return "skipped";
+    }
+    const linkedPath = await fs.readlink(target).catch(() => null);
+    if (!linkedPath)
+        return "skipped";
+    const resolvedLinkedPath = path.resolve(path.dirname(target), linkedPath);
+    if (resolvedLinkedPath === resolvedSource) {
+        return "skipped";
+    }
+    const linkedPathExists = await fs.stat(resolvedLinkedPath).then(() => true).catch(() => false);
+    if (linkedPathExists
+        && !isPreviousAlvaxManagedSkillSymlinkTarget(resolvedSource, target, resolvedLinkedPath)) {
+        return "skipped";
+    }
+    const replaced = await replaceSymlinkAtomically(resolvedSource, target, resolvedLinkedPath, linkSkill);
+    return replaced ? "repaired" : "skipped";
+}
+function isAlvaxManagedMaterializedSkillPath(candidate) {
+    const normalized = normalizePathSlashes(path.resolve(candidate));
+    return normalized.includes("/companies/")
+        && (normalized.includes("/skills/__catalog__/")
+            || normalized.includes("/skills/__runtime__/"));
+}
+function isSkillVersionDirName(runtimeName, candidateName) {
+    return candidateName === runtimeName || candidateName.startsWith(`${runtimeName}--`);
+}
+function isPreviousAlvaxManagedSkillSymlinkTarget(source, target, linkedPath) {
+    if (!isAlvaxManagedMaterializedSkillPath(source) || !isAlvaxManagedMaterializedSkillPath(linkedPath)) {
+        return false;
+    }
+    if (path.dirname(source) !== path.dirname(linkedPath))
+        return false;
+    const runtimeName = path.basename(target);
+    return isSkillVersionDirName(runtimeName, path.basename(source))
+        && isSkillVersionDirName(runtimeName, path.basename(linkedPath));
+}
+async function replaceSymlinkAtomically(source, target, expectedLinkedPath, linkSkill) {
+    const targetDir = path.dirname(target);
+    const tempTarget = path.join(targetDir, `.${path.basename(target)}.tmp-${randomUUID()}`);
+    await linkSkill(source, tempTarget);
+    try {
+        const current = await fs.lstat(target).catch(() => null);
+        if (!current?.isSymbolicLink())
+            return false;
+        const currentLinkedPath = await fs.readlink(target).catch(() => null);
+        if (!currentLinkedPath)
+            return false;
+        if (path.resolve(targetDir, currentLinkedPath) !== expectedLinkedPath)
+            return false;
+        await fs.rename(tempTarget, target);
+        return true;
+    }
+    finally {
+        await fs.rm(tempTarget, { recursive: true, force: true }).catch(() => undefined);
+    }
+}
+async function hashSkillDirectory(root) {
+    const hash = createHash("sha256");
+    async function visit(candidate, relativePath) {
+        const stat = await fs.lstat(candidate);
+        if (stat.isSymbolicLink()) {
+            hash.update(`symlink:${relativePath}\n`);
+            return;
+        }
+        if (stat.isDirectory()) {
+            hash.update(`dir:${relativePath}\n`);
+            const entries = await fs.readdir(candidate, { withFileTypes: true });
+            entries.sort((left, right) => left.name.localeCompare(right.name));
+            for (const entry of entries) {
+                const childRelativePath = relativePath ? `${relativePath}/${entry.name}` : entry.name;
+                await visit(path.join(candidate, entry.name), childRelativePath);
+            }
+            return;
+        }
+        if (stat.isFile()) {
+            hash.update(`file:${relativePath}:${stat.mode}\n`);
+            hash.update(await fs.readFile(candidate));
+            hash.update("\n");
+            return;
+        }
+        hash.update(`other:${relativePath}:${stat.mode}\n`);
+    }
+    await visit(root, "");
+    return hash.digest("hex");
+}
+async function materializedSkillFingerprintMatches(targetRoot, sourceFingerprint) {
+    try {
+        const raw = JSON.parse(await fs.readFile(path.join(targetRoot, MATERIALIZED_SKILL_SENTINEL), "utf8"));
+        const parsed = parseObject(raw);
+        return parsed.version === 1 && parsed.sourceFingerprint === sourceFingerprint;
+    }
+    catch {
+        return false;
+    }
+}
+async function acquireMaterializeLock(lockDir) {
+    await fs.mkdir(path.dirname(lockDir), { recursive: true });
+    const deadline = Date.now() + MATERIALIZED_SKILL_LOCK_STALE_MS;
+    while (true) {
+        try {
+            await fs.mkdir(lockDir);
+            await fs.writeFile(path.join(lockDir, MATERIALIZED_SKILL_LOCK_OWNER), `${JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() })}\n`, "utf8");
+            return async () => {
+                await fs.rm(lockDir, { recursive: true, force: true });
+            };
+        }
+        catch (err) {
+            const code = err && typeof err === "object" ? err.code : null;
+            if (code !== "EEXIST")
+                throw err;
+            if (await removeStaleMaterializeLock(lockDir, MATERIALIZED_SKILL_LOCK_STALE_MS))
+                continue;
+            if (Date.now() >= deadline) {
+                throw new Error(`Timed out waiting for Alvax skill materialization lock at ${lockDir}`);
+            }
+            await new Promise((resolve) => setTimeout(resolve, 50));
+        }
+    }
+}
+function isPidAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        const code = err && typeof err === "object" ? err.code : null;
+        return code === "EPERM";
+    }
+}
+async function removeStaleMaterializeLock(lockDir, staleMs) {
+    const ownerPath = path.join(lockDir, MATERIALIZED_SKILL_LOCK_OWNER);
+    let shouldRemove = false;
+    try {
+        const raw = JSON.parse(await fs.readFile(ownerPath, "utf8"));
+        const owner = parseObject(raw);
+        const pid = typeof owner.pid === "number" ? owner.pid : 0;
+        const createdAt = typeof owner.createdAt === "string" ? Date.parse(owner.createdAt) : Number.NaN;
+        const ageMs = Number.isFinite(createdAt) ? Date.now() - createdAt : staleMs + 1;
+        shouldRemove = !isPidAlive(pid) || ageMs > staleMs;
+    }
+    catch {
+        const stat = await fs.stat(lockDir).catch(() => null);
+        shouldRemove = !stat || Date.now() - stat.mtimeMs > staleMs;
+    }
+    if (!shouldRemove)
+        return false;
+    await fs.rm(lockDir, { recursive: true, force: true }).catch(() => { });
+    return true;
+}
+export async function materializeAlvaxSkillCopy(source, target) {
+    const sourceRoot = path.resolve(source);
+    const targetRoot = path.resolve(target);
+    const relativeTarget = path.relative(sourceRoot, targetRoot);
+    const relativeSource = path.relative(targetRoot, sourceRoot);
+    if (!relativeTarget ||
+        (!relativeTarget.startsWith("..") && !path.isAbsolute(relativeTarget)) ||
+        !relativeSource ||
+        (!relativeSource.startsWith("..") && !path.isAbsolute(relativeSource))) {
+        throw new Error("Refusing to materialize a skill into itself, an ancestor, or one of its descendants.");
+    }
+    const rootStat = await fs.lstat(sourceRoot);
+    if (rootStat.isSymbolicLink()) {
+        throw new Error("Refusing to materialize a skill root that is itself a symlink.");
+    }
+    if (!rootStat.isDirectory()) {
+        throw new Error("Alvax skills must be directories.");
+    }
+    const result = {
+        copiedFiles: 0,
+        skippedSymlinks: [],
+    };
+    const lockDir = `${targetRoot}.lock`;
+    const releaseLock = await acquireMaterializeLock(lockDir);
+    const tempRoot = `${targetRoot}.tmp-${process.pid}-${randomUUID()}`;
+    async function copyEntry(sourcePath, targetPath, relativePath) {
+        const stat = await fs.lstat(sourcePath);
+        if (stat.isSymbolicLink()) {
+            result.skippedSymlinks.push(relativePath || ".");
+            return;
+        }
+        if (stat.isDirectory()) {
+            await fs.mkdir(targetPath, { recursive: true });
+            const entries = await fs.readdir(sourcePath, { withFileTypes: true });
+            entries.sort((left, right) => left.name.localeCompare(right.name));
+            for (const entry of entries) {
+                const childRelativePath = relativePath ? `${relativePath}/${entry.name}` : entry.name;
+                await copyEntry(path.join(sourcePath, entry.name), path.join(targetPath, entry.name), childRelativePath);
+            }
+            return;
+        }
+        if (stat.isFile()) {
+            await fs.mkdir(path.dirname(targetPath), { recursive: true });
+            await fs.copyFile(sourcePath, targetPath, fsConstants.COPYFILE_FICLONE).catch(async () => {
+                await fs.copyFile(sourcePath, targetPath);
+            });
+            await fs.chmod(targetPath, stat.mode).catch(() => { });
+            result.copiedFiles += 1;
+        }
+    }
+    try {
+        const sourceFingerprint = await hashSkillDirectory(sourceRoot);
+        if (await materializedSkillFingerprintMatches(targetRoot, sourceFingerprint))
+            return result;
+        await copyEntry(sourceRoot, tempRoot, "");
+        await fs.writeFile(path.join(tempRoot, MATERIALIZED_SKILL_SENTINEL), `${JSON.stringify({
+            version: 1,
+            sourceFingerprint,
+            copiedFiles: result.copiedFiles,
+            skippedSymlinks: result.skippedSymlinks,
+        }, null, 2)}\n`, "utf8");
+        if (await materializedSkillFingerprintMatches(targetRoot, sourceFingerprint))
+            return result;
+        await fs.rm(targetRoot, { recursive: true, force: true });
+        await fs.rename(tempRoot, targetRoot);
+        return result;
+    }
+    finally {
+        await fs.rm(tempRoot, { recursive: true, force: true }).catch(() => { });
+        await releaseLock();
+    }
+}
+export async function removeMaintainerOnlySkillSymlinks(skillsHome, allowedSkillNames) {
+    const allowed = new Set(Array.from(allowedSkillNames));
+    try {
+        const entries = await fs.readdir(skillsHome, { withFileTypes: true });
+        const removed = [];
+        for (const entry of entries) {
+            if (allowed.has(entry.name))
+                continue;
+            const target = path.join(skillsHome, entry.name);
+            const existing = await fs.lstat(target).catch(() => null);
+            if (!existing?.isSymbolicLink())
+                continue;
+            const linkedPath = await fs.readlink(target).catch(() => null);
+            if (!linkedPath)
+                continue;
+            const resolvedLinkedPath = path.isAbsolute(linkedPath)
+                ? linkedPath
+                : path.resolve(path.dirname(target), linkedPath);
+            if (!isMaintainerOnlySkillTarget(linkedPath) &&
+                !isMaintainerOnlySkillTarget(resolvedLinkedPath)) {
+                continue;
+            }
+            await fs.unlink(target);
+            removed.push(entry.name);
+        }
+        return removed;
+    }
+    catch {
+        return [];
+    }
+}
+export async function ensureCommandResolvable(command, cwd, env, options = {}) {
+    if (options.remoteExecution) {
+        const resolvedSsh = await resolveCommandPath("ssh", process.cwd(), env);
+        if (resolvedSsh)
+            return;
+        throw new Error('Command not found in PATH: "ssh"');
+    }
+    const resolved = await resolveCommandPath(command, cwd, env);
+    if (resolved)
+        return;
+    if (command.includes("/") || command.includes("\\")) {
+        const absolute = path.isAbsolute(command) ? command : path.resolve(cwd, command);
+        throw new Error(`Command is not executable: "${command}" (resolved: "${absolute}")`);
+    }
+    throw new Error(`Command not found in PATH: "${command}"`);
+}
+export async function runChildProcess(runId, command, args, opts) {
+    const onLogError = opts.onLogError ?? ((err, id, msg) => console.warn({ err, runId: id }, msg));
+    return new Promise((resolve, reject) => {
+        const rawMerged = {
+            ...sanitizeInheritedAlvaxEnv(process.env),
+            ...opts.env,
+        };
+        // Strip Claude Code nesting-guard env vars so spawned `claude` processes
+        // don't refuse to start with "cannot be launched inside another session".
+        // These vars leak in when the Alvax server itself is started from
+        // within a Claude Code session (e.g. `npx alvaxai run` in a terminal
+        // owned by Claude Code) or when cron inherits a contaminated shell env.
+        const CLAUDE_CODE_NESTING_VARS = [
+            "CLAUDECODE",
+            "CLAUDE_CODE_ENTRYPOINT",
+            "CLAUDE_CODE_SESSION",
+            "CLAUDE_CODE_PARENT_SESSION",
+        ];
+        for (const key of CLAUDE_CODE_NESTING_VARS) {
+            delete rawMerged[key];
+        }
+        const mergedEnv = ensurePathInEnv(rawMerged);
+        void resolveSpawnTarget(command, args, opts.cwd, mergedEnv, {
+            remoteExecution: opts.remoteExecution ?? null,
+            remoteEnv: opts.remoteExecution ? opts.env : null,
+        })
+            .then((target) => {
+            const child = spawn(target.command, target.args, {
+                cwd: target.cwd ?? opts.cwd,
+                env: mergedEnv,
+                detached: process.platform !== "win32",
+                shell: false,
+                stdio: [opts.stdin != null ? "pipe" : "ignore", "pipe", "pipe"],
+            });
+            const startedAt = new Date().toISOString();
+            const processGroupId = resolveProcessGroupId(child);
+            const spawnPersistPromise = typeof child.pid === "number" && child.pid > 0 && opts.onSpawn
+                ? opts.onSpawn({ pid: child.pid, processGroupId, startedAt }).catch((err) => {
+                    onLogError(err, runId, "failed to record child process metadata");
+                })
+                : Promise.resolve();
+            runningProcesses.set(runId, { child, graceSec: opts.graceSec, processGroupId });
+            let timedOut = false;
+            let stdout = "";
+            let stderr = "";
+            let logChain = Promise.resolve();
+            let terminalResultSeen = false;
+            let terminalCleanupStarted = false;
+            let terminalCleanupTimer = null;
+            let terminalCleanupKillTimer = null;
+            let terminalResultStdoutScanOffset = 0;
+            let terminalResultStderrScanOffset = 0;
+            const clearTerminalCleanupTimers = () => {
+                if (terminalCleanupTimer)
+                    clearTimeout(terminalCleanupTimer);
+                if (terminalCleanupKillTimer)
+                    clearTimeout(terminalCleanupKillTimer);
+                terminalCleanupTimer = null;
+                terminalCleanupKillTimer = null;
+            };
+            const maybeArmTerminalResultCleanup = () => {
+                const terminalCleanup = opts.terminalResultCleanup;
+                if (!terminalCleanup || terminalCleanupStarted || timedOut)
+                    return;
+                if (!terminalResultSeen) {
+                    const stdoutStart = Math.max(0, terminalResultStdoutScanOffset - TERMINAL_RESULT_SCAN_OVERLAP_CHARS);
+                    const stderrStart = Math.max(0, terminalResultStderrScanOffset - TERMINAL_RESULT_SCAN_OVERLAP_CHARS);
+                    const scanOutput = {
+                        stdout: stdout.slice(stdoutStart),
+                        stderr: stderr.slice(stderrStart),
+                    };
+                    terminalResultStdoutScanOffset = stdout.length;
+                    terminalResultStderrScanOffset = stderr.length;
+                    if (scanOutput.stdout.length === 0 && scanOutput.stderr.length === 0)
+                        return;
+                    try {
+                        terminalResultSeen = terminalCleanup.hasTerminalResult(scanOutput);
+                    }
+                    catch (err) {
+                        onLogError(err, runId, "failed to inspect terminal adapter output");
+                    }
+                }
+                if (!terminalResultSeen)
+                    return;
+                if (terminalCleanupTimer)
+                    return;
+                const graceMs = Math.max(0, terminalCleanup.graceMs ?? 5_000);
+                terminalCleanupTimer = setTimeout(() => {
+                    terminalCleanupTimer = null;
+                    if (terminalCleanupStarted || timedOut)
+                        return;
+                    terminalCleanupStarted = true;
+                    signalRunningProcess({ child, processGroupId }, "SIGTERM");
+                    terminalCleanupKillTimer = setTimeout(() => {
+                        terminalCleanupKillTimer = null;
+                        signalRunningProcess({ child, processGroupId }, "SIGKILL");
+                    }, Math.max(1, opts.graceSec) * 1000);
+                }, graceMs);
+            };
+            const timeout = opts.timeoutSec > 0
+                ? setTimeout(() => {
+                    timedOut = true;
+                    clearTerminalCleanupTimers();
+                    signalRunningProcess({ child, processGroupId }, "SIGTERM");
+                    setTimeout(() => {
+                        signalRunningProcess({ child, processGroupId }, "SIGKILL");
+                    }, Math.max(1, opts.graceSec) * 1000);
+                }, opts.timeoutSec * 1000)
+                : null;
+            child.stdout?.on("data", (chunk) => {
+                const readable = child.stdout;
+                if (!readable)
+                    return;
+                readable.pause();
+                const text = String(chunk);
+                stdout = appendWithCap(stdout, text);
+                maybeArmTerminalResultCleanup();
+                logChain = logChain
+                    .then(() => opts.onLog("stdout", text))
+                    .catch((err) => onLogError(err, runId, "failed to append stdout log chunk"))
+                    .finally(() => {
+                    maybeArmTerminalResultCleanup();
+                    resumeReadable(readable);
+                });
+            });
+            child.stderr?.on("data", (chunk) => {
+                const readable = child.stderr;
+                if (!readable)
+                    return;
+                readable.pause();
+                const text = String(chunk);
+                stderr = appendWithCap(stderr, text);
+                maybeArmTerminalResultCleanup();
+                logChain = logChain
+                    .then(() => opts.onLog("stderr", text))
+                    .catch((err) => onLogError(err, runId, "failed to append stderr log chunk"))
+                    .finally(() => {
+                    maybeArmTerminalResultCleanup();
+                    resumeReadable(readable);
+                });
+            });
+            const stdin = child.stdin;
+            if (opts.stdin != null && stdin) {
+                void spawnPersistPromise.finally(() => {
+                    if (child.killed || stdin.destroyed)
+                        return;
+                    stdin.write(opts.stdin);
+                    stdin.end();
+                });
+            }
+            child.on("error", (err) => {
+                if (timeout)
+                    clearTimeout(timeout);
+                clearTerminalCleanupTimers();
+                runningProcesses.delete(runId);
+                void target.cleanup?.();
+                const errno = err.code;
+                const pathValue = mergedEnv.PATH ?? mergedEnv.Path ?? "";
+                const msg = errno === "ENOENT"
+                    ? `Failed to start command "${command}" in "${opts.cwd}". Verify adapter command, working directory, and PATH (${pathValue}).`
+                    : `Failed to start command "${command}" in "${opts.cwd}": ${err.message}`;
+                reject(new Error(msg));
+            });
+            child.on("exit", () => {
+                maybeArmTerminalResultCleanup();
+            });
+            child.on("close", (code, signal) => {
+                if (timeout)
+                    clearTimeout(timeout);
+                clearTerminalCleanupTimers();
+                runningProcesses.delete(runId);
+                void logChain.finally(() => {
+                    void Promise.resolve()
+                        .then(() => target.cleanup?.())
+                        .finally(() => {
+                        resolve({
+                            exitCode: code,
+                            signal,
+                            timedOut,
+                            stdout,
+                            stderr,
+                            pid: child.pid ?? null,
+                            startedAt,
+                        });
+                    });
+                });
+            });
+        })
+            .catch(reject);
+    });
+}
+//# sourceMappingURL=server-utils.js.map