@descryy/mcp 0.11.4 → 0.11.5

package/dist/tools/observe-runtime.js

@@ -1,1901 +0,0 @@
-/**
- * `observe_runtime` — boot or attach to a real application, write what was witnessed into the
- * graph as R4 facts. Composes existing descry-runtime stages, no new mechanism (DEC-NEXT-mcp-
- * runtime-dependency-boundary-for-r4-evidence). `action`/`evidence` (DEC-278), gated by
- * confirmToken + profile safetyLevel (DEC-270). Never emits a denial. */
-import { mkdir } from "node:fs/promises";
-import { dirname, isAbsolute, join } from "node:path";
-import { independentSignalTypes } from "@descryy/ir";
-import { checkNotSensitivePath, checkPathConfinement } from "../path-confinement.js";
-/** A-F6 escape hatches — see path-confinement.ts. */
-const ALLOW_EVIDENCE_PATH_OUTSIDE_REPO_ENV_VAR = "DESCRY_ALLOW_EVIDENCE_PATH_OUTSIDE_REPO";
-const ALLOW_SENSITIVE_LOG_PATH_ENV_VAR = "DESCRY_ALLOW_SENSITIVE_LOG_PATH";
-import { buildGraph, counts, createConfirmedIncidentSource, evictStaleConfirmedIncidentNodes, persistGraph, } from "@descryy/core";
-import { createDatabaseQueryCollector, createPostgresLogSource, createPostgresQueryCollector, } from "@descryy/runtime-database-observation";
-import { evaluateAction, PROFILE_MODES, SAFETY_LEVELS, validateProfile } from "@descryy/runtime-environment-profile";
-import { correlateExecution } from "@descryy/runtime-evidence-correlation";
-import { EvidenceStore } from "@descryy/runtime-evidence-store";
-import { confirmObservedFrontendCaller } from "@descryy/runtime-graph-correlator";
-import { createSourceRootResolver, runInstrumentedExecution } from "@descryy/runtime-orchestrator";
-import { answer, optionalBoolean, optionalEnum, optionalInteger, optionalString, ToolInputError, } from "./kit.js";
-import { cancellationHeadline, cancellationNotes, whenAborted } from "../cancellation.js";
-import { readScenario } from "../scenarios/index.js";
-import { createRuntimeJourneyDrive, projectScenarioToRunPlan, } from "./runtime-journey-drive.js";
-import { loadRuntimeAdapter, RuntimeAdapterLoadError } from "../runtime-registry.js";
-import { writeConfirmedIncident, writeSavedStart } from "../session.js";
-import { runtimeObservedIncident } from "./runtime-incident.js";
-/** Where evidence lands when the call does not say. Beside the graph, not inside it. */
-export const DEFAULT_EVIDENCE_RELATIVE_PATH = join(".descry", "evidence.db");
-/** How long collectors are drained after the services report ready, when unstated. */
-const DEFAULT_OBSERVE_MS = 5_000;
-const DEFAULT_TIMEOUT_MS = 60_000;
-const DEFAULT_READINESS_TIMEOUT_MS = 30_000;
-const READINESS_KINDS = ["http", "tcp-port", "command"];
-const SCHEMA = {
-    type: "object",
-    properties: {
-        profile: {
-            type: "object",
-            description: "The environment this run targets. Every field is declared by you and never inferred from " +
-                "any other (DEC-270): a profile named \"staging\" with safetyLevel \"readOnly\" is read-only, " +
-                "and a profile named \"local\" with safetyLevel \"readOnly\" is too.",
-            properties: {
-                name: { type: "string", description: "Free-form. Matched against no vocabulary anywhere." },
-                url: { type: "string", description: "The target's base URL. Must parse." },
-                safetyLevel: {
-                    type: "string",
-                    // Same constant `describeProfileError` maps INVALID_SAFETY_LEVEL's
-                    // legal values from — one source, so schema and refusal cannot
-                    // drift apart (UAT phase 5, F10).
-                    enum: [...SAFETY_LEVELS],
-                    description: "Booting a service is a write against the target, so \"readOnly\" refuses a run that " +
-                        "spawns anything. A run in which every service uses \"attach\" spawns nothing and is " +
-                        "permitted under \"readOnly\".",
-                },
-                credentialRef: {
-                    type: "string",
-                    description: "An opaque key into a credential store — never the secret itself.",
-                },
-                mode: { type: "string", enum: [...PROFILE_MODES] },
-            },
-            required: ["name", "url", "safetyLevel", "credentialRef", "mode"],
-            additionalProperties: false,
-        },
-        services: {
-            type: "object",
-            description: "One entry per service, keyed by the name evidence will be attributed to. Exactly one of " +
-                "\"command\" or \"attach\" per service. Optional: when omitted, a repository that has a " +
-                "prior successful run's services saved reuses them (disclosed on the reply) — otherwise " +
-                "this call refuses and names that omission as the reason. Supplying this always overrides " +
-                "whatever is saved, and a run that reaches readiness replaces the saved services with " +
-                "this call's own, whichever source they came from.",
-            additionalProperties: {
-                type: "object",
-                properties: {
-                    command: { type: "string", description: "How to start it. Omit when using \"attach\"." },
-                    cwd: {
-                        type: "string",
-                        description: "The directory this service is started in. Relative paths resolve against the " +
-                            "repository root. REQUIRED with \"command\". With \"attach\" it is required only " +
-                            "for a \"command\" readiness check, which is an executable Descry runs in it; for " +
-                            "an \"http\" or \"tcp-port\" check it is not needed at all, because nothing is " +
-                            "started and Descry never executes code in a process it did not spawn.",
-                    },
-                    // Fixes the tool's costliest ergonomic gap: 3 failed runs in one real investigation,
-                    // same root cause, explanation previously living only in a source comment.
-                    port: {
-                        type: "integer",
-                        description: "The port readiness checks against, and the two modes need opposite things from you. " +
-                            "With \"attach\": REQUIRED whenever readiness is \"http\" or \"tcp-port\" — the target " +
-                            "chose its port before Descry saw it, and nothing in a pid or a log path reveals which, " +
-                            "so this is refused up front rather than guessed. With \"command\": omit to get an " +
-                            "ephemeral port, which is passed to your command as PORT; set it only if your command " +
-                            "hardcodes a port, and then it must be THAT port — a readiness check against a port " +
-                            "your command did not bind fails while the service is perfectly healthy.",
-                    },
-                    dependsOn: {
-                        type: "array",
-                        items: { type: "string" },
-                        description: "Service names that must be ready first. Declared, never inferred.",
-                    },
-                    env: { type: "object", additionalProperties: { type: "string" } },
-                    attach: {
-                        type: "object",
-                        description: "Observe a process that is already running instead of spawning one. Descry never " +
-                            "executes code in, signals, or applies resource limits to a process it did not spawn.",
-                        properties: {
-                            pid: { type: "integer" },
-                            logFilePath: {
-                                type: "string",
-                                description: "A file the target already writes its stdout/stderr to.",
-                            },
-                        },
-                        required: ["pid", "logFilePath"],
-                        additionalProperties: false,
-                    },
-                    readiness: {
-                        type: "object",
-                        description: "Required per service — a run refuses rather than treat \"the process started\" as " +
-                            "\"the service is up\". Only the three mechanisms expressible as JSON are offered here; " +
-                            "\"log-pattern\" and \"custom-hook\" need a function and are not reachable through this " +
-                            "tool, which is disclosed on every call rather than left to be discovered.",
-                        properties: {
-                            kind: { type: "string", enum: [...READINESS_KINDS] },
-                            path: {
-                                type: "string",
-                                description: "kind \"http\": path appended to http://127.0.0.1:<resolved port>. Defaults to \"/\".",
-                            },
-                            expectedStatus: { type: "integer", description: "kind \"http\": defaults to any 2xx/3xx." },
-                            host: { type: "string", description: "kind \"tcp-port\": defaults to 127.0.0.1." },
-                            command: { type: "string", description: "kind \"command\": the executable to run." },
-                            args: { type: "array", items: { type: "string" }, description: "kind \"command\"." },
-                            timeoutMs: { type: "integer", description: `Defaults to ${DEFAULT_READINESS_TIMEOUT_MS}.` },
-                        },
-                        required: ["kind"],
-                        additionalProperties: false,
-                    },
-                },
-                required: ["readiness"],
-                additionalProperties: false,
-            },
-        },
-        adapter: {
-            type: "object",
-            description: "The runtime adapter to observe with, named as a module specifier and imported at run time. " +
-                "This server depends on none of descry-runtime's per-language runtime adapters by design, and " +
-                "names none of them anywhere — including here, which is why this description carries no " +
-                "example specifier. Install the one matching the service's runtime alongside this server and " +
-                "name its package here; descry-runtime publishes one runtime adapter package per supported " +
-                "runtime, and its README lists them.",
-            properties: {
-                module: { type: "string" },
-                export: {
-                    type: "string",
-                    description: "Defaults to the single export matching create*RuntimeAdapter. Two matches is an error, " +
-                        "not a coin toss — name one here.",
-                },
-                options: { type: "object", description: "Passed to the factory. Adapter-specific and opaque here." },
-            },
-            required: ["module"],
-            additionalProperties: false,
-        },
-        scopeByService: {
-            type: "object",
-            description: "Service name → which repository its symbols resolve in. A service with no entry has its " +
-                "symbol evidence left alone and its name reported, never resolved against a repository " +
-                "nobody named. Defaults to this session's own repo for every declared service.",
-            additionalProperties: {
-                type: "object",
-                properties: {
-                    repo: { type: "string" },
-                    repoRoot: { type: "string", description: "Absolute on-disk root, so observed absolute paths translate exactly." },
-                    cwd: { type: "string" },
-                },
-                required: ["repo"],
-                additionalProperties: false,
-            },
-        },
-        observeForMs: {
-            type: "integer",
-            description: `How long to drain collector output after the services are up. Defaults to ${DEFAULT_OBSERVE_MS}. ` +
-                "There is no \"the application is done\" signal at this layer — a server runs until stopped — " +
-                "so you state the observation window rather than this tool guessing at one.",
-        },
-        timeoutMs: { type: "integer", description: `Whole-execution budget. Defaults to ${DEFAULT_TIMEOUT_MS}.` },
-        environmentTier: {
-            type: "string",
-            enum: ["tier-0-ci-attached", "tier-1-preview", "tier-2-container", "tier-2b-api-only", "tier-3-static-only"],
-            description: "Recorded on the execution. Defaults to \"tier-2-container\" and is deliberately not derived " +
-                "from \"profile.mode\" — DEC-270's rule is that a declared field is declared, not inferred " +
-                "from a neighbouring one.",
-        },
-        fidelityLevel: {
-            type: "integer",
-            enum: [1, 2, 3, 4],
-            description: "1 rule-aware stub · 2 real code + disposable DB · 3 real code + redacted recordings · " +
-                "4 real staging. Defaults to 2. Not derived from anything else, same reason as environmentTier.",
-        },
-        evidencePath: {
-            type: "string",
-            description: `Where the evidence database lives. Defaults to ${DEFAULT_EVIDENCE_RELATIVE_PATH} under the repository root.`,
-        },
-        resourceLimits: {
-            type: "object",
-            description: "A-F5: caps on a spawned service, enforced by the OS (prlimit) — never applied to an attached " +
-                "service, since Descry did not start it. Absent means unconstrained, which every reply discloses.",
-            properties: {
-                maxMemoryBytes: { type: "integer", description: "Virtual address space cap (prlimit --as)." },
-                maxCpuSeconds: { type: "integer", description: "CPU time cap, in seconds (prlimit --cpu)." },
-                maxProcesses: { type: "integer", description: "Process count cap, per real uid (prlimit --nproc)." },
-            },
-            additionalProperties: false,
-        },
-        filesystemPolicy: {
-            type: "object",
-            description: "A-F5: confines a spawned service's filesystem view to its own cwd plus these roots — real on " +
-                "Linux (a bwrap mount namespace; everything else is not merely unreadable, it is not mounted at " +
-                "all), refused rather than silently unenforced elsewhere. Absent means unconstrained.",
-            properties: {
-                allowedRoots: {
-                    type: "array",
-                    items: { type: "string" },
-                    description: "Absolute paths visible read-write in addition to the service's own cwd.",
-                },
-            },
-            required: ["allowedRoots"],
-            additionalProperties: false,
-        },
-        networkPolicy: {
-            type: "object",
-            description: 'A-F5: only { mode: "allow", hosts: [] } (full denial) is actually enforced today — a network ' +
-                "namespace holding nothing but an unreachable loopback. Any other shape refuses the run rather " +
-                "than starting unconstrained under a policy nobody enforced. Absent means unconstrained.",
-            properties: {
-                mode: { type: "string", enum: ["allow", "deny"] },
-                hosts: { type: "array", items: { type: "string" } },
-            },
-            required: ["mode", "hosts"],
-            additionalProperties: false,
-        },
-        sandboxBackend: {
-            type: "string",
-            enum: ["bwrap", "container"],
-            description: 'Which mechanism enforces filesystemPolicy/networkPolicy. Defaults to "bwrap" (Linux-native). ' +
-                '"container" routes through a real Docker container instead — the only option on macOS/Windows, ' +
-                "and it does not compose with resourceLimits (disclosed on the reply when both are declared).",
-        },
-        confirmToken: {
-            type: "string",
-            description: "The token returned by an unconfirmed call. This tool performs nothing without it: the first " +
-                "call describes what running would do and returns a token, and only a second call presenting " +
-                "that exact token runs anything — with the arguments frozen when the token was minted, never " +
-                "whatever the second call supplies. A conflicting argument on the confirming call is " +
-                "discarded rather than applied, and the reply discloses which ones were.",
-        },
-        journey: {
-            type: "object",
-            description: "RG-4 — drive a real browser inside THIS run's readiness window, so browser and backend " +
-                "evidence land in the same evidence store under the same executionId, rather than requiring " +
-                "a separate browser_start_session call against an app that may no longer be in the state this " +
-                "run put it in. Optional: omitted means backend-only, exactly as before. Declare exactly one " +
-                "of \"scenario\" or \"startUrl\". No journey is invented — a scenario with no steps, or " +
-                "startUrl alone, navigates and observes without interacting with anything.",
-            properties: {
-                service: {
-                    type: "string",
-                    description: "Which declared service this browser evidence is attributed to. Optional.",
-                },
-                scenario: {
-                    type: "string",
-                    description: "The name of a committed scenario under descry/scenarios/ (see browser_save_scenario), " +
-                        "replayed inside this run's readiness window. Its own targetUrl is used as the start URL.",
-                },
-                startUrl: {
-                    type: "string",
-                    description: "Navigate here and observe, with no saved scenario and no steps. Mutually exclusive with \"scenario\".",
-                },
-                recordVideo: {
-                    type: "boolean",
-                    description: "RG-6. Off by default. Captured after the drive completes and returned as a VIDEO evidence artifact.",
-                },
-                headless: { type: "boolean", description: "Defaults to true." },
-                settleForMs: {
-                    type: "integer",
-                    description: "How long to keep the page alive after the last step so async console/network activity it provoked actually arrives. Defaults to 1000.",
-                },
-            },
-            additionalProperties: false,
-        },
-        database: {
-            type: "object",
-            description: "RG-5(c) — the database channel. Node services get the node:sqlite observation preload " +
-                "automatically (no declaration needed); this argument is for Postgres, whose statement log " +
-                "lives on the server, not in a spawned service's own output. Declares where to tail it from, " +
-                "so real queries issued during this run's observation window become DATABASE_QUERY evidence. " +
-                "Omit entirely for no Postgres channel — the reply discloses that rather than staying silent.",
-            properties: {
-                statementLog: {
-                    type: "object",
-                    description: "Never turns Postgres logging on — reads whatever the deployment already produces.",
-                    properties: {
-                        kind: { type: "string", enum: ["file", "dockerContainer"] },
-                        path: { type: "string", description: "kind \"file\": a log file the deployment already writes to." },
-                        container: { type: "string", description: "kind \"dockerContainer\": tails `docker logs -f` for this container." },
-                    },
-                    required: ["kind"],
-                    additionalProperties: false,
-                },
-                service: {
-                    type: "string",
-                    description: "Which declared service this DATABASE_QUERY evidence is attributed to. Optional.",
-                },
-            },
-            required: ["statementLog"],
-            additionalProperties: false,
-        },
-    },
-    required: ["profile", "adapter"],
-    additionalProperties: false,
-};
-function asRecord(value, what) {
-    if (typeof value !== "object" || value === null || Array.isArray(value)) {
-        throw new ToolInputError(`"${what}" must be an object`);
-    }
-    return value;
-}
-/**
- * `validateProfile`'s bare machine codes, mapped to a sentence naming what would
- * satisfy them — generated from `SAFETY_LEVELS`/`PROFILE_MODES`, the same constants
- * the schema's own `enum`s are built from above, so the two cannot drift (UAT phase
- * 5, F10). The codes without a closed value set (`EMPTY_NAME`, `INVALID_URL`, …)
- * still get a plain-language sentence rather than reaching the caller verbatim —
- * consistency, not just the two enum cases.
- */
-function describeProfileError(code) {
-    switch (code) {
-        case "EMPTY_NAME":
-            return '"profile.name" must not be empty';
-        case "EMPTY_CREDENTIAL_REF":
-            return '"profile.credentialRef" must not be empty';
-        case "INVALID_URL":
-            return '"profile.url" must be a URL the URL constructor can parse';
-        case "INVALID_SAFETY_LEVEL":
-            return `"profile.safetyLevel" must be one of: ${SAFETY_LEVELS.join(", ")}`;
-        case "INVALID_MODE":
-            return `"profile.mode" must be one of: ${PROFILE_MODES.join(", ")}`;
-        case "REMOTE_LOG_SOURCE_NOT_ALLOWED_FOR_MODE":
-            return ('"profile.remoteLogSource" is not allowed when "profile.mode" is "localBooted" or ' +
-                '"localAttached" — DEC-271\'s remote-log-ingestion mechanism only applies to "remote"/"production"');
-    }
-}
-function readProfile(args) {
-    const raw = asRecord(args["profile"], "profile");
-    // Collect, don't short-circuit (UAT phase 5, F10): the old `field()` threw on
-    // the first key that was not a string, costing up to five round trips to
-    // enumerate five required fields ("seven refusals, one field at a time" in
-    // one real investigation). Every field is checked before anything is thrown,
-    // so a caller learns the whole shape of what is wrong in one call.
-    const shapeErrors = [];
-    const field = (key) => {
-        const value = raw[key];
-        if (typeof value !== "string") {
-            shapeErrors.push(`"profile.${key}" must be a string`);
-            return undefined;
-        }
-        return value;
-    };
-    const name = field("name");
-    const url = field("url");
-    const safetyLevel = field("safetyLevel");
-    const credentialRef = field("credentialRef");
-    const mode = field("mode");
-    if (shapeErrors.length > 0) {
-        throw new ToolInputError(`"profile" is not valid: ${shapeErrors.join("; ")}`);
-    }
-    const candidate = {
-        name: name,
-        url: url,
-        safetyLevel: safetyLevel,
-        credentialRef: credentialRef,
-        mode: mode,
-    };
-    const errors = validateProfile(candidate);
-    if (errors.length > 0) {
-        throw new ToolInputError(`"profile" is not valid: ${errors.map(describeProfileError).join("; ")}`);
-    }
-    return candidate;
-}
-function readAdapterSpec(args) {
-    const raw = asRecord(args["adapter"], "adapter");
-    const module = raw["module"];
-    if (typeof module !== "string" || module === "") {
-        throw new ToolInputError('"adapter.module" is required and must be a non-empty string');
-    }
-    const exportName = raw["export"];
-    if (exportName !== undefined && typeof exportName !== "string") {
-        throw new ToolInputError('"adapter.export" must be a string');
-    }
-    const options = raw["options"];
-    if (options !== undefined && (typeof options !== "object" || options === null)) {
-        throw new ToolInputError('"adapter.options" must be an object');
-    }
-    return {
-        module,
-        ...(typeof exportName === "string" ? { export: exportName } : {}),
-        ...(options === undefined ? {} : { options: options }),
-    };
-}
-/** `readiness`'s raw JSON, captured as `SavedServiceStart.readiness` — before `readReadiness`
- *  turns it into a closure that cannot be serialised. Reads the same fields `readReadiness`
- *  itself validates, so this can only be called after that validation has already run. */
-function toSavedReadiness(raw) {
-    const entry = asRecord(raw, "readiness");
-    const kind = entry["kind"];
-    const path = typeof entry["path"] === "string" ? entry["path"] : undefined;
-    const expectedStatus = typeof entry["expectedStatus"] === "number" ? entry["expectedStatus"] : undefined;
-    const host = typeof entry["host"] === "string" ? entry["host"] : undefined;
-    const command = typeof entry["command"] === "string" ? entry["command"] : undefined;
-    const rawArgs = entry["args"];
-    const args = Array.isArray(rawArgs) ? rawArgs : undefined;
-    const timeoutMs = typeof entry["timeoutMs"] === "number" ? entry["timeoutMs"] : undefined;
-    return {
-        kind,
-        ...(path === undefined ? {} : { path }),
-        ...(expectedStatus === undefined ? {} : { expectedStatus }),
-        ...(host === undefined ? {} : { host }),
-        ...(command === undefined ? {} : { command }),
-        ...(args === undefined ? {} : { args }),
-        ...(timeoutMs === undefined ? {} : { timeoutMs }),
-    };
-}
-/** Rebuilds `DeclaredService[]` from what a prior successful run saved — the reuse path
- *  (build item 3). `envNames` are re-read from THIS process's own environment, never from
- *  disk: nothing here ever held a value to begin with. A name with nothing currently set
- *  under it is reported back via `missingSavedEnv` rather than silently passing `undefined`
- *  through — the caller (`run`) discloses it, per rule 7. */
-function declaredFromSaved(saved, repoPath) {
-    const missingSavedEnv = [];
-    const declared = Object.entries(saved.services).map(([name, svc]) => {
-        const cwd = isAbsolute(svc.cwd) ? svc.cwd : join(repoPath, svc.cwd);
-        const env = {};
-        for (const key of svc.envNames ?? []) {
-            const value = process.env[key];
-            if (value === undefined)
-                missingSavedEnv.push(`${name}.${key}`);
-            else
-                env[key] = value;
-        }
-        const configuration = {
-            ...(svc.command === undefined ? {} : { command: svc.command }),
-            cwd,
-            ...(svc.port === undefined ? {} : { port: svc.port }),
-            ...(svc.dependsOn === undefined ? {} : { dependsOn: svc.dependsOn }),
-            ...(Object.keys(env).length === 0 ? {} : { env }),
-            ...(svc.attach === undefined ? {} : { attach: svc.attach }),
-        };
-        return {
-            name,
-            configuration,
-            readiness: readReadiness(svc.readiness, name, cwd),
-            attached: svc.attach !== undefined,
-            savable: svc,
-        };
-    });
-    return { declared, missingSavedEnv };
-}
-/** A saved command or attach target, named plainly for a refusal/failure note (build item
- *  4) — never the whole saved shape, which would bury the one fact ("this is what didn't
- *  work") a caller needs to read at a glance. */
-function describeSavedCommands(declared) {
-    return declared
-        .map((service) => service.attached
-        ? `${service.name}: attach to pid ${String(service.configuration.attach?.pid ?? "?")}`
-        : `${service.name}: "${service.configuration.command ?? "?"}"`)
-        .join("; ");
-}
-function readServices(args, repoPath, savedFallback) {
-    const rawServices = args["services"];
-    if (rawServices === undefined) {
-        if (savedFallback === undefined || Object.keys(savedFallback.services).length === 0) {
-            throw new ToolInputError('"services" must declare at least one service, and no start settings have been saved yet ' +
-                "for this repository. Declare it once with a run that reaches readiness and this tool " +
-                "remembers it — after that, \"services\" can be omitted and the saved settings are " +
-                "reused, disclosed on every call that reuses them.");
-        }
-        const { declared, missingSavedEnv } = declaredFromSaved(savedFallback, repoPath);
-        return { declared, usedSaved: true, missingSavedEnv };
-    }
-    const raw = asRecord(rawServices, "services");
-    const names = Object.keys(raw);
-    if (names.length === 0)
-        throw new ToolInputError('"services" must declare at least one service');
-    const declared = names.map((name) => {
-        const entry = asRecord(raw[name], `services.${name}`);
-        const command = entry["command"];
-        const attachRaw = entry["attach"];
-        if ((command === undefined) === (attachRaw === undefined)) {
-            throw new ToolInputError(`services.${name} must declare exactly one of "command" or "attach" — ` +
-                (command === undefined ? "it declares neither" : "it declares both"));
-        }
-        if (command !== undefined && typeof command !== "string") {
-            throw new ToolInputError(`"services.${name}.command" must be a string`);
-        }
-        // Read once: two rules below need it (whether cwd is required, whether attach needs a port).
-        const readinessRaw = entry["readiness"];
-        const readinessKind = typeof readinessRaw === "object" && readinessRaw !== null && !Array.isArray(readinessRaw)
-            ? readinessRaw["kind"]
-            : undefined;
-        // cwd required only where something executes in it: attach never runs code Descry didn't
-        // spawn, so http/tcp-port checks leave it inert; a "command" check does execute (DEC-388).
-        const cwdRaw = entry["cwd"];
-        if (cwdRaw !== undefined && (typeof cwdRaw !== "string" || cwdRaw === "")) {
-            throw new ToolInputError(`"services.${name}.cwd" must be a non-empty string`);
-        }
-        if (cwdRaw === undefined && attachRaw === undefined) {
-            throw new ToolInputError(`"services.${name}.cwd" is required and must be a non-empty string: it is the directory ` +
-                `"${name}" is started in.`);
-        }
-        if (cwdRaw === undefined && attachRaw !== undefined && readinessKind === "command") {
-            throw new ToolInputError(`"services.${name}.cwd" is required when "${name}" uses "attach" with a "command" ` +
-                "readiness check: the check is an executable Descry runs, and it runs in this " +
-                "directory. Attaching needs no cwd otherwise — nothing is started.");
-        }
-        const cwd = cwdRaw ?? repoPath;
-        const port = entry["port"];
-        if (port !== undefined && (typeof port !== "number" || !Number.isInteger(port) || port < 0)) {
-            throw new ToolInputError(`"services.${name}.port" must be a non-negative integer`);
-        }
-        const dependsOn = entry["dependsOn"];
-        if (dependsOn !== undefined &&
-            (!Array.isArray(dependsOn) || dependsOn.some((d) => typeof d !== "string"))) {
-            throw new ToolInputError(`"services.${name}.dependsOn" must be an array of strings`);
-        }
-        const env = entry["env"];
-        if (env !== undefined) {
-            const record = asRecord(env, `services.${name}.env`);
-            for (const [key, value] of Object.entries(record)) {
-                if (typeof value !== "string") {
-                    throw new ToolInputError(`"services.${name}.env.${key}" must be a string`);
-                }
-            }
-        }
-        let attach;
-        if (attachRaw !== undefined) {
-            const a = asRecord(attachRaw, `services.${name}.attach`);
-            const pid = a["pid"];
-            const logFilePath = a["logFilePath"];
-            if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0) {
-                throw new ToolInputError(`"services.${name}.attach.pid" must be a positive integer`);
-            }
-            if (typeof logFilePath !== "string" || logFilePath === "") {
-                throw new ToolInputError(`"services.${name}.attach.logFilePath" is required`);
-            }
-            // A-F6: logFilePath is read in full on every poll and can't be root-confined (a real
-            // log lives anywhere) — narrower, disclosed name-based check instead (path-confinement.ts).
-            const sensitivity = checkNotSensitivePath(logFilePath, ALLOW_SENSITIVE_LOG_PATH_ENV_VAR);
-            if (sensitivity.sensitive) {
-                throw new ToolInputError(`"services.${name}.attach.logFilePath": ${sensitivity.reason}`);
-            }
-            attach = { pid, logFilePath };
-            // An attached service's port can't be allocated or inferred — nothing in a pid or log
-            // path reveals it. Left as `port ?? 0` it silently times out against port 0; refused
-            // here by name instead (cost a full failed run to rediscover, twice). Not for "command"
-            // checks, which never ask where the service listens.
-            if ((readinessKind === "http" || readinessKind === "tcp-port") && port === undefined) {
-                throw new ToolInputError(`"services.${name}.port" is required when "${name}" uses "attach" with a ` +
-                    `"${readinessKind}" readiness check: the check needs a port and an attached target's ` +
-                    "port cannot be allocated or inferred — it is whatever the already-running process " +
-                    "bound. State it, or use a \"command\" readiness check, which needs none.");
-            }
-        }
-        const configuration = {
-            ...(typeof command === "string" ? { command } : {}),
-            cwd: isAbsolute(cwd) ? cwd : join(repoPath, cwd),
-            ...(port === undefined ? {} : { port: port }),
-            ...(dependsOn === undefined ? {} : { dependsOn: dependsOn }),
-            ...(env === undefined ? {} : { env: env }),
-            ...(attach === undefined ? {} : { attach }),
-        };
-        const savable = {
-            ...(typeof command === "string" ? { command } : {}),
-            cwd: configuration.cwd,
-            ...(port === undefined ? {} : { port: port }),
-            ...(dependsOn === undefined ? {} : { dependsOn: dependsOn }),
-            // Names only — see this file's own header and SavedServiceStart's doc. Never `env` itself.
-            ...(env === undefined ? {} : { envNames: Object.keys(env) }),
-            ...(attach === undefined ? {} : { attach }),
-            readiness: toSavedReadiness(entry["readiness"]),
-        };
-        return {
-            name,
-            configuration,
-            readiness: readReadiness(entry["readiness"], name, configuration.cwd),
-            attached: attach !== undefined,
-            savable,
-        };
-    });
-    return { declared, usedSaved: false, missingSavedEnv: [] };
-}
-/** JSON→ReadinessCheck mapping. `log-pattern`/`custom-hook` can't survive a JSON boundary
- *  (one closes over a live process, the other is a function) — absent from the enum and
- *  stated in disclosures instead (rule 7, applied to a capability, not just a result). */
-function readReadiness(raw, service, cwd) {
-    const entry = asRecord(raw, `services.${service}.readiness`);
-    const kind = entry["kind"];
-    if (typeof kind !== "string" || !READINESS_KINDS.includes(kind)) {
-        throw new ToolInputError(`"services.${service}.readiness.kind" must be one of: ${READINESS_KINDS.join(", ")}`);
-    }
-    const timeoutMs = entry["timeoutMs"];
-    if (timeoutMs !== undefined &&
-        (typeof timeoutMs !== "number" || !Number.isInteger(timeoutMs) || timeoutMs < 1)) {
-        throw new ToolInputError(`"services.${service}.readiness.timeoutMs" must be a positive integer`);
-    }
-    // Validated here, not lazily inside checks() — the controller only calls checks() after
-    // spawning, so a bad argument caught late means a live process to clean up.
-    const path = typeof entry["path"] === "string" ? entry["path"] : "/";
-    const expectedStatus = entry["expectedStatus"];
-    if (expectedStatus !== undefined && typeof expectedStatus !== "number") {
-        throw new ToolInputError(`"services.${service}.readiness.expectedStatus" must be a number`);
-    }
-    const host = typeof entry["host"] === "string" ? entry["host"] : "127.0.0.1";
-    const command = entry["command"];
-    const commandArgs = entry["args"];
-    if (kind === "command") {
-        if (typeof command !== "string" || command === "") {
-            throw new ToolInputError(`"services.${service}.readiness.command" is required for kind "command"`);
-        }
-        if (commandArgs !== undefined &&
-            (!Array.isArray(commandArgs) || commandArgs.some((a) => typeof a !== "string"))) {
-            throw new ToolInputError(`"services.${service}.readiness.args" must be an array of strings`);
-        }
-    }
-    const checks = (info) => {
-        if (kind === "http") {
-            return [
-                {
-                    kind: "http",
-                    url: `http://127.0.0.1:${String(info.port)}${path.startsWith("/") ? path : `/${path}`}`,
-                    ...(typeof expectedStatus === "number" ? { expectedStatus } : {}),
-                },
-            ];
-        }
-        if (kind === "tcp-port") {
-            return [{ kind: "tcp-port", host, port: info.port }];
-        }
-        return [
-            {
-                kind: "command",
-                command: command,
-                ...(commandArgs === undefined ? {} : { args: commandArgs }),
-                cwd,
-            },
-        ];
-    };
-    return {
-        checks,
-        timeoutMs: typeof timeoutMs === "number" ? timeoutMs : DEFAULT_READINESS_TIMEOUT_MS,
-    };
-}
-function readScopes(args, declared, fallback) {
-    const scopes = {};
-    for (const service of declared)
-        scopes[service.name] = fallback;
-    const raw = args["scopeByService"];
-    if (raw === undefined)
-        return scopes;
-    for (const [name, value] of Object.entries(asRecord(raw, "scopeByService"))) {
-        const entry = asRecord(value, `scopeByService.${name}`);
-        const repo = entry["repo"];
-        if (typeof repo !== "string" || repo === "") {
-            throw new ToolInputError(`"scopeByService.${name}.repo" is required and must be a non-empty string`);
-        }
-        const repoRoot = entry["repoRoot"];
-        const cwd = entry["cwd"];
-        if (repoRoot !== undefined && typeof repoRoot !== "string") {
-            throw new ToolInputError(`"scopeByService.${name}.repoRoot" must be a string`);
-        }
-        if (cwd !== undefined && typeof cwd !== "string") {
-            throw new ToolInputError(`"scopeByService.${name}.cwd" must be a string`);
-        }
-        scopes[name] = {
-            repo,
-            ...(repoRoot === undefined ? {} : { repoRoot }),
-            ...(cwd === undefined ? {} : { cwd }),
-        };
-    }
-    return scopes;
-}
-/**
- * `Execution.state`'s five terminal values (`@descryy/runtime-contracts`:
- * `COMPLETED`, `FAILED_START`, `FAILED`, `TIMED_OUT`, `CANCELLED`), reduced
- * to this reply's own three-way outcome. Was `state === "TIMED_OUT" ?
- * "timed_out" : "ok"` — checked for exactly one non-success terminal state
- * and read every other one, `FAILED_START` included, as success. A post-spawn
- * readiness failure sets `FAILED_START` without throwing (the service never
- * became ready, but nothing raised), so it fell straight through that
- * `: "ok"` default and reported a success-shaped headline over whatever
- * evidence happened to exist — real, but no proof the boot itself worked, and
- * sometimes none of it about this failure at all.
- *
- * Inverted here on purpose: only `COMPLETED` reads as `"ok"`. `TIMED_OUT`
- * keeps its own state (a partial answer, not a failure). Everything else —
- * `FAILED_START`, `FAILED`, `CANCELLED`, and any terminal state added later —
- * reads as `"failed"` by default, so a new failure mode can only ever under-
- * report as `failed` (safe) rather than silently rejoin `"ok"` (the bug).
- */
-function deriveRunOutcome(executionState) {
-    if (executionState === "TIMED_OUT")
-        return { state: "timed_out", failed: false, timedOut: true };
-    if (executionState === "COMPLETED")
-        return { state: "ok", failed: false, timedOut: false };
-    return { state: "failed", failed: true, timedOut: false };
-}
-const EMPTY_WRITE = {
-    promoted: [],
-    created: [],
-    confirmed: [],
-    refused: [],
-    contradictions: [],
-    staleR4: [],
-    confirmedFactConflict: [],
-    unjoinedSplitEvidence: null,
-};
-/** Stated unconditionally on every call, not only when it bites: a caller unaware
- *  log-pattern readiness is unreachable will misread a tcp-port check's empty evidence
- *  as "the service produced nothing". */
-const STANDING_NOTES = [
-    "Readiness here offers only the three mechanisms JSON can state — http, tcp-port and command. " +
-        "log-pattern and custom-hook need a function and are unreachable through this tool; a run that " +
-        "needs one of those is not degraded here, it is unsupported here.",
-    "Edges are written only where an observation named both endpoints itself: a captured call-site " +
-        "stack resolving to a function, against an endpoint the same observation named. Every other " +
-        "correlated evidence item resolves a node and produces no edge, which is a gap in what this run " +
-        "could prove rather than evidence that no such edge exists.",
-    "That combination — HTTP evidence carrying a call-site stack — is produced here by the outbound-fetch " +
-        "instrumentation in @descryy/runtime-external-service-observation, which this server installs into a " +
-        "spawned service before any application code runs. So an observed outbound call CAN write this edge, " +
-        "and a run that makes none writes none: the backend collectors attach a stack to log and error lines " +
-        "(resolving a function) and none to inbound HTTP traffic (resolving an endpoint), so a service that " +
-        "never calls out resolves both kinds of node and still writes nothing. A zero here means this run " +
-        "observed no outbound call it could attribute, not that no such call exists in your code.",
-    "One thing this still cannot witness. An ATTACHED service is not launched by Descry, so the client " +
-        "instrumentation this outbound-fetch edge needs cannot be installed into it, and its outbound calls " +
-        "carry no call-site stack — an attached run is never reported as instrumented the way a spawned one " +
-        "is, whatever else it observes. @descryy/runtime-browser IS in this server's closure: declare " +
-        "\"journey\" on this call to drive a browser inside this run's own readiness window, so browser and " +
-        "backend evidence land under one executionId (RG-4). The separate browser_* tools are a different " +
-        "lifetime — they require the application to already be running when the session starts, which this " +
-        "run's own boot does not change.",
-    "No denial is ever recorded. A run establishes that a call happened; it cannot establish that one " +
-        "did not, because it exercises only the paths it took. Nothing here demotes an edge.",
-];
-/** A-F5: honest degradation about real isolation, said on every reply rather than left for
- *  the caller to discover. applySandbox enforces resourceLimits/filesystemPolicy/networkPolicy
- *  for real on Linux when declared; never applied to an attached service (Descry didn't spawn it). */
-function sandboxDisclosure(options) {
-    const { resourceLimits, filesystemPolicy, networkPolicy, sandboxBackend } = options;
-    // True regardless of policy: spawnProcess merges the full ambient env into every spawned
-    // process and bwrap doesn't clear it — out of this repo's reach (DEC-NEXT-runtime-sandbox-residual-gaps).
-    const envCaveat = "This is unaffected by any policy above: the spawned process still receives this operator's full " +
-        "environment, secrets included — the merge happens in @descryy/runtime-controller's spawnProcess and " +
-        "cannot be narrowed from this server.";
-    if (resourceLimits === undefined && filesystemPolicy === undefined && networkPolicy === undefined) {
-        return ("No resourceLimits, filesystemPolicy or networkPolicy was declared for this run. Every spawned " +
-            "service therefore ran with no OS-enforced isolation: it can read and write anything this operator's " +
-            "account can, use as much memory/CPU/process count as the host allows, and reach any network this " +
-            "operator's account can reach, and it received this operator's full environment. Attached services " +
-            "are never sandboxed regardless — Descry did not spawn them. Declare resourceLimits/filesystemPolicy/" +
-            "networkPolicy to change the filesystem/network/resource part of this for a spawned service.");
-    }
-    const applied = [];
-    if (resourceLimits !== undefined)
-        applied.push("resourceLimits");
-    if (filesystemPolicy !== undefined)
-        applied.push(`filesystemPolicy (allowedRoots: ${filesystemPolicy.allowedRoots.join(", ") || "none beyond cwd"})`);
-    if (networkPolicy !== undefined)
-        applied.push(`networkPolicy (${networkPolicy.mode}: ${networkPolicy.hosts.join(", ") || "none"})`);
-    const backend = sandboxBackend ?? "bwrap";
-    return (`Declared for this run, applied to every spawned (never attached) service via the "${backend}" ` +
-        `backend: ${applied.join(", ")}. If any of these could not actually be enforced (wrong platform, an ` +
-        "unsupported networkPolicy shape, bwrap/Docker unavailable), the run refused to start rather than " +
-        `running unconstrained under a policy nobody enforced — see the headline if this reply is a refusal. ${envCaveat}`);
-}
-/** Said on every attaching run. Measured: a redirected process's stdout is block-buffered,
- *  not line-buffered — 3 lines written over 0.6s were still absent from the file 3s later.
- *  Nothing in Descry can see those bytes; a boundary to state, not a gap to close. */
-const ATTACH_BUFFERING_NOTE = "Attaching reads a file the target writes; it can only see what the target has already flushed " +
-    "there. A process whose output is redirected to a file is usually block-buffered rather than " +
-    "line-buffered — its own runtime holds whole lines in a userspace buffer, invisible from outside, " +
-    "until the buffer fills or the process flushes. Output produced during this window may therefore " +
-    "arrive in the file after the window closed and be absent here, which is a fact about the " +
-    "target's buffering and not evidence that it did nothing. Run the target with its output " +
-    "unbuffered or line-buffered if the timing matters.";
-/**
- * RT-024, restated where a caller can actually see it.
- *
- * `attachToRunningProcess` (descry-runtime) already discloses this in its own
- * source comment — `isProcessAlive` confirms *a* process with this pid
- * exists, not that it is the one that wrote `logFilePath`, because pids are
- * reused by the OS and nothing in a bare pid or path proves provenance. That
- * comment reaches nobody calling this tool. A real run hit exactly the gap it
- * describes: an unrelated orphaned process from an earlier failed boot wrote
- * a crash trace into the same log path a live attach target used, and it was
- * attributed to the live run with no indication anything could be wrong.
- */
-const ATTACH_IDENTITY_NOTE = "Attaching verifies the declared pid is alive and reads the declared log file; it does not verify " +
-    "the lines in that file actually came from that pid. A pid can be reused by the OS, and nothing in " +
-    "a bare pid or file path proves which process is writing to it — an unrelated process writing to " +
-    "the same path would be attributed to this run with no way to tell the two apart from here.";
-/** Every argument this tool takes (readArguments, below), extracted so describeAction can
- *  call it too — catches a bad argument before minting a token for a run that could never
- *  happen (DEC-387). Touches nothing; exported for its own test. */
-/** A-F5: ResourceLimits, straight through to ExecutionConfiguration. applyResourceLimits
- *  already refuses rather than silently running unconstrained; this only reads the shape. */
-function readResourceLimits(args) {
-    const raw = args["resourceLimits"];
-    if (raw === undefined || raw === null)
-        return undefined;
-    const record = asRecord(raw, "resourceLimits");
-    const maxMemoryBytes = optionalInteger(record, "maxMemoryBytes", 1);
-    const maxCpuSeconds = optionalInteger(record, "maxCpuSeconds", 1);
-    const maxProcesses = optionalInteger(record, "maxProcesses", 1);
-    return {
-        ...(maxMemoryBytes === undefined ? {} : { maxMemoryBytes }),
-        ...(maxCpuSeconds === undefined ? {} : { maxCpuSeconds }),
-        ...(maxProcesses === undefined ? {} : { maxProcesses }),
-    };
-}
-/** A-F5: FilesystemPolicy. allowedRoots is required whenever filesystemPolicy is present —
- *  an empty-roots policy silently means "cwd only", and that must be stated, not defaulted into. */
-function readFilesystemPolicy(args) {
-    const raw = args["filesystemPolicy"];
-    if (raw === undefined || raw === null)
-        return undefined;
-    const record = asRecord(raw, "filesystemPolicy");
-    const allowedRoots = record["allowedRoots"];
-    if (!Array.isArray(allowedRoots) || allowedRoots.some((r) => typeof r !== "string")) {
-        throw new ToolInputError('"filesystemPolicy.allowedRoots" must be an array of strings');
-    }
-    return { allowedRoots: allowedRoots };
-}
-/** A-F5: NetworkPolicy. Only `{mode:"allow", hosts:[]}` (full denial) is actually enforced
- *  by applySandbox today; any other shape is accepted here and refused downstream by the
- *  mechanism itself (execution.validationError), never pre-judged here (rule 1). */
-function readNetworkPolicy(args) {
-    const raw = args["networkPolicy"];
-    if (raw === undefined || raw === null)
-        return undefined;
-    const record = asRecord(raw, "networkPolicy");
-    const mode = optionalEnum(record, "mode", ["allow", "deny"]);
-    if (mode === undefined)
-        throw new ToolInputError('"networkPolicy.mode" is required');
-    const hosts = record["hosts"];
-    if (!Array.isArray(hosts) || hosts.some((h) => typeof h !== "string")) {
-        throw new ToolInputError('"networkPolicy.hosts" must be an array of strings');
-    }
-    return { mode, hosts: hosts };
-}
-function readSandboxBackend(args) {
-    return optionalEnum(args, "sandboxBackend", ["bwrap", "container"]);
-}
-function readJourney(args) {
-    const raw = args["journey"];
-    if (raw === undefined || raw === null)
-        return undefined;
-    const record = asRecord(raw, "journey");
-    const service = optionalString(record, "service");
-    const scenarioName = optionalString(record, "scenario");
-    const startUrl = optionalString(record, "startUrl");
-    if ((scenarioName === undefined) === (startUrl === undefined)) {
-        throw new ToolInputError('journey must declare exactly one of "scenario" or "startUrl" — ' +
-            (scenarioName === undefined ? "it declares neither" : "it declares both"));
-    }
-    const recordVideo = optionalBoolean(record, "recordVideo");
-    const headless = optionalBoolean(record, "headless");
-    const settleForMs = optionalInteger(record, "settleForMs", 0);
-    return { service, scenarioName, startUrl, recordVideo, headless, settleForMs };
-}
-function readDatabaseChannel(args) {
-    const raw = args["database"];
-    if (raw === undefined || raw === null)
-        return undefined;
-    const record = asRecord(raw, "database");
-    const statementLogRaw = record["statementLog"];
-    const statementLogRecord = asRecord(statementLogRaw, "database.statementLog");
-    const kind = statementLogRecord["kind"];
-    const service = optionalString(record, "service");
-    if (kind === "file") {
-        const path = statementLogRecord["path"];
-        if (typeof path !== "string" || path === "") {
-            throw new ToolInputError('"database.statementLog.path" is required and must be a non-empty string for kind "file"');
-        }
-        // A-F6: same narrower, name-based check `attach.logFilePath` uses — a real statement log
-        // lives anywhere and can't be root-confined.
-        const sensitivity = checkNotSensitivePath(path, ALLOW_SENSITIVE_LOG_PATH_ENV_VAR);
-        if (sensitivity.sensitive)
-            throw new ToolInputError(`"database.statementLog.path": ${sensitivity.reason}`);
-        return { statementLog: { kind: "file", path }, service };
-    }
-    if (kind === "dockerContainer") {
-        const container = statementLogRecord["container"];
-        if (typeof container !== "string" || container === "") {
-            throw new ToolInputError('"database.statementLog.container" is required and must be a non-empty string for kind "dockerContainer"');
-        }
-        return { statementLog: { kind: "dockerContainer", container }, service };
-    }
-    throw new ToolInputError('"database.statementLog.kind" must be "file" or "dockerContainer"');
-}
-export function readArguments(args, repoPath, savedStart) {
-    const profile = readProfile(args);
-    const adapterSpec = readAdapterSpec(args);
-    const { declared, usedSaved: usedSavedServices, missingSavedEnv } = readServices(args, repoPath, savedStart);
-    const observeForMs = optionalInteger(args, "observeForMs", 1) ?? DEFAULT_OBSERVE_MS;
-    const timeoutMs = optionalInteger(args, "timeoutMs", 1) ?? DEFAULT_TIMEOUT_MS;
-    const fidelityRaw = optionalInteger(args, "fidelityLevel", 1) ?? 2;
-    if (fidelityRaw > 4)
-        throw new ToolInputError('"fidelityLevel" must be 1, 2, 3 or 4');
-    const environmentTier = optionalString(args, "environmentTier") ?? "tier-2-container";
-    const evidenceArg = optionalString(args, "evidencePath");
-    const evidenceCandidate = evidenceArg === undefined
-        ? join(repoPath, DEFAULT_EVIDENCE_RELATIVE_PATH)
-        : isAbsolute(evidenceArg)
-            ? evidenceArg
-            : join(repoPath, evidenceArg);
-    // A-F6: join() doesn't stop ".." escaping repoPath — confined by default (path-confinement.ts).
-    const confinement = checkPathConfinement({
-        candidate: evidenceCandidate,
-        allowedRoots: [repoPath],
-        envVar: ALLOW_EVIDENCE_PATH_OUTSIDE_REPO_ENV_VAR,
-        what: "evidencePath",
-    });
-    if (!confinement.allowed)
-        throw new ToolInputError(confinement.reason);
-    const evidencePath = confinement.resolved;
-    const resourceLimits = readResourceLimits(args);
-    const filesystemPolicy = readFilesystemPolicy(args);
-    const networkPolicy = readNetworkPolicy(args);
-    const sandboxBackend = readSandboxBackend(args);
-    const journey = readJourney(args);
-    const database = readDatabaseChannel(args);
-    return {
-        profile,
-        adapterSpec,
-        declared,
-        usedSavedServices,
-        missingSavedEnv,
-        observeForMs,
-        timeoutMs,
-        fidelityRaw,
-        environmentTier,
-        evidencePath,
-        resourceLimits,
-        filesystemPolicy,
-        networkPolicy,
-        sandboxBackend,
-        journey,
-        database,
-    };
-}
-/**
- * RG-5(a) — every service this tool spawns gets whatever database-observation
- * launch its own adapter declares, injected automatically with no caller
- * declaration needed. Reads `RuntimeAdapter.databaseObservationLaunch()`
- * (`@descryy/runtime-backend-observation`) — the same language-neutral seam
- * `outboundHttpLaunch()` already established for outbound-fetch
- * instrumentation — rather than comparing `adapter.language` against a name:
- * this file sits above the Canonical IR, where deciding behaviour from which
- * language an adapter is for is the exact leak architecture principle 7
- * forbids (enforced here by `eslint-plugin-descry-boundary`'s
- * `no-language-vocabulary`, which is what caught the first draft of this
- * function). The per-language answer — Node gets `node:sqlite`'s preload,
- * most runtimes get nothing yet — lives in each adapter package instead.
- *
- * Attach-mode services (no `command`) are untouched — Descry did not spawn
- * them, so there is no command line to inject into.
- */
-function withDatabaseObservationPreload(service, adapter) {
-    if (service.command === undefined)
-        return service;
-    const launch = adapter.databaseObservationLaunch?.();
-    if (launch === undefined || launch === null)
-        return service;
-    return {
-        ...service,
-        ...(launch.interpreterArgs === undefined ? {} : { interpreterArgs: [...(service.interpreterArgs ?? []), ...launch.interpreterArgs] }),
-        ...(launch.env === undefined ? {} : { env: { ...service.env, ...launch.env } }),
-    };
-}
-/**
- * RG-5(a) read-back half — desktop's `observeDatabaseQueries`, same shape:
- * replays each service's own already-captured output (the preload's
- * `DESCRY_DB_QUERY` marker lines) through `createDatabaseQueryCollector` and
- * writes real `DATABASE_QUERY` evidence into this run's store. Returns how
- * many records it wrote, so the caller can fold it into one disclosed count
- * alongside the Postgres channel's.
- */
-async function observeSqliteQueries(store, executionId, configuration, execution) {
-    const serviceOutput = capturedServiceOutput(execution);
-    if (serviceOutput === null)
-        return 0;
-    let written = 0;
-    await Promise.all(Object.entries(serviceOutput).map(async ([serviceName, output]) => {
-        const source = {
-            processId: `${executionId}:${serviceName}`,
-            serviceName,
-            lines: (async function* () {
-                for (const text of output.split("\n")) {
-                    if (text.length === 0)
-                        continue;
-                    yield { text, stream: "combined", observedAt: new Date().toISOString() };
-                }
-            })(),
-        };
-        const context = {
-            executionId,
-            configuration,
-            emit: (evidenceInput) => {
-                store.write({ ...evidenceInput, executionId });
-                written += 1;
-            },
-        };
-        const collector = createDatabaseQueryCollector({ source, service: serviceName });
-        await collector.start(context);
-        await collector.stop();
-    }));
-    return written;
-}
-/**
- * RG-5(c) — the Postgres statement-log channel's own start/stop pair, same
- * design as the desktop's `beginPostgresChannel`: started before
- * `runInstrumentedExecution` (the server keeps running independently of
- * whatever this tool spawns or tears down, so the only way to capture
- * queries issued *during* the observation window is to already be tailing
- * when they happen), buffered until a real `executionId` exists to attribute
- * it to, and idempotent to `stop()` because the caller's own `finally` may
- * call it a second time after an already-successful stop.
- */
-function beginPostgresChannel(database, processId) {
-    if (database === undefined)
-        return { kind: "not-declared" };
-    const captured = [];
-    const controller = new AbortController();
-    const serviceName = database.service ?? "postgres";
-    const source = createPostgresLogSource(database.statementLog, processId, serviceName, { signal: controller.signal });
-    const collector = createPostgresQueryCollector({ source, service: serviceName });
-    const context = {
-        executionId: processId,
-        configuration: { environmentTier: "tier-2-container", fidelityLevel: 2, timeoutMs: 0, services: {} },
-        emit: (evidence) => {
-            captured.push(evidence);
-        },
-    };
-    const started = collector.start(context);
-    let stopped;
-    return {
-        kind: "observing",
-        stop: () => {
-            if (stopped === undefined) {
-                stopped = (async () => {
-                    await started;
-                    controller.abort();
-                    await collector.stop();
-                    return captured;
-                })();
-            }
-            return stopped;
-        },
-    };
-}
-/** Exported so `observe.ts` can dispatch the "runtime" verb to this exact body — the merge
- *  reuses this function rather than reimplementing it (mcp-surface-consolidation.md). */
-export async function run(args, ctx) {
-    const session = ctx.session;
-    const { profile, adapterSpec, declared, usedSavedServices, missingSavedEnv, observeForMs, timeoutMs, fidelityRaw, environmentTier, evidencePath, resourceLimits, filesystemPolicy, networkPolicy, sandboxBackend, journey, database, } = readArguments(args, session.repoPath, session.config.savedStart);
-    const notes = [...STANDING_NOTES, sandboxDisclosure({ resourceLimits, filesystemPolicy, networkPolicy, sandboxBackend })];
-    // RG-5(c). Stated on every call, success or refusal, same reasoning as the
-    // sandbox disclosure above: a caller unaware the Postgres channel needs an
-    // explicit statement-log source would misread a "channel absent" run as
-    // "this application makes no database calls."
-    notes.push(database === undefined
-        ? "database channel: not observed — no statement log configured. Declare \"database.statementLog\" " +
-            "(a file path, or a Docker container's logs) to capture real Postgres queries issued during this " +
-            "run. Node services using node:sqlite are observed automatically, with no declaration needed."
-        : `database channel: tailing the Postgres statement log via ${database.statementLog.kind === "file" ? `file "${database.statementLog.path}"` : `docker container "${database.statementLog.container}"`}.`);
-    // Added on refusal paths too — telling the caller only on success means telling them
-    // after the run whose result it would have explained (same reasoning as the line above).
-    if (usedSavedServices) {
-        const savedAt = session.config.savedStart?.savedAt ?? "an earlier run";
-        notes.push(`No "services" was supplied on this call, so it reused the start settings a prior successful run ` +
-            `saved (${savedAt}): ${describeSavedCommands(declared)}. Declare "services" explicitly to override ` +
-            "them — only another run that reaches readiness replaces what is saved.");
-        if (missingSavedEnv.length > 0) {
-            notes.push(`These environment variables were declared on the run that saved these settings, but nothing is ` +
-                `set under their names in this process's environment now, so they were not passed this time: ` +
-                `${missingSavedEnv.join(", ")}. Only variable names are ever saved, never their values.`);
-        }
-    }
-    if (declared.some((service) => service.attached)) {
-        notes.push(ATTACH_BUFFERING_NOTE, ATTACH_IDENTITY_NOTE);
-    }
-    const base = session.provider().baseStamp();
-    const refuse = (headline, data = {}, extraNotes = []) => answer({
-        headline,
-        state: "refused",
-        nameLevel: true,
-        // Nothing ran, so nothing was resolved — never leak the tier a successful path would reach.
-        resolutionFloor: 0,
-        commitSha: base.commitSha,
-        graphBuiltAt: base.graphBuiltAt,
-        irSchemaVersion: base.irSchemaVersion,
-        commitSpread: base.commitSpread,
-        repoCount: base.repoCount,
-        notes: [...notes, ...extraNotes],
-        data: {
-            executionId: null,
-            executionState: null,
-            adapterLanguage: null,
-            evidencePath,
-            services: [],
-            evidenceByType: {},
-            correlation: null,
-            wrote: EMPTY_WRITE,
-            journey: null,
-            database: null,
-            ...data,
-        },
-    });
-    // Spawning is a write against the target; attaching is not (Descry never executes code in,
-    // signals, or limits a process it didn't spawn). The profile's declared level decides, never its name.
-    const spawns = declared.some((service) => !service.attached);
-    const action = { write: spawns, destructive: false };
-    const decision = evaluateAction(profile, action);
-    if (decision !== "allow") {
-        return refuse(`Profile "${profile.name}" declares safetyLevel "${profile.safetyLevel}", which does not permit ` +
-            `${spawns ? "spawning a service" : "this run"}. Nothing was started and nothing was written. ` +
-            (spawns
-                ? "A run in which every service uses \"attach\" spawns nothing and is permitted under readOnly."
-                : ""));
-    }
-    if (!spawns) {
-        notes.push("Every declared service is attached to rather than spawned, so this run started nothing and " +
-            "applied no resource, filesystem or network policy to any process — Descry does not constrain " +
-            "a process it did not spawn.");
-    }
-    // Correlation resolves evidence against this graph; an empty graph resolving nothing must
-    // not be reported as a clean run with no findings — the "empty means broken" collapse.
-    const driver = session.store().driver;
-    const stored = counts(driver);
-    if (stored.nodes === 0) {
-        return refuse("This repository has no graph yet, so there is nothing for a run's evidence to be resolved " +
-            "against. Run analyze first — an observation that cannot name a node cannot become a fact.");
-    }
-    // --- the adapter ----------------------------------------------------------
-    ctx.progress(`Loading runtime adapter ${adapterSpec.module}`);
-    let adapter;
-    try {
-        adapter = await loadRuntimeAdapter(adapterSpec, session.repoPath);
-    }
-    catch (error) {
-        if (error instanceof RuntimeAdapterLoadError) {
-            notes.push("This server depends on none of descry-runtime's language adapters by design, so the adapter " +
-                "must be installed alongside it and named in the call. Nothing was started.");
-            return refuse(error.message);
-        }
-        throw error;
-    }
-    notes.push(`Observed with the runtime adapter for "${adapter.language}", loaded from ${adapterSpec.module}.`);
-    const root = await session.root();
-    const scopes = readScopes(args, declared, {
-        repo: root.repo,
-        repoRoot: root.absolutePath,
-    });
-    const services = {};
-    const readiness = {};
-    for (const service of declared) {
-        services[service.name] = withDatabaseObservationPreload(service.configuration, adapter);
-        readiness[service.name] = service.readiness;
-    }
-    const configuration = {
-        environmentTier: environmentTier,
-        fidelityLevel: fidelityRaw,
-        timeoutMs,
-        services,
-        // A-F5: wired through to the controller's real bwrap/container isolation
-        // — see sandboxDisclosure() above for what this reply says about it.
-        ...(resourceLimits === undefined ? {} : { resourceLimits }),
-        ...(filesystemPolicy === undefined ? {} : { filesystemPolicy }),
-        ...(networkPolicy === undefined ? {} : { networkPolicy }),
-        ...(sandboxBackend === undefined ? {} : { sandboxBackend }),
-    };
-    // Before anything is spawned — a caller who's already gone would leave a real process
-    // running with nothing left to ever stop it.
-    if (ctx.signal.aborted) {
-        return refuse(cancellationHeadline("no service was started") + " " + cancellationNotes("Nothing was spawned.")[0]);
-    }
-    // RG-4/RG-6 — resolve the declared journey into a drive-ready plan before anything is
-    // spawned. A scenario that cannot be read or projected (e.g. an unresolvable secret
-    // reference) degrades this run to backend-only with a named disclosure; it never fails
-    // the whole call, because the journey is additive to what observe_runtime already does.
-    let journeyPlan = null;
-    if (journey !== undefined) {
-        if (journey.scenarioName !== undefined) {
-            const stored = await readScenario(session.repoPath, journey.scenarioName);
-            if (!stored.valid) {
-                notes.push(`journey.scenario "${journey.scenarioName}" could not be read, so this run is backend-only: ` +
-                    stored.problems.join(" "));
-            }
-            else {
-                const projected = projectScenarioToRunPlan(stored.scenario);
-                if (!projected.ok) {
-                    notes.push(`journey.scenario "${journey.scenarioName}" could not be driven, so this run is backend-only: ` +
-                        `${projected.reason} (verb "${projected.verb}")`);
-                }
-                else {
-                    const MUTATING_KINDS = new Set(["click", "type", "select", "submit"]);
-                    const mutates = projected.plan.steps.some((s) => MUTATING_KINDS.has(s.kind));
-                    const readOnly = profile.safetyLevel === "readOnly";
-                    const steps = mutates && readOnly ? projected.plan.steps.filter((s) => !MUTATING_KINDS.has(s.kind)) : projected.plan.steps;
-                    if (mutates && readOnly) {
-                        notes.push(`journey.scenario "${journey.scenarioName}" declares steps that would change the application ` +
-                            `(click/type/select/submit), and profile "${profile.name}" declares safetyLevel "readOnly" — ` +
-                            "those steps were not driven. The scenario's own navigation and any assertions still ran and were observed.");
-                    }
-                    journeyPlan = {
-                        startUrl: projected.plan.startUrl,
-                        steps,
-                        ...(journey.service === undefined ? {} : { service: journey.service }),
-                        ...(journey.recordVideo === undefined ? {} : { recordVideo: journey.recordVideo }),
-                        ...(journey.headless === undefined ? {} : { headless: journey.headless }),
-                        ...(journey.settleForMs === undefined ? {} : { settleForMs: journey.settleForMs }),
-                    };
-                }
-            }
-        }
-        else if (journey.startUrl !== undefined) {
-            journeyPlan = {
-                startUrl: journey.startUrl,
-                ...(journey.service === undefined ? {} : { service: journey.service }),
-                ...(journey.recordVideo === undefined ? {} : { recordVideo: journey.recordVideo }),
-                ...(journey.headless === undefined ? {} : { headless: journey.headless }),
-                ...(journey.settleForMs === undefined ? {} : { settleForMs: journey.settleForMs }),
-            };
-        }
-    }
-    await mkdir(dirname(evidencePath), { recursive: true });
-    const evidenceStore = new EvidenceStore({ path: evidencePath });
-    /** Processes **this run started**, and only those — an attach-mode service is the
-     *  developer's own process; killing it on cancellation would destroy something this
-     *  call never created. Only the spawn path is cleaned up. */
-    const attached = new Set(declared.filter((service) => service.attached).map((service) => service.name));
-    const spawnedPids = new Set();
-    const abort = whenAborted(ctx.signal);
-    void abort.promise.then(() => {
-        for (const pid of spawnedPids)
-            terminateSpawnedProcess(pid);
-    });
-    // Set inside onReady below, read after the execution returns — the drive is the only
-    // thing that can report what it did, and it runs deep inside the orchestrator's own
-    // callback. `onReady`'s own contract says a throwing callback is NOT caught by the
-    // orchestrator — it would reject the whole execution and discard every piece of backend
-    // evidence already collected — so the drive itself never throws and this is a second belt.
-    let journeyOutcome;
-    // RG-5(c). Started before `runInstrumentedExecution`, not after: a Postgres
-    // statement log is the server's own, and the server keeps running
-    // independently of whatever this run spawns or tears down — the only way
-    // to capture queries issued *during* this run's observation window is to
-    // already be tailing when they happen (same reasoning as the journey drive
-    // being wired through `onReady` rather than run after the fact).
-    const postgresChannel = beginPostgresChannel(database, `postgres:${root.repo}`);
-    try {
-        ctx.progress(`Running ${declared.length} service(s), observing for ${String(observeForMs)}ms`);
-        const execution = await runInstrumentedExecution({
-            execution: {
-                application: root.repo,
-                repository: root.repo,
-                commit: root.commitSha,
-                configuration,
-            },
-            runOptions: {
-                readiness,
-                // The only channel naming a process while still alive — Execution.processes is
-                // complete only once the whole window has already slept, past where a cancel lands.
-                onProcessLifecycleEvent: (event) => {
-                    if (event.kind !== "process-started" || attached.has(event.serviceName))
-                        return;
-                    if (event.handle.pid !== null)
-                        spawnedPids.add(event.handle.pid);
-                },
-            },
-            adapter,
-            store: evidenceStore,
-            observeForMs,
-            // RG-4 — the one moment in a run when every service's readiness has already
-            // succeeded and nothing has been torn down yet. Browser evidence therefore lands
-            // in the same store under the same executionId as the backend's — the desktop
-            // composes identically (packages/session/src/pipeline/runtime-execution.ts).
-            ...(journeyPlan === null
-                ? {}
-                : {
-                    onReady: async ({ execution: readyExecution }) => {
-                        try {
-                            const drive = createRuntimeJourneyDrive(journeyPlan);
-                            journeyOutcome = await drive({
-                                store: evidenceStore,
-                                executionId: readyExecution.executionId,
-                                configuration,
-                                resolveSourceRoot: createSourceRootResolver(readyExecution.processes, configuration),
-                                stackTraceParser: adapter.stackTraceParser,
-                            });
-                        }
-                        catch (error) {
-                            const cause = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
-                            evidenceStore.write({
-                                executionId: readyExecution.executionId,
-                                timestamp: new Date().toISOString(),
-                                source: "harness",
-                                service: journeyPlan?.service ?? null,
-                                process: null,
-                                eventType: "COLLECTOR_ERROR",
-                                payload: { raw: `the journey drive threw instead of degrading: ${cause}`, error: cause, collectorId: "runtime-journey-drive" },
-                                traceId: null,
-                                requestId: null,
-                                correlationId: null,
-                                graphNodeId: null,
-                                sourceLocation: null,
-                                stackTrace: null,
-                                confidence: 1,
-                                collectorVersion: "descry-mcp-observe-runtime@1",
-                            });
-                        }
-                    },
-                }),
-        });
-        // The kill above doesn't shorten the window — this is where a cancelled run actually
-        // stops. Nothing is correlated or written: an R4 edge can't be re-derived and checked
-        // later, so minting one from a run nobody watched to the end would be unquestionable.
-        // RG-5(c): the postgres tail is stopped here too (releasing its child process) but its
-        // capture is discarded, same "nothing correlated or written" rule as everything else.
-        if (ctx.signal.aborted) {
-            if (postgresChannel.kind === "observing")
-                await postgresChannel.stop().catch(() => undefined);
-            return refuse(cancellationHeadline("the observed application was stopped"), {
-                executionId: execution.execution.executionId,
-                executionState: execution.execution.state,
-                adapterLanguage: adapter.language,
-                services: describeServices(execution.execution.processes, declared),
-                evidenceByType: tally(execution.evidence),
-                journey: journeyOutcome ?? null,
-            }, cancellationNotes(`Every service this run spawned was killed; ${String(attached.size)} attached service(s) were ` +
-                "left alone, because this call did not start them.", "No evidence was correlated and no edge was written. Evidence already collected is still on disk " +
-                `at ${evidencePath}, so nothing witnessed was thrown away.`));
-        }
-        // RG-5(a)/(c) — stop the postgres tail now that the observation window has closed and
-        // replay the sqlite preload's captured output, attributing both to this run's real
-        // executionId (unknown until now, which is why the postgres collector above buffered
-        // rather than wrote directly). Must happen before correlation, same ordering the desktop
-        // uses, so a database-node resolver can attribute what is already in the store.
-        const executionId = execution.execution.executionId;
-        let databaseRecordCount = 0;
-        if (postgresChannel.kind === "observing") {
-            const capturedPostgres = await postgresChannel.stop();
-            for (const evidence of capturedPostgres) {
-                evidenceStore.write({ ...evidence, executionId });
-                databaseRecordCount += 1;
-            }
-        }
-        databaseRecordCount += await observeSqliteQueries(evidenceStore, executionId, configuration, execution);
-        const databaseObservation = database === undefined
-            ? {
-                observed: false,
-                disclosure: "database channel: not observed — no statement log configured",
-                recordCount: databaseRecordCount,
-            }
-            : { observed: true, disclosure: null, recordCount: databaseRecordCount };
-        const observed = describeServices(execution.execution.processes, declared);
-        const evidenceByType = tally(execution.evidence);
-        // RG-4 — `execution.evidence` is `runInstrumentedExecution`'s own returned snapshot and
-        // never includes what the journey drive wrote directly into `evidenceStore` inside
-        // `onReady` (it isn't tracked by the orchestrator's own `emitted` array). Re-read from
-        // the store, scoped to this executionId, only when a journey actually ran — so the
-        // headline/notes below (which read `execution.evidence` directly, unchanged) still pin
-        // exactly what they always have on every backend-only run.
-        // RG-5(c): also re-read when the database channel wrote anything — same reasoning as the
-        // journey case, a different write path `execution.evidence` was already materialised
-        // before this run's own DATABASE_QUERY records ever reached the store.
-        const evidenceIncludingJourney = journeyOutcome === undefined && databaseRecordCount === 0
-            ? execution.evidence
-            : [...evidenceStore.getByExecution(execution.execution.executionId)];
-        if (execution.validationError !== null) {
-            // Refused before spawning — a fact about the declaration, not the application;
-            // emphatically not "the service is clean".
-            return refuse(`The execution refused to start: ${execution.validationError}. Nothing was spawned, no ` +
-                "evidence was collected, and no graph edge was written.", {
-                executionState: execution.execution.state,
-                adapterLanguage: adapter.language,
-                database: databaseObservation,
-                services: observed,
-                evidenceByType,
-            }, usedSavedServices
-                ? [
-                    `These start settings came from a prior successful run — "services" was omitted on this ` +
-                        `call — and they no longer work: ${describeSavedCommands(declared)}. Call observe_runtime ` +
-                        'again with "services" declared explicitly to replace what is saved; only another run ' +
-                        "that reaches readiness updates it.",
-                ]
-                : []);
-        }
-        // See deriveRunOutcome for the full rule. Budget-expired case measured pre-clamp: a 1.5s
-        // budget over a 12s window returned at 12.3s with zero evidence (DEC-NEXT-observe-runtime-
-        // timeout-budget-is-not-enforced.md). Reported `timed_out`, not `ok` (§6) — real evidence,
-        // just less of it. A post-spawn readiness failure (FAILED_START) and any other non-success
-        // terminal state are reported `failed`, never `ok`, whatever evidence happens to exist.
-        const outcome = deriveRunOutcome(execution.execution.state);
-        const { failed, timedOut } = outcome;
-        if (timedOut) {
-            notes.push(`This run hit its ${String(timeoutMs)}ms whole-execution budget before the ` +
-                `${String(observeForMs)}ms observation window closed, so every service was stopped early and ` +
-                "the evidence below is partial — every count is a floor, not a total. Nothing here says the " +
-                "application produced no further output; only that this run stopped listening for it. Raise " +
-                '"timeoutMs" clear of the observation window, or shorten "observeForMs".');
-        }
-        const capturedOutput = capturedServiceOutput(execution);
-        // Only on failure: a healthy boot log is large and would crowd out every
-        // other field, and nobody is asking why a service that worked worked.
-        const services = failed ? describeServices(execution.execution.processes, declared, capturedOutput ?? {}) : observed;
-        if (failed) {
-            const outputNote = startupOutputNote(services, capturedOutput);
-            if (outputNote !== null)
-                notes.push(outputNote);
-            notes.push(`This run's execution ended in state "${execution.execution.state}", not "COMPLETED" — the ` +
-                "application did not finish booting successfully. Any evidence below may be partial, or " +
-                "left over from earlier in this same run, and does not mean the service ever became ready.");
-            if (usedSavedServices) {
-                notes.push(`These start settings came from a prior successful run — "services" was omitted on this call ` +
-                    `— and they did not work this time: ${describeSavedCommands(declared)}. Call observe_runtime ` +
-                    'again with "services" declared explicitly to replace what is saved.');
-            }
-        }
-        ctx.progress(`Correlating ${String(execution.evidence.length)} evidence item(s) against the graph`);
-        const pass = correlateExecution({
-            store: evidenceStore,
-            driver,
-            executionId: execution.execution.executionId,
-            scopeByService: scopes,
-        });
-        const correlation = {
-            considered: pass.considered,
-            skipped: pass.skipped,
-            attributed: pass.attributed.length,
-            refused: pass.refusals.length,
-            unscopedServices: pass.unscopedServices,
-            harnessErrors: pass.harnessErrors.map((e) => `${e.detail} (${String(e.occurrences)}×)`),
-        };
-        if (pass.unscopedServices.length > 0) {
-            // Two sentences, not one: a named service with no scope is fixable by the caller; the
-            // "(no service)" sentinel is not — no collector stamps one, so there's no key to supply.
-            const named = pass.unscopedServices.filter((s) => s !== "(no service)");
-            const anonymous = pass.unscopedServices.length - named.length;
-            if (named.length > 0) {
-                notes.push(`Symbol evidence from ${named.join(", ")} was left unresolved: no scope named which ` +
-                    "repository those symbols belong to, and resolving them against a repository nobody " +
-                    "named would resolve the wrong one's identically-named file. Supply " +
-                    '"scopeByService" for those services to have them resolved.');
-            }
-            if (anonymous > 0) {
-                notes.push("Some evidence carried a source location but no service name, so no scope could be " +
-                    "looked up for it and its symbols were never resolved. This is not a missing argument: " +
-                    "nothing in this server's runtime closure stamps a service name onto collector " +
-                    "evidence, so there is no key a caller could supply a scope under. The items are " +
-                    "counted as skipped rather than dropped, and what they would have resolved to is " +
-                    "unknown rather than absent.");
-            }
-        }
-        if (pass.harnessErrors.length > 0) {
-            notes.push(`${String(pass.harnessErrors.length)} correlation failure(s) were the machinery breaking rather ` +
-                "than a resolver honestly declining — each is written into the evidence stream as a " +
-                "COLLECTOR_ERROR, and the counts below are correspondingly incomplete.");
-        }
-        // Recorded before the edge write so a failure in one doesn't silently cost the other.
-        // See runtime-incident.ts for why an EXCEPTION alone is not an incident.
-        const incident = runtimeObservedIncident({
-            repo: root.repo,
-            repoRoot: root.absolutePath,
-            runId: execution.execution.executionId,
-            services,
-            exceptionLocations: execution.evidence
-                .filter((e) => e.eventType === "EXCEPTION")
-                .map((e) => ({ file: e.sourceLocation?.file ?? null })),
-            exceptionTexts: execution.evidence
-                .filter((e) => e.eventType === "EXCEPTION")
-                .map((e) => (typeof e.payload === "string" ? e.payload : JSON.stringify(e.payload)))
-                .map((text) => text.split("\n")[0] ?? "")
-                .filter((line) => line !== ""),
-        });
-        if (incident !== null) {
-            ctx.progress("Recording the observed failure as an incident");
-            // `written.records` — the already-deduped list on file, not
-            // `session.config.confirmedIncidents` plus `incident` — the same
-            // resubmission hazard `mark_incident` has (UAT phase 5, F9): a run
-            // observing the identical failure twice must merge, not mint a second
-            // `INCIDENT` node sharing the first's id.
-            const written = await writeConfirmedIncident(session.repoPath, incident);
-            const projected = await createConfirmedIncidentSource({
-                repo: root.repo,
-                incidents: written.records,
-            }).emit({ root });
-            const built = buildGraph([projected], {
-                nodeExists: (id) => session.provider().node(id) !== undefined,
-            });
-            persistGraph(driver, [projected], built);
-            // Same fix as mark_incident's write path: this source's output is a
-            // small, fully-specified list every call, so a deleted incident whose
-            // files went with it is never caught by the shared eviction's file
-            // overlap check.
-            evictStaleConfirmedIncidentNodes(driver, projected.producedBy, new Set(built.nodes.filter((n) => n.producedBy === projected.producedBy).map((n) => n.id)));
-            notes.push(`A service died during this run (${incident.summary}), so it was recorded as an incident ` +
-                `correlated to ${String(incident.files.length)} file(s) this repository owns, and written ` +
-                "durably to .descry/config.json — a run is gone once the process exits. The correlation " +
-                "is every file an exception stack named during the run, which is not a claim about the " +
-                "cause: nothing here knows which exception killed the process, and choosing the last one " +
-                "would be recency standing in for causality.");
-        }
-        ctx.progress("Writing observed edges into the graph");
-        const wrote = writeObservations({
-            driver,
-            pass,
-            evidenceStore,
-            repo: root.repo,
-            repoRoot: root.absolutePath,
-            runId: execution.execution.executionId,
-            commitSha: root.commitSha,
-        });
-        const written = wrote.promoted.length + wrote.created.length;
-        if (written === 0) {
-            notes.push("No edge was written. Either no observation carried a call-site stack that resolved to a " +
-                "function this graph holds, or every one it did carry was already at R4. Both are real " +
-                "outcomes of this run, and neither says the graph's existing edges are wrong.");
-        }
-        if (wrote.unjoinedSplitEvidence !== null)
-            notes.push(wrote.unjoinedSplitEvidence);
-        notes.push(...wrote.confirmedFactConflict);
-        // Build item 2: save only on a real success, whichever source these services came
-        // from (fresh args or the saved settings this same call may have reused) — an
-        // idempotent overwrite either way. Never on `timedOut` or `failed`: neither
-        // establishes that every declared service actually reached readiness.
-        if (outcome.state === "ok") {
-            const toSave = {};
-            for (const service of declared)
-                toSave[service.name] = service.savable;
-            try {
-                const saved = await writeSavedStart(session.repoPath, toSave);
-                // Written to disk above; `reloadConfig()` (session.ts's own sole mutator of
-                // `session.config`) mirrors it into this live session immediately, so a second
-                // call on this same connection sees it with no explicit reload in between.
-                // Without this, `session.config.savedStart` stays whatever it was when this
-                // session was constructed — stale for the rest of the process's life — and this
-                // same write would also show up as spurious drift on this very reply, since
-                // `checkConfigDrift` (server.ts) diffs on-disk config against `session.config`
-                // right after this tool returns.
-                await session.reloadConfig();
-                notes.push(`This run's services were saved to ${saved.path} (auto-action, disclosed per rule 7 — never a ` +
-                    "secret value, since environment variables are saved by name only). A later observe_runtime " +
-                    'call on this repository may omit "services" and these settings will be reused.');
-            }
-            catch (error) {
-                notes.push(`This run's start settings could not be saved (${error instanceof Error ? error.message : String(error)}); ` +
-                    'a later call must still declare "services" explicitly.');
-            }
-        }
-        const headline = failed
-            ? `The run failed to complete: execution ended in state "${execution.execution.state}", not ` +
-                `"COMPLETED". ${String(execution.evidence.length)} evidence item(s) were collected across ` +
-                `${String(declared.length)} service(s), but that does not mean the boot succeeded — see the ` +
-                "notes for what this run could and could not establish."
-            : `Observed ${String(execution.evidence.length)} evidence item(s) across ${String(declared.length)} ` +
-                `service(s); ${String(pass.attributed.length)} resolved to graph nodes; ` +
-                `${String(wrote.promoted.length)} edge(s) promoted to R4 and ${String(wrote.created.length)} minted at R4.`;
-        return answer({
-            headline,
-            // Not `empty` when nothing was witnessed — `empty` claims the population, and "this run
-            // took no path exercising the code" isn't "this code does nothing". `timed_out` when the
-            // budget bound this run, `failed` when the execution never reached `COMPLETED` at all
-            // (see deriveRunOutcome): `empty`/`ok` both claim the window ran to its end on a run that
-            // actually finished.
-            state: outcome.state,
-            nameLevel: true,
-            // R4 unconditionally: every `wrote` fact was witnessed at runtime (DEC-115, no inference).
-            // A run that wrote nothing reports R0 rather than borrowing the tier a success would reach.
-            resolutionFloor: (written > 0 ? 4 : 0),
-            // G3/G4's E, declared only when evidence actually came back — not gated on `written > 0`:
-            // rule 3 already caps the category via resolutionFloor above, so a run that saw channels
-            // but wrote no edge is `unconfirmed` by that cap, not by pretending it saw nothing.
-            ...(evidenceIncludingJourney.length === 0
-                ? {}
-                : { runtimeEvidence: { independentSignalTypes: witnessedSignalTypes(evidenceIncludingJourney) } }),
-            commitSha: base.commitSha,
-            graphBuiltAt: base.graphBuiltAt,
-            irSchemaVersion: base.irSchemaVersion,
-            commitSpread: base.commitSpread,
-            repoCount: base.repoCount,
-            notes,
-            data: {
-                executionId: execution.execution.executionId,
-                executionState: execution.execution.state,
-                adapterLanguage: adapter.language,
-                evidencePath,
-                services,
-                evidenceByType: journeyOutcome === undefined && databaseRecordCount === 0 ? evidenceByType : tally(evidenceIncludingJourney),
-                correlation,
-                wrote,
-                journey: journeyOutcome ?? null,
-                database: databaseObservation,
-            },
-        });
-    }
-    finally {
-        // Best-effort: normally already stopped above. Only still "observing" here when something
-        // threw before that point (e.g. runInstrumentedExecution itself), in which case the
-        // captured evidence has no real executionId to attribute to and is discarded — the same
-        // "no fabrication" posture as the cancellation path.
-        if (postgresChannel.kind === "observing")
-            await postgresChannel.stop().catch(() => undefined);
-        abort.dispose();
-        evidenceStore.close();
-    }
-}
-/** Stop a process this run spawned, and the group it leads — signalling the leader alone
- *  would leave forked children holding the port. ESRCH is ordinary: it may have already exited. */
-function terminateSpawnedProcess(pid) {
-    try {
-        process.kill(-pid, "SIGTERM");
-        return;
-    }
-    catch (error) {
-        if (error.code === "ESRCH")
-            return;
-    }
-    try {
-        process.kill(pid, "SIGTERM");
-    }
-    catch {
-        // Already gone. Nothing to report and nothing to do.
-    }
-}
-/**
- * The per-service captured output, when the installed runtime supplies it.
- *
- * Read structurally rather than off the declared type. `serviceOutput` is newer
- * than the `@descryy/runtime-orchestrator` this package is pinned to, and the
- * pin is exact while the engine is on 0.x (DEC-395), so the field is present at
- * runtime only once that pin moves. An optional read means this half works the
- * day the runtime ships it and degrades honestly — not silently — before then:
- * `startupOutputNote` says so to the user rather than letting an empty field
- * read as "the service printed nothing".
- */
-function capturedServiceOutput(execution) {
-    const candidate = execution.serviceOutput;
-    if (candidate === null || typeof candidate !== "object" || candidate === undefined)
-        return null;
-    const entries = Object.entries(candidate).filter((entry) => typeof entry[1] === "string");
-    return Object.fromEntries(entries);
-}
-/**
- * What to tell the user when a run failed and no output came back with it.
- *
- * An exit code with no explanation is a fallback, and rule 7 says every
- * fallback is labelled. The cost of not labelling this one is measured: a bare
- * `126` was read as a nested-sandbox incompatibility and the wrong root cause
- * outlived the session that filed it.
- */
-function startupOutputNote(services, captured) {
-    const failedSilently = services.filter((service) => service.started && service.startupOutput === null);
-    if (failedSilently.length === 0)
-        return null;
-    const names = failedSilently.map((service) => service.service).join(", ");
-    if (captured === null) {
-        return (`No startup output is shown for ${names} because the installed ` +
-            "@descryy/runtime-orchestrator does not return it — not because the service printed nothing. " +
-            "An exit code on its own does not say why a service failed, and can mislead: 126 means the " +
-            "command was found and could not be executed, which is also what a perfectly working sandbox " +
-            "reports. Upgrade the runtime to see the reason the process actually gave.");
-    }
-    return (`${names} produced no captured output before failing, so this run cannot say why beyond the exit ` +
-        "code and signal recorded above. That is an absence of evidence about the failure, not evidence " +
-        "that the service failed quietly.");
-}
-/**
- * The tail of a failed service's captured output that survives into the reply.
- *
- * Tail rather than head: a process that dies prints its reason last, so
- * clipping from the front is the one choice guaranteed to discard the line this
- * field exists to carry.
- */
-export const STARTUP_OUTPUT_TAIL_LIMIT = 4_000;
-/** One row per **declared** service, not per spawned process — a never-started service
- *  appears with `started: false` rather than vanishing ("it did nothing" vs "it never ran").
- *
- *  `startupOutput` is keyed by service name. Callers pass `{}` for a run that did
- *  not fail; the policy lives at the call site, where the outcome is known, rather
- *  than in here. Exported for `observe-runtime-startup-output.test.ts`, which pins
- *  the mapping without needing a runtime new enough to produce real output. */
-export function describeServices(processes, declared, startupOutput = {}) {
-    const byService = new Map();
-    for (const handle of processes) {
-        if (handle.serviceName !== null)
-            byService.set(handle.serviceName, handle);
-    }
-    return declared.map((service) => {
-        const handle = byService.get(service.name);
-        // A service with no process never ran, so anything keyed under its name is
-        // not its output — reporting it would attribute one service's words to
-        // another.
-        const captured = handle === undefined ? undefined : startupOutput[service.name];
-        const truncated = captured !== undefined && captured.length > STARTUP_OUTPUT_TAIL_LIMIT;
-        return {
-            service: service.name,
-            started: handle !== undefined,
-            attached: service.attached,
-            port: handle?.port ?? null,
-            exitedAt: handle?.exitedAt ?? null,
-            exitCode: handle?.exitCode ?? null,
-            signal: handle?.signal ?? null,
-            startupOutput: captured === undefined ? null : truncated ? captured.slice(-STARTUP_OUTPUT_TAIL_LIMIT) : captured,
-            startupOutputTruncated: truncated,
-        };
-    });
-}
-function tally(evidence) {
-    const byType = {};
-    for (const item of evidence)
-        byType[item.eventType] = (byType[item.eventType] ?? 0) + 1;
-    return byType;
-}
-/** One evidence row onto one of @descryy/ir's six RUNTIME_SIGNAL_TYPES, or null. Decided by
- *  `eventType`; `source` consulted only for the ambiguous EXCEPTION/STACK_TRACE pair (reading
- *  `source` alone was measured wrong). Unlisted kinds fail closed to null, never guess-mapped. */
-function signalOf(item) {
-    switch (item.eventType) {
-        case "CONSOLE_MESSAGE":
-            return "browser-console";
-        case "NETWORK_REQUEST":
-        case "NETWORK_RESPONSE":
-        case "HTTP_ERROR":
-        case "WEBSOCKET_CLOSED":
-            return "network";
-        case "SCREENSHOT":
-        case "VIDEO":
-            return "browser-visual";
-        case "BACKEND_LOG":
-            return "backend-log";
-        case "DATABASE_QUERY":
-            return "database";
-        case "EXTERNAL_REQUEST":
-            return "external-service";
-        // The ambiguous pair: a thrown error reaches Descry through whichever collector saw it.
-        case "EXCEPTION":
-        case "STACK_TRACE":
-            return item.source === "browser-console" ? "browser-console" : "backend-log";
-        default:
-            return null;
-    }
-}
-/** `E` for this run — channels actually seen, via @descryy/ir's independentSignalTypes
- *  (clamp-to-six and null-drop are that function's rules, not duplicated here). Exported for
- *  its own test — this mapping decides `strongly supported` vs `unconfirmed`. */
-export function witnessedSignalTypes(evidence) {
-    return independentSignalTypes(evidence.map((item) => ({ signal: signalOf(item), detail: item.eventType })));
-}
-/**
- * The R4 write, and the one join this tool performs: for every evidence item resolved to an
- * endpoint that also carries a call-site stack, ask confirmObservedFrontendCaller. Both come
- * from one observation — nothing here pairs two separate evidence items, on purpose.
- *
- * A stack resolved on some OTHER evidence item (`family === "symbol"`, e.g. a BACKEND_LOG or
- * EXCEPTION line elsewhere in the same run) is never joined to an endpoint item that lacks its
- * own stack, even when both exist in the same run's evidence. `resolveObservedFrontendCaller`
- * takes a stack on faith as "the call site that reached this endpoint" — it does not itself
- * verify the direction, so the caller supplying the wrong stack is exactly how a wrong edge
- * gets minted at R4 with full confidence. Nothing on `Evidence` disambiguates that direction
- * for a cross-record pair: `traceId`/`requestId` can say two items belong to the same request,
- * never that the stack-bearing one is the endpoint's CALLER rather than code running inside its
- * own handling of that same request — which is the common shape (a handler's own exception
- * stack, correlated to the request it was handling, not to whoever issued it). Joining on that
- * key would systematically mint edges in the SERVES direction mislabelled as CALLS/USES_API —
- * worse than the gap disclosed below (rule 2). So this is measured and reported via
- * `unjoinedSplitEvidence`, never inferred into an edge.
- */
-export function writeObservations(input) {
-    const promoted = [];
-    const created = [];
-    const confirmed = [];
-    const refused = [];
-    const contradictions = [];
-    const staleR4 = [];
-    const confirmedFactConflict = [];
-    // One evidence item can be attributed twice; keyed on both so the same (evidence,
-    // endpoint) pair is never confirmed twice within one run.
-    const seen = new Set();
-    // Split-evidence gap, tracked rather than acted on — see this function's own doc.
-    let unpairedEndpoints = 0;
-    let resolvedSymbolsElsewhere = 0;
-    for (const attribution of input.pass.attributed) {
-        if (attribution.family === "symbol") {
-            const evidence = input.evidenceStore.getById(attribution.evidenceId);
-            if (evidence !== null && evidence.stackTrace !== null)
-                resolvedSymbolsElsewhere += 1;
-            continue;
-        }
-        // "endpoint" only — "log-text-endpoint" fires when a log line mentions a route, which
-        // means the function SERVES it, not calls it; minting from that could point the wrong
-        // way. Rule 2: a wrong edge is worse than a missing (disclosed) one. Omitted.
-        if (attribution.family !== "endpoint")
-            continue;
-        const key = `${attribution.evidenceId}::${attribution.graphNodeId}`;
-        if (seen.has(key))
-            continue;
-        seen.add(key);
-        const evidence = input.evidenceStore.getById(attribution.evidenceId);
-        if (evidence === null || evidence.stackTrace === null) {
-            unpairedEndpoints += 1;
-            continue;
-        }
-        const outcome = confirmObservedFrontendCaller(input.driver, {
-            endpointNodeId: attribution.graphNodeId,
-            stackTrace: evidence.stackTrace,
-            repo: input.repo,
-            runId: input.runId,
-            commitSha: input.commitSha,
-            repoRoot: input.repoRoot,
-        });
-        promoted.push(...outcome.confirmation.promoted);
-        created.push(...outcome.confirmation.created);
-        confirmed.push(...outcome.confirmation.confirmed);
-        refused.push(...outcome.confirmation.refused.map((r) => r.reason));
-        contradictions.push(...outcome.confirmation.contradictions.map((c) => c.detail));
-        staleR4.push(...outcome.confirmation.staleR4.map((s) => s.detail));
-        // `confirmedFactConflict` cannot be read here yet: `outcome.confirmation` is typed
-        // against `@descryy/runtime-graph-correlator`'s OWN pinned, nested `@descryy/core`
-        // (0.5.2 at last check — DEC-395's exact cross-repo pins), which predates this field.
-        // Also moot in practice today: this call path never emits a denial at all (see this
-        // function's own header doc, and `contradictions`/`staleR4` above, which are "always
-        // empty today" for the same reason) — so there is nothing for a human-confirmed edge
-        // to collide with here regardless. Once the correlator republishes against a core
-        // carrying `confirmedFactConflict`, thread it through the same way as the lines above.
-    }
-    const unjoinedSplitEvidence = unpairedEndpoints > 0 && resolvedSymbolsElsewhere > 0
-        ? `This run reached ${String(unpairedEndpoints)} endpoint attribution(s) carrying no call-site ` +
-            `stack of their own, and separately resolved ${String(resolvedSymbolsElsewhere)} call-site ` +
-            "stack(s) to a real function elsewhere in this run's evidence. The two are not joined: this " +
-            "tool only promotes an edge from one observation that names both the endpoint and the stack " +
-            "itself, because a stack found on a different evidence record cannot be shown to be the " +
-            "endpoint's CALLER rather than code that merely ran during its own handling of the same " +
-            "request — minting from that risks an edge pointing the wrong way, which this project's rules " +
-            "treat as worse than the gap this note discloses. No edge was written for this pairing; it is " +
-            "real signal this run could not safely turn into a fact, not evidence that no such call exists."
-        : null;
-    return { promoted, created, confirmed, refused, contradictions, staleR4, confirmedFactConflict, unjoinedSplitEvidence };
-}
-/** §7's `willDo` — and, since readArguments runs first, where an invalid call is refused.
- *  Always returns a string, never undefined: unlike `questions`, no call here has nothing
- *  to confirm. Reads the *parsed* services so the confirmation sentence matches the run exactly. */
-/** Exported for the same reason as `run` above — `observe.ts` dispatches the "runtime" verb's
- *  consent sentence to this exact function. */
-export function describeAction(args, ctx) {
-    const { declared } = readArguments(args, ctx.session.repoPath);
-    const spawned = declared.filter((service) => !service.attached).map((service) => service.name);
-    const attached = declared.filter((service) => service.attached).map((service) => service.name);
-    const parts = [];
-    if (spawned.length > 0)
-        parts.push(`start ${String(spawned.length)} service(s) (${spawned.join(", ")})`);
-    if (attached.length > 0) {
-        parts.push(`attach to ${String(attached.length)} already-running service(s) (${attached.join(", ")})`);
-    }
-    return (`${parts.join(" and ")}, observe them, and write any edge the run witnesses into this ` +
-        "repository's graph at R4 — a durable fact that raises every later finding resting on it to " +
-        "reliability class A, and that survives re-indexing. Nothing is ever demoted or deleted.");
-}
-export const observeRuntimeTool = {
-    name: "observe_runtime",
-    class: "action",
-    tier: "evidence",
-    version: "1.0.0",
-    title: "Run the application and record what was observed",
-    description: "Boot or attach to the declared services, watch them with a runtime adapter, resolve what was " +
-        "observed against this repository's graph, and record the edges the run actually witnessed at R4 " +
-        "— the one resolution level static analysis cannot reach. Promoted and newly minted edges become " +
-        "visible through impact, propagation and every other tool immediately, with no second call: they " +
-        "already read the resolution field. Running takes a two-call confirmation — the first call " +
-        "performs nothing and returns a token describing what it would do; call again with " +
-        "\"confirmToken\" to actually run it. The environment profile's declared safetyLevel is checked " +
-        "before anything starts: booting is a write, attaching is not. " +
-        "BEFORE CALLING: this observes an application you can already run — it does not help you get to " +
-        "a runnable state, and that boundary is real rather than apologetic. Its dependencies must be up, " +
-        "its environment set, and its migrations applied, all by you. One trap worth stating because it " +
-        "is invisible: overriding some environment variables does not isolate a run from the " +
-        "application's own configuration file — anything you did not explicitly override is still read " +
-        "from it, including values naming environments you did not intend to touch.",
-    inputSchema: SCHEMA,
-    run,
-    describeAction,
-};
-//# sourceMappingURL=observe-runtime.js.map