@useorgx/openclaw-plugin 0.4.9 → 0.7.2

package/dist/retro/domain-templates.js

@@ -0,0 +1,297 @@
+import { callLlmJson } from "../http/helpers/llm-client.js";
+const DOMAIN_TEMPLATES = {
+    engineering: {
+        summaryPrefix: "Engineering execution",
+        successWell: [
+            "Delivered implementation changes with focused validation evidence.",
+            "Kept execution scoped to the active slice and avoided unrelated churn.",
+        ],
+        successDecisions: ["No immediate intervention required; keep current engineering execution pattern."],
+        successFollowUps: [
+            {
+                title: "Capture engineering implementation notes for future retros",
+                priority: "p2",
+            },
+        ],
+        failureDecision: "Escalate blocker triage and assign root-cause owner before the next engineering run.",
+        failureFollowUpTitle: "Reproduce failure with a targeted engineering check and patch root cause",
+        failureFollowUpReason: "Engineering runs should converge quickly on reproducible failures and ship a corrective change.",
+    },
+    product: {
+        summaryPrefix: "Product execution",
+        successWell: [
+            "Clarified scope and acceptance criteria for the requested slice.",
+            "Converted ambiguous asks into concrete execution steps.",
+        ],
+        successDecisions: ["Proceed with the current product plan and track any open assumptions."],
+        successFollowUps: [{ title: "Log product assumptions and open questions", priority: "p2" }],
+        failureDecision: "Resolve product scope/acceptance ambiguity with a direct owner decision before retry.",
+        failureFollowUpTitle: "Resolve product requirement ambiguity before next run",
+        failureFollowUpReason: "Product loops fail when acceptance criteria and constraints remain underspecified.",
+    },
+    design: {
+        summaryPrefix: "Design execution",
+        successWell: [
+            "Produced design output aligned with existing system constraints.",
+            "Prioritized usability clarity over decorative changes.",
+        ],
+        successDecisions: ["Continue with the approved design direction and preserve current constraints."],
+        successFollowUps: [{ title: "Attach visual QA checklist for handoff", priority: "p2" }],
+        failureDecision: "Run a blocking UX triage decision and align acceptance checkpoints before rerun.",
+        failureFollowUpTitle: "Run design QA pass and fix blocking UX mismatches",
+        failureFollowUpReason: "Design regressions should be validated with explicit viewport and interaction checks.",
+    },
+    marketing: {
+        summaryPrefix: "Marketing execution",
+        successWell: [
+            "Delivered channel-ready messaging with clear audience targeting.",
+            "Maintained consistent narrative and measurable intent.",
+        ],
+        successDecisions: ["Keep the current campaign direction and monitor defined success signals."],
+        successFollowUps: [{ title: "Record campaign hypotheses and success metrics", priority: "p2" }],
+        failureDecision: "Decide on updated positioning hypothesis before the next marketing execution cycle.",
+        failureFollowUpTitle: "Diagnose marketing execution gap and tighten message-to-metric mapping",
+        failureFollowUpReason: "Marketing outcomes need explicit hypotheses, channel constraints, and measurable goals.",
+    },
+    sales: {
+        summaryPrefix: "Sales execution",
+        successWell: [
+            "Created actionable next steps tied to buyer-stage progression.",
+            "Preserved signal quality for follow-up actions and objections.",
+        ],
+        successDecisions: ["Continue with the current sales motion while maintaining pipeline signal quality."],
+        successFollowUps: [{ title: "Document discovery-to-close handoff notes", priority: "p2" }],
+        failureDecision: "Trigger a sales unblock decision on objection handling and next-step ownership.",
+        failureFollowUpTitle: "Rework sales motion to unblock stalled buyer progression",
+        failureFollowUpReason: "Sales stalls usually reflect missing objection handling or unclear next actions.",
+    },
+    operations: {
+        summaryPrefix: "Operations execution",
+        successWell: [
+            "Stabilized process flow with explicit ownership and runbook alignment.",
+            "Reduced operational risk through controlled scope and sequencing.",
+        ],
+        successDecisions: ["Keep current ops controls and apply runbook deltas from this run."],
+        successFollowUps: [{ title: "Add ops runbook delta from this run", priority: "p2" }],
+        failureDecision: "Escalate operational owner decision to remove the bottleneck before retrying.",
+        failureFollowUpTitle: "Patch operational bottleneck and update runbook controls",
+        failureFollowUpReason: "Operations failures should result in tighter runbooks and clearer owner accountability.",
+    },
+    orchestration: {
+        summaryPrefix: "Orchestration execution",
+        successWell: [
+            "Coordinated dependencies and sequencing across agents effectively.",
+            "Maintained clear control flow for decisions and handoffs.",
+        ],
+        successDecisions: ["Preserve current orchestration sequencing and monitor handoff latency."],
+        successFollowUps: [{ title: "Capture orchestration handoff timing insights", priority: "p2" }],
+        failureDecision: "Request an orchestration sequencing decision to unblock dependency handoffs.",
+        failureFollowUpTitle: "Unblock orchestration handoff failure and re-sequence dependent work",
+        failureFollowUpReason: "Orchestration errors should tighten dependency ordering and handoff contracts.",
+    },
+    general: {
+        summaryPrefix: "Execution",
+        successWell: ["Completed the requested run without runtime error."],
+        successDecisions: ["No immediate action required; continue with the current execution flow."],
+        successFollowUps: [],
+        failureDecision: "Request a human unblock decision before the next retry.",
+        failureFollowUpTitle: "Investigate OpenClaw session failure and unblock task",
+        failureFollowUpReason: "Session ended with error.",
+    },
+};
+function inferDomainFromAgentId(agentId) {
+    const normalized = String(agentId ?? "").trim().toLowerCase();
+    if (!normalized)
+        return "general";
+    const compact = normalized.replace(/[^a-z0-9]/g, "");
+    const tokenSet = new Set(normalized.split(/[^a-z0-9]+/g).filter(Boolean));
+    const hasToken = (...tokens) => tokens.some((token) => tokenSet.has(token));
+    const hasTokenPrefix = (...prefixes) => Array.from(tokenSet).some((token) => prefixes.some((prefix) => token.startsWith(prefix)));
+    if (normalized.includes("sentinel") ||
+        hasToken("sentinel", "watchdog") ||
+        hasTokenPrefix("sentinel", "watch")) {
+        return "orchestration";
+    }
+    if (normalized.includes("engineering") ||
+        normalized.includes("developer") ||
+        hasToken("eng", "dev", "frontend", "backend", "fullstack", "engineer") ||
+        compact.includes("engineering") ||
+        compact.includes("developer")) {
+        return "engineering";
+    }
+    if (normalized.includes("product") ||
+        hasToken("pm", "prod") ||
+        hasTokenPrefix("product", "pm") ||
+        compact.includes("productmanager")) {
+        return "product";
+    }
+    if (normalized.includes("design") || tokenSet.has("ux") || tokenSet.has("ui"))
+        return "design";
+    if (normalized.includes("marketing") ||
+        hasToken("mktg", "growth") ||
+        hasTokenPrefix("mkt", "market")) {
+        return "marketing";
+    }
+    if (normalized.includes("sales") || hasToken("sdr", "ae") || hasTokenPrefix("sales"))
+        return "sales";
+    if (normalized.includes("operations") ||
+        normalized.includes("platform") ||
+        hasToken("ops", "sre", "infra") ||
+        hasTokenPrefix("operat", "platform", "infra")) {
+        return "operations";
+    }
+    if (normalized.includes("orchestrat") ||
+        hasToken("coord", "router") ||
+        hasTokenPrefix("coordinat", "orchestrat", "route")) {
+        return "orchestration";
+    }
+    return "general";
+}
+function isSentinelAgentId(agentId) {
+    const normalized = String(agentId ?? "").trim().toLowerCase();
+    if (!normalized)
+        return false;
+    const compact = normalized.replace(/[^a-z0-9]/g, "");
+    if (normalized.includes("sentinel") || compact.includes("sentinel")) {
+        return true;
+    }
+    const tokenSet = new Set(normalized.split(/[^a-z0-9]+/g).filter(Boolean));
+    return tokenSet.has("watchdog") || Array.from(tokenSet).some((token) => token.startsWith("watch"));
+}
+export function buildRetroTemplateForAgent(input) {
+    const domain = inferDomainFromAgentId(input.agentId);
+    const isSentinel = isSentinelAgentId(input.agentId);
+    const template = DOMAIN_TEMPLATES[domain];
+    const errorMessage = input.errorMessage?.trim() || "Session ended with error.";
+    const summary = input.taskId
+        ? `${template.summaryPrefix} ${input.success ? "completed" : "blocked"} task ${input.taskId}.`
+        : `${template.summaryPrefix} run ${input.success ? "completed" : "blocked"} (session ${input.runId}).`;
+    if (input.success) {
+        return {
+            domain,
+            summary,
+            whatWentWell: template.successWell,
+            whatWentWrong: [],
+            decisions: template.successDecisions,
+            followUps: template.successFollowUps,
+        };
+    }
+    return {
+        domain,
+        summary,
+        whatWentWell: [],
+        whatWentWrong: [errorMessage],
+        decisions: [
+            isSentinel
+                ? "Sentinel: resolve decision to unblock dependency handoffs before retrying this run."
+                : template.failureDecision,
+        ],
+        followUps: [
+            {
+                title: template.failureFollowUpTitle,
+                priority: "p0",
+                reason: domain === "general"
+                    ? errorMessage
+                    : `${template.failureFollowUpReason} Error: ${errorMessage}`,
+            },
+        ],
+    };
+}
+// ---------------------------------------------------------------------------
+// LLM-powered retro generation (falls back to heuristic template above)
+// ---------------------------------------------------------------------------
+const RETRO_SYSTEM_PROMPT = `You generate structured retrospectives for autonomous agent runs. Given the run context, produce a JSON object with these fields: domain (one of: engineering, product, design, marketing, sales, operations, orchestration, general), summary (1 sentence), whatWentWell (1-3 specific items), whatWentWrong (0-3 items, empty if success), decisions (1-2 actionable items), followUps (0-2 items, each with title, priority p0/p1/p2, and reason). Be specific to what actually happened — avoid generic template language.`;
+const VALID_DOMAINS = new Set([
+    "engineering",
+    "product",
+    "design",
+    "marketing",
+    "sales",
+    "operations",
+    "orchestration",
+    "general",
+]);
+const VALID_PRIORITIES = new Set(["p0", "p1", "p2"]);
+/**
+ * Generate a structured retro using an LLM, falling back to the heuristic
+ * template produced by {@link buildRetroTemplateForAgent}.
+ *
+ * Caller: src/index.ts (~line 971) — `buildRetroTemplateForAgent` is invoked
+ * inside the session-stopped handler. Migrate that call site to use this
+ * function when ready to enable LLM-powered retros.
+ */
+export async function buildRetroWithLlm(input) {
+    const lines = [
+        `Agent ID: ${input.agentId ?? "(unknown)"}`,
+        `Outcome: ${input.success ? "success" : "failure"}`,
+        `Task ID: ${input.taskId ?? "(none)"}`,
+        `Run ID: ${input.runId}`,
+    ];
+    if (input.errorMessage) {
+        lines.push(`Error: ${input.errorMessage}`);
+    }
+    if (input.executionContext) {
+        lines.push(`Execution context: ${input.executionContext}`);
+    }
+    const userPrompt = lines.join("\n");
+    function parseRetroJson(raw) {
+        try {
+            const obj = JSON.parse(raw);
+            if (typeof obj.domain !== "string" || !VALID_DOMAINS.has(obj.domain))
+                return null;
+            if (typeof obj.summary !== "string" || obj.summary.length === 0)
+                return null;
+            if (!Array.isArray(obj.whatWentWell) || !obj.whatWentWell.every((v) => typeof v === "string"))
+                return null;
+            if (!Array.isArray(obj.whatWentWrong) || !obj.whatWentWrong.every((v) => typeof v === "string"))
+                return null;
+            if (!Array.isArray(obj.decisions) || !obj.decisions.every((v) => typeof v === "string"))
+                return null;
+            if (!Array.isArray(obj.followUps))
+                return null;
+            const followUps = [];
+            for (const fu of obj.followUps) {
+                if (!fu || typeof fu !== "object")
+                    return null;
+                const rec = fu;
+                if (typeof rec.title !== "string" || rec.title.length === 0)
+                    return null;
+                const entry = { title: rec.title };
+                if (typeof rec.priority === "string" && VALID_PRIORITIES.has(rec.priority)) {
+                    entry.priority = rec.priority;
+                }
+                if (typeof rec.reason === "string") {
+                    entry.reason = rec.reason;
+                }
+                followUps.push(entry);
+            }
+            return {
+                domain: obj.domain,
+                summary: obj.summary,
+                whatWentWell: obj.whatWentWell,
+                whatWentWrong: obj.whatWentWrong,
+                decisions: obj.decisions,
+                followUps,
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    function heuristicFallback() {
+        return buildRetroTemplateForAgent(input);
+    }
+    const response = await callLlmJson({
+        taskId: "retro",
+        systemPrompt: RETRO_SYSTEM_PROMPT,
+        userPrompt,
+        model: "openai/gpt-4.1-mini",
+        maxTokens: 512,
+        temperature: 0.2,
+        cacheTtlMs: 6 * 60 * 60_000, // 6 hours
+    }, parseRetroJson, heuristicFallback);
+    return {
+        ...response.result,
+        source: response.source,
+    };
+}

package/dist/retro/quality-rubric.d.ts

@@ -0,0 +1,33 @@
+import type { OrgxAgentDomain } from "../contracts/types.js";
+export type RetroQualityRubricInput = {
+    success: boolean;
+    hadError: boolean;
+    errorMessage?: string | null;
+    tokens?: number | null;
+    costUsd?: number | null;
+    decisionsCount?: number;
+    followUpsCount?: number;
+    whatWentWrongCount?: number;
+    /** Agent domain for domain-specific scoring modifiers */
+    domain?: OrgxAgentDomain | null;
+    /** Artifact metadata from the registered atomic unit */
+    artifactMetadata?: Record<string, unknown> | null;
+};
+export type RetroQualityRubricResult = {
+    score: number;
+    reasons: string[];
+};
+/**
+ * Compute domain-specific quality modifier based on artifact metadata.
+ * Returns delta (positive = bonus, negative = penalty) and reasons.
+ */
+export declare function computeDomainQualityModifier(domain: OrgxAgentDomain | null | undefined, artifactMetadata: Record<string, unknown> | null | undefined): {
+    delta: number;
+    reasons: string[];
+};
+export declare function computeRetroQualityRubricScore(input: RetroQualityRubricInput): RetroQualityRubricResult;
+export declare function computeRetroQualityWithLlm(input: RetroQualityRubricInput & {
+    executionContext?: string | null;
+}): Promise<RetroQualityRubricResult & {
+    source: "llm" | "heuristic";
+}>;

package/dist/retro/quality-rubric.js

@@ -0,0 +1,213 @@
+import { callLlmJson } from "../http/helpers/llm-client.js";
+function toFiniteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function toNonNegativeCount(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0
+        ? Math.floor(value)
+        : 0;
+}
+/**
+ * Compute domain-specific quality modifier based on artifact metadata.
+ * Returns delta (positive = bonus, negative = penalty) and reasons.
+ */
+export function computeDomainQualityModifier(domain, artifactMetadata) {
+    if (!domain || !artifactMetadata)
+        return { delta: 0, reasons: [] };
+    let delta = 0;
+    const reasons = [];
+    const meta = artifactMetadata;
+    // Helper to check nested dotted paths or flat keys
+    const has = (key) => {
+        if (key in meta && meta[key] != null) {
+            const v = meta[key];
+            if (typeof v === "string")
+                return v.trim().length > 0;
+            if (Array.isArray(v))
+                return v.length > 0;
+            return true;
+        }
+        const parts = key.split(".");
+        let cur = meta;
+        for (const p of parts) {
+            if (cur == null || typeof cur !== "object")
+                return false;
+            cur = cur[p];
+        }
+        if (cur == null)
+            return false;
+        if (typeof cur === "string")
+            return cur.trim().length > 0;
+        if (Array.isArray(cur))
+            return cur.length > 0;
+        return true;
+    };
+    switch (domain) {
+        case "engineering":
+            if (has("verification.tests_passed") || has("verification")) {
+                delta += 1;
+                reasons.push("Engineering artifact includes test verification.");
+            }
+            if (!has("commit_sha")) {
+                delta -= 1;
+                reasons.push("Engineering artifact missing commit_sha.");
+            }
+            break;
+        case "product":
+            if (has("acceptance_criteria")) {
+                delta += 1;
+                reasons.push("Product artifact includes acceptance criteria.");
+            }
+            if (!has("success_metric")) {
+                delta -= 1;
+                reasons.push("Product artifact missing success metric.");
+            }
+            break;
+        case "design":
+            if (has("evidence_url")) {
+                delta += 1;
+                reasons.push("Design artifact includes evidence URL.");
+            }
+            if (!has("tokens_referenced")) {
+                delta -= 1;
+                reasons.push("Design artifact missing token references.");
+            }
+            break;
+        case "marketing":
+            if (has("measurement_hook")) {
+                delta += 1;
+                reasons.push("Marketing artifact includes measurement hook.");
+            }
+            if (!has("audience")) {
+                delta -= 1;
+                reasons.push("Marketing artifact missing target audience.");
+            }
+            break;
+        case "sales":
+            if (has("next_action")) {
+                delta += 1;
+                reasons.push("Sales artifact includes next action.");
+            }
+            if (!has("buyer_stage")) {
+                delta -= 1;
+                reasons.push("Sales artifact missing buyer stage.");
+            }
+            break;
+        case "operations":
+            if (has("rollback_path")) {
+                delta += 1;
+                reasons.push("Operations artifact includes rollback path.");
+            }
+            if (!has("affected_systems")) {
+                delta -= 1;
+                reasons.push("Operations artifact missing affected systems.");
+            }
+            break;
+        case "orchestration":
+            if (has("unblocked_work")) {
+                delta += 1;
+                reasons.push("Orchestration artifact includes unblocked work.");
+            }
+            if (!has("rationale")) {
+                delta -= 1;
+                reasons.push("Orchestration artifact missing rationale.");
+            }
+            break;
+    }
+    return { delta, reasons };
+}
+export function computeRetroQualityRubricScore(input) {
+    let score = input.success ? 5 : 2;
+    const reasons = [];
+    if (input.hadError || (input.errorMessage?.trim() ?? "").length > 0) {
+        score -= 1;
+        reasons.push("Run ended with error signal.");
+    }
+    const followUpsCount = toNonNegativeCount(input.followUpsCount);
+    if (!input.success && followUpsCount < 1) {
+        score -= 1;
+        reasons.push("Failure run missing actionable follow-up.");
+    }
+    const decisionsCount = toNonNegativeCount(input.decisionsCount);
+    if (!input.success && decisionsCount < 1) {
+        score -= 1;
+        reasons.push("Failure run missing decision signal.");
+    }
+    const wrongCount = toNonNegativeCount(input.whatWentWrongCount);
+    if (input.success && wrongCount > 0) {
+        score -= 1;
+        reasons.push("Success run still reported retrospective issues.");
+    }
+    const tokens = toFiniteNumber(input.tokens);
+    if (tokens === null || tokens <= 0) {
+        score -= 1;
+        reasons.push("Missing or invalid token telemetry.");
+    }
+    const costUsd = toFiniteNumber(input.costUsd);
+    if (costUsd !== null && costUsd > 10) {
+        score -= 1;
+        reasons.push("Run cost exceeded preferred threshold ($10).");
+    }
+    // Domain-specific modifiers (stacks with generic signals)
+    const domainMod = computeDomainQualityModifier(input.domain, input.artifactMetadata);
+    score += domainMod.delta;
+    reasons.push(...domainMod.reasons);
+    const normalized = Math.max(1, Math.min(5, Math.round(score)));
+    if (reasons.length === 0) {
+        reasons.push("Outcome met baseline quality rubric expectations.");
+    }
+    return { score: normalized, reasons };
+}
+export async function computeRetroQualityWithLlm(input) {
+    const lines = [
+        `Outcome: ${input.success ? "success" : "failure"}`,
+        `Error present: ${input.hadError || (input.errorMessage?.trim() ?? "").length > 0 ? "yes" : "no"}`,
+    ];
+    if (input.errorMessage?.trim()) {
+        lines.push(`Error message: ${input.errorMessage.trim()}`);
+    }
+    const tokens = toFiniteNumber(input.tokens);
+    if (tokens !== null)
+        lines.push(`Tokens used: ${tokens}`);
+    const costUsd = toFiniteNumber(input.costUsd);
+    if (costUsd !== null)
+        lines.push(`Cost (USD): ${costUsd.toFixed(4)}`);
+    const decisionsCount = toNonNegativeCount(input.decisionsCount);
+    lines.push(`Decisions recorded: ${decisionsCount}`);
+    const followUpsCount = toNonNegativeCount(input.followUpsCount);
+    lines.push(`Follow-ups recorded: ${followUpsCount}`);
+    const issuesCount = toNonNegativeCount(input.whatWentWrongCount);
+    lines.push(`Issues reported: ${issuesCount}`);
+    if (input.executionContext?.trim()) {
+        lines.push(`Execution context: ${input.executionContext.trim()}`);
+    }
+    const userPrompt = lines.join("\n");
+    const systemPrompt = "Score this autonomous agent run on a 1-5 quality scale. Consider: task completion, error handling, resource efficiency, follow-up quality, and decision signals. Return JSON: {\"score\": <1-5>, \"reasons\": [\"...\", ...]}. Each reason should be specific and actionable, not generic.";
+    const { result, source } = await callLlmJson({
+        taskId: "quality_rubric",
+        systemPrompt,
+        userPrompt,
+        model: "openai/gpt-4.1-nano",
+        maxTokens: 256,
+        cacheTtlMs: 12 * 60 * 60_000,
+    }, (raw) => {
+        try {
+            const parsed = JSON.parse(raw);
+            const score = parsed.score;
+            if (typeof score !== "number" || !Number.isInteger(score) || score < 1 || score > 5) {
+                return null;
+            }
+            const reasons = parsed.reasons;
+            if (!Array.isArray(reasons) ||
+                reasons.length === 0 ||
+                !reasons.every((r) => typeof r === "string" && r.length > 0)) {
+                return null;
+            }
+            return { score, reasons };
+        }
+        catch {
+            return null;
+        }
+    }, () => computeRetroQualityRubricScore(input));
+    return { ...result, source };
+}

package/dist/runtime-cleanup.d.ts

@@ -0,0 +1,18 @@
+type CleanupLogger = {
+    info?: (message: string, meta?: Record<string, unknown>) => void;
+    warn?: (message: string, meta?: Record<string, unknown>) => void;
+};
+export declare function cleanupOrgxRuntime(logger?: CleanupLogger): Promise<{
+    watchdog: {
+        pid: number | null;
+        wasRunning: boolean;
+        stopped: boolean;
+    };
+    runs: {
+        attempted: number;
+        stopped: number;
+        failed: number;
+        markedStopped: number;
+    };
+}>;
+export {};

package/dist/runtime-cleanup.js

@@ -0,0 +1,87 @@
+import { pathToFileURL } from "node:url";
+import { markAgentRunStopped, readAgentRuns } from "./agent-run-store.js";
+import { stopGatewayWatchdog } from "./gateway-watchdog.js";
+function isPidAlive(pid) {
+    if (!Number.isFinite(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function sendSignal(pid, signal) {
+    try {
+        process.kill(-pid, signal);
+        return;
+    }
+    catch {
+        // Fall back to direct process kill.
+    }
+    try {
+        process.kill(pid, signal);
+    }
+    catch {
+        // best effort
+    }
+}
+async function stopDetachedPid(pid) {
+    if (!isPidAlive(pid))
+        return true;
+    sendSignal(pid, "SIGTERM");
+    await new Promise((resolve) => setTimeout(resolve, 450));
+    if (isPidAlive(pid)) {
+        sendSignal(pid, "SIGKILL");
+        await new Promise((resolve) => setTimeout(resolve, 200));
+    }
+    return !isPidAlive(pid);
+}
+export async function cleanupOrgxRuntime(logger = console) {
+    const watchdog = await stopGatewayWatchdog(logger);
+    const runningRuns = Object.values(readAgentRuns().runs ?? {}).filter((run) => run?.status === "running");
+    let attempted = 0;
+    let stopped = 0;
+    let failed = 0;
+    let markedStopped = 0;
+    for (const run of runningRuns) {
+        if (!run || typeof run !== "object")
+            continue;
+        attempted += 1;
+        let runStopped = false;
+        if (typeof run.pid === "number" && Number.isFinite(run.pid) && run.pid > 0) {
+            runStopped = await stopDetachedPid(run.pid);
+        }
+        else {
+            runStopped = true;
+        }
+        if (runStopped)
+            stopped += 1;
+        else
+            failed += 1;
+        if (markAgentRunStopped(run.runId)) {
+            markedStopped += 1;
+        }
+    }
+    const summary = {
+        watchdog,
+        runs: { attempted, stopped, failed, markedStopped },
+    };
+    logger.info?.("[orgx] Runtime cleanup summary", summary);
+    return summary;
+}
+function isDirectRun() {
+    const entry = process.argv[1];
+    if (!entry)
+        return false;
+    return import.meta.url === pathToFileURL(entry).href;
+}
+if (isDirectRun()) {
+    cleanupOrgxRuntime().catch((err) => {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(`[orgx] runtime cleanup failed: ${message}`);
+        // Never block uninstall/update for best-effort cleanup.
+        process.exitCode = 0;
+    });
+}

package/dist/services/background.d.ts

@@ -15,6 +15,17 @@ export interface RegisterSyncServiceDeps {
         started: boolean;
         pid?: number | null;
     };
+    stopGatewayWatchdog?: () => Promise<{
+        pid: number | null;
+        wasRunning: boolean;
+        stopped: boolean;
+    }>;
+    stopTrackedAgentRuns?: () => Promise<{
+        attempted: number;
+        stopped: number;
+        failed: number;
+        markedStopped: number;
+    }>;
     doSync: () => Promise<void>;
     scheduleNextSync: () => void;
     setSyncServiceRunning: (running: boolean) => void;