@descryy/mcp 0.11.2 → 0.11.4

package/dist/tools/observe-runtime.js

@@ -11,6 +11,7 @@ import { checkNotSensitivePath, checkPathConfinement } from "../path-confinement
 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";
@@ -21,7 +22,7 @@ import { cancellationHeadline, cancellationNotes, whenAborted } from "../cancell
 import { readScenario } from "../scenarios/index.js";
 import { createRuntimeJourneyDrive, projectScenarioToRunPlan, } from "./runtime-journey-drive.js";
 import { loadRuntimeAdapter, RuntimeAdapterLoadError } from "../runtime-registry.js";
-import { writeConfirmedIncident } from "../session.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");
@@ -62,8 +63,12 @@ const SCHEMA = {
         },
         services: {
             type: "object",
-            description: "One entry per service, keyed by the name evidence will be attributed to. At least one is " +
-                "required. Exactly one of \"command\" or \"attach\" per service.",
+            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: {
@@ -281,8 +286,35 @@ const SCHEMA = {
             },
             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", "services", "adapter"],
+    required: ["profile", "adapter"],
     additionalProperties: false,
 };
 function asRecord(value, what) {
@@ -373,12 +405,91 @@ function readAdapterSpec(args) {
         ...(options === undefined ? {} : { options: options }),
     };
 }
-function readServices(args, repoPath) {
-    const raw = asRecord(args["services"], "services");
+/** `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');
-    return names.map((name) => {
+    const declared = names.map((name) => {
         const entry = asRecord(raw[name], `services.${name}`);
         const command = entry["command"];
         const attachRaw = entry["attach"];
@@ -465,13 +576,25 @@ function readServices(args, repoPath) {
             ...(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
@@ -752,10 +875,40 @@ function readJourney(args) {
     const settleForMs = optionalInteger(record, "settleForMs", 0);
     return { service, scenarioName, startUrl, recordVideo, headless, settleForMs };
 }
-export function readArguments(args, repoPath) {
+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 = readServices(args, repoPath);
+    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;
@@ -783,10 +936,13 @@ export function readArguments(args, repoPath) {
     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,
@@ -797,16 +953,147 @@ export function readArguments(args, repoPath) {
         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, observeForMs, timeoutMs, fidelityRaw, environmentTier, evidencePath, resourceLimits, filesystemPolicy, networkPolicy, sandboxBackend, journey, } = readArguments(args, session.repoPath);
+    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.
+    // 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);
     }
@@ -833,6 +1120,7 @@ export async function run(args, ctx) {
             correlation: null,
             wrote: EMPTY_WRITE,
             journey: null,
+            database: null,
             ...data,
         },
     });
@@ -884,7 +1172,7 @@ export async function run(args, ctx) {
     const services = {};
     const readiness = {};
     for (const service of declared) {
-        services[service.name] = service.configuration;
+        services[service.name] = withDatabaseObservationPreload(service.configuration, adapter);
         readiness[service.name] = service.readiness;
     }
     const configuration = {
@@ -971,6 +1259,13 @@ export async function run(args, ctx) {
     // 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({
@@ -1038,7 +1333,11 @@ export async function run(args, ctx) {
         // 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,
@@ -1050,6 +1349,28 @@ export async function run(args, ctx) {
                 "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
@@ -1058,7 +1379,12 @@ export async function run(args, ctx) {
         // 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.
-        const evidenceIncludingJourney = journeyOutcome === undefined ? execution.evidence : [...evidenceStore.getByExecution(execution.execution.executionId)];
+        // 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".
@@ -1066,9 +1392,17 @@ export async function run(args, ctx) {
                 "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-
@@ -1095,6 +1429,11 @@ export async function run(args, ctx) {
             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({
@@ -1199,6 +1538,34 @@ export async function run(args, ctx) {
         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 ` +
@@ -1237,14 +1604,21 @@ export async function run(args, ctx) {
                 adapterLanguage: adapter.language,
                 evidencePath,
                 services,
-                evidenceByType: journeyOutcome === undefined ? evidenceByType : tally(evidenceIncludingJourney),
+                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();
     }