@unbrained/pm-web 2026.8.14 → 2026.8.28

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## Unreleased
+
+### Fixed
+
+- The health endpoint no longer reports ok: true when the database or projects volume is unreachable ([pm-web-u9mh](https://github.com/unbraind/pm-web/blob/main/.agents/pm/issues/pm-web-u9mh.toon))
+- Mount the real /healthz handler in pm-web (Greptile P1 on PR \#105) ([pm-web-iocm](https://github.com/unbraind/pm-web/blob/main/.agents/pm/issues/pm-web-iocm.toon))
+
+## 2026.8.28 - 2026-08-28
+
+### Fixed
+
+- The changelog gate stamps an untagged version with the current date, so its verdict flips every midnight with no commit ([pm-web-kcs1](https://github.com/unbraind/pm-web/blob/main/.agents/pm/issues/pm-web-kcs1.toon))
+- Certify pm-web complete tracker reads and refresh the package catalog ([pm-web-crdr](https://github.com/unbraind/pm-web/blob/main/.agents/pm/issues/pm-web-crdr.toon))
+- Docstring corrections: filters, graph-canvas, crypto, board, pm routes, project-watcher, sse, mutation-event-watcher ([pm-web-oehb](https://github.com/unbraind/pm-web/blob/main/.agents/pm/issues/pm-web-oehb.toon))
+- Fix release publish-before-protected-main-push ordering ([pm-web-8l6j](https://github.com/unbraind/pm-web/blob/main/.agents/pm/issues/pm-web-8l6j.toon))
+
+### Security
+
+- The identity gate deadlocks the one remediation its own failure message prescribes ([pm-web-1ggj](https://github.com/unbraind/pm-web/blob/main/.agents/pm/issues/pm-web-1ggj.toon))
+
+## 2026.8.17 - 2026-08-17
+
+### Fixed
+
+- The package catalog could silently omit a fleet package, and had already drifted from pm-ops capabilities ([pm-web-yqmi](https://github.com/unbraind/pm-web/blob/main/.agents/pm/issues/pm-web-yqmi.toon))
+
 ## 2026.8.14 - 2026-08-14
 
 ### Fixed

package/README.md

@@ -149,6 +149,19 @@ within each Node process, so high-throughput installations should run multiple
 pm-web replicas behind a shared PostgreSQL realtime bus. Independent replicas
 converge through PostgreSQL notifications and the mutation-event watcher.
 
+Whole-project graph fallback, board, local search, iCalendar, and export reads
+use the SDK's high-level `listAllComplete` operation. pm-web accepts those rows
+only after the shared SDK certificate and supplemental 2026.8.21 source,
+omission, output-receipt, and budget checks all agree. The public `/pm/list-all`
+HTTP compatibility route remains deliberately paginated for interactive clients,
+but invokes canonical `list --all` internally; consumers that need the whole
+workspace must use a complete-read endpoint rather than assembling a page as if
+it were the corpus. The standalone server exact-pins pm CLI/SDK 2026.8.21, and
+the extension manifest refuses older hosts through the same compatibility floor.
+Commands that render their own text or JSON (`web status`, `web stop`, and
+`web doctor`) return the public SDK output-suppression marker, so the host never
+appends a second payload to stdout.
+
 Optional OIDC uses Authorization Code flow with PKCE, provider discovery/JWKS,
 signed state cookies, and issuer/subject identity mapping. It is disabled when
 no OIDC variables are present and production startup fails closed on partial or
@@ -186,13 +199,29 @@ MIT
 
 ## Release Automation
 
-This package is release-ready for GitHub, npm, and Bun-compatible installs. CI runs type checking, build, production dependency audit, package packing, Bun install verification, and pm-changelog validation. The daily release workflow publishes only when commits exist after the latest release tag and uses pm-changelog to generate CHANGELOG.md and GitHub release notes.
+CI runs type checking, exact Node 22.18.0 and current-Node matrices, real
+PostgreSQL integration tests, the configured coverage gate, complete docstring
+coverage, production dependency audit, package packing, fresh packed `npx` and
+`bunx` install-and-command acceptance, immutable workflow-action checks, and
+pm-changelog validation. The daily release
+workflow publishes at most once when commits exist after the latest release tag
+and uses pm-changelog for both `CHANGELOG.md` and GitHub release notes.
+
+The current package is **not** approved for a new release: exact all-source
+100/100/100/100 coverage remains open in
+[`pm-web-9ulj`](.agents/pm/epics/pm-web-9ulj.toon) and
+[`pm-web-ulgy`](.agents/pm/tasks/pm-web-ulgy.toon), while reachable-history
+privacy authorization is tracked in
+[`pm-web-priv`](.agents/pm/issues/pm-web-priv.toon) and
+[GitHub issue #96](https://github.com/unbraind/pm-web/issues/96). Passing the
+configured gate is evidence for the measured source set, not those independent
+release approvals.
 
 ## New data endpoints (kanban board & search)
 
-The pm data API now exposes board and search views, both driven by the
-workspace's live `pm contracts` schema (so they reflect the installed pm CLI +
-extensions):
+The pm data API exposes board and search views through the certified
+complete-read contract described above. The board also uses the workspace's
+live `pm contracts` statuses for its columns:
 
 - `GET /api/projects/:projectId/pm/board` — items grouped into kanban columns by
   the workspace's runtime statuses (unlisted statuses fall into `(other)`).

package/dist/app.d.ts

@@ -1,4 +1,5 @@
 import { type Express } from "express";
+import { type HealthProbeDeps } from "./health.ts";
 /**
  * Legal pages served as standalone HTML (not part of the SPA bundle).
  *
@@ -34,10 +35,33 @@ export declare const LEGAL_REDIRECTS: Record<string, string>;
  * @returns The real, resolved directory path holding the legal HTML files.
  */
 export declare function resolveLegalPagesDir(env?: NodeJS.ProcessEnv): string;
+/**
+ * Optional dependencies `createApp` can wire into the application.
+ *
+ * Currently only the {@link HealthProbeDeps} for the real `/healthz` handler is
+ * supported; the object is kept as a bag so further production-only wiring
+ * (e.g. a logger) can be added later without another signature change.
+ */
+export interface CreateAppDeps {
+    /**
+     * Health-probe dependencies for the real `/healthz` handler. When supplied,
+     * `createApp` mounts {@link createHealthHandler}, which probes PostgreSQL and
+     * the projects volume and answers 200/503 accordingly. When omitted, the
+     * route answers 503 `ok:false` (see the comment at the route) so a
+     * misconfigured deployment can never report healthy while its dependencies
+     * are down — the exact failure this handler was written to close.
+     */
+    readonly health?: HealthProbeDeps;
+}
 /**
  * Build the Express application with all middleware, static assets, legal
  * page routes, API routes and the SPA fallback — but WITHOUT touching the
  * database or binding a port. Splitting this out from server.ts keeps the
  * HTTP surface unit-testable without a running PostgreSQL instance.
+ *
+ * @param deps - Optional production wiring. Pass `health` to mount the real
+ *   probing `/healthz` handler; omit it for tests that only need the HTTP
+ *   surface (the route then answers 503 `ok:false`, never `ok:true`).
+ * @returns The configured Express application, not yet listening on a port.
  */
-export declare function createApp(): Express;
+export declare function createApp(deps?: CreateAppDeps): Express;

package/dist/app.js

@@ -3,6 +3,7 @@ import cookieParser from "cookie-parser";
 import path from "node:path";
 import { accessSync, constants, lstatSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { fileURLToPath } from "node:url";
+import { createHealthHandler } from "./health.js";
 import { authRouter } from "./routes/auth.js";
 import { oidcRouter } from "./routes/oidc.js";
 import { projectsRouter } from "./routes/projects.js";
@@ -95,8 +96,13 @@ export function resolveLegalPagesDir(env = process.env) {
  * page routes, API routes and the SPA fallback — but WITHOUT touching the
  * database or binding a port. Splitting this out from server.ts keeps the
  * HTTP surface unit-testable without a running PostgreSQL instance.
+ *
+ * @param deps - Optional production wiring. Pass `health` to mount the real
+ *   probing `/healthz` handler; omit it for tests that only need the HTTP
+ *   surface (the route then answers 503 `ok:false`, never `ok:true`).
+ * @returns The configured Express application, not yet listening on a port.
  */
-export function createApp() {
+export function createApp(deps) {
     const app = express();
     const legalPagesDir = resolveLegalPagesDir();
     app.use(express.json({ limit: "1mb" }));
@@ -128,7 +134,25 @@ export function createApp() {
             return "unknown";
         }
     })();
-    app.get("/healthz", (_req, res) => res.json({ ok: true, version: PM_WEB_VERSION }));
+    if (deps?.health) {
+        // Production wiring: probe PostgreSQL and the projects volume before
+        // answering. `server.ts` always supplies these dependencies, so the
+        // deployed service reports healthy only when its hard dependencies are
+        // actually reachable.
+        app.get("/healthz", createHealthHandler(deps.health));
+    }
+    else {
+        // No health-probe dependencies were supplied, so this route cannot probe
+        // PostgreSQL or the projects volume. Answering `ok:true` here would
+        // reproduce the original bug this handler exists to close: pm-web has
+        // previously served frozen data for two days while `/healthz` reported
+        // healthy. A route that cannot probe must not claim `ok:true`, so the
+        // unconfigured default answers 503 with the version only. Production
+        // (`server.ts`) always supplies the real dependencies; this branch is
+        // reached only by tests that exercise the HTTP surface without a database
+        // and by misconfigured deployments, which must fail loud rather than lie.
+        app.get("/healthz", (_req, res) => res.status(503).json({ ok: false, version: PM_WEB_VERSION }));
+    }
     const legalPages = new Set(LEGAL_PAGES);
     Object.entries(LEGAL_REDIRECTS).forEach(([from, to]) => {
         app.get(from, (_req, res) => {

package/dist/app.js.map

@@ -1 +1 @@
-{"version":3,"file":"app.js","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"app.js","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"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"}

package/dist/health.d.ts

@@ -0,0 +1,84 @@
+import type { RequestHandler } from "express";
+/**
+ * Minimum structural type a PostgreSQL pool must satisfy for the health probe.
+ *
+ * The real `pg.Pool` satisfies this, and tests can substitute any object whose
+ * `query` accepts a SQL string and returns a promise — so the probe runs
+ * through the same pool the service uses in production without forcing tests
+ * to construct a real database connection.
+ */
+export interface Queryable {
+    /** Execute a SQL string and return rows. */
+    query(text: string): Promise<{
+        rows: unknown[];
+    }>;
+}
+/** Status reported for one dependency in the health response. */
+export interface DependencyStatus {
+    /** Whether the dependency responded successfully. */
+    readonly ok: boolean;
+    /** Round-trip latency in milliseconds. */
+    readonly latency_ms: number;
+    /** Human-readable failure reason; omitted on success. */
+    readonly error?: string;
+    /**
+     * Whether the dependency was configured (env var present). Only meaningful
+     * for soft dependencies that may legitimately be absent; hard dependencies
+     * are always treated as configured.
+     */
+    readonly configured?: boolean;
+}
+/** A named soft-dependency probe whose result does not affect the status code. */
+export interface SoftProbe {
+    /** Key under `dependencies` in the response. */
+    readonly name: string;
+    /** Async function returning the dependency status. */
+    readonly probe: () => Promise<DependencyStatus>;
+}
+/** Dependencies the health handler needs to probe. */
+export interface HealthProbeDeps {
+    /** PostgreSQL pool — probed with `SELECT 1` (hard dependency). */
+    readonly pool: Queryable;
+    /** Host-mounted projects root — probed for writability (hard dependency). */
+    readonly projectsRoot: string;
+    /** Package version, resolved once at boot from `package.json`. */
+    readonly version: string;
+    /** Soft-dependency probes; their results are reported but never cause 503. */
+    readonly softProbes?: ReadonlyArray<SoftProbe>;
+    /**
+     * Timing overrides, in milliseconds.
+     *
+     * Production never sets these. They exist because the behaviour that matters
+     * here -- what happens on the second cooldown expiry of a stall that has not
+     * ended -- is otherwise only reachable by a test that waits over half a
+     * minute, and a guard nothing executes is how a pool-drain protection stops
+     * working without anyone noticing.
+     */
+    readonly timing?: {
+        /** Overrides {@link PROBE_TIMEOUT_MS}. */
+        readonly probeTimeoutMs?: number;
+        /** Overrides {@link CACHE_TTL_MS}. */
+        readonly cacheTtlMs?: number;
+        /** Overrides {@link POOL_COOLDOWN_MS}. */
+        readonly poolCooldownMs?: number;
+    };
+}
+/** Shape of the `/healthz` response body (backward compatible: `ok`, `version`). */
+export interface HealthResult {
+    /** `true` only when every hard dependency is reachable. */
+    readonly ok: boolean;
+    /** Package version from `package.json`. */
+    readonly version: string;
+    /** Per-dependency breakdown. */
+    readonly dependencies: Readonly<Record<string, DependencyStatus>>;
+}
+/**
+ * Build the Express `/healthz` request handler.
+ *
+ * The handler probes every hard dependency in parallel, adds soft-dependency
+ * results, caches the outcome for {@link CACHE_TTL_MS} milliseconds, and
+ * responds with HTTP 200 (`ok: true`) or 503 (`ok: false`). It never throws:
+ * each probe catches its own errors, and the outer `try`/`catch` is a
+ * defensive last resort.
+ */
+export declare function createHealthHandler(deps: HealthProbeDeps): RequestHandler;

package/dist/health.js

@@ -0,0 +1,284 @@
+import { readdir, stat, unlink, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+/** Maximum time a single probe may run before it is considered failed. */
+const PROBE_TIMEOUT_MS = 2000;
+/** How long a computed health result is reused before re-probing. */
+const CACHE_TTL_MS = 5000;
+/**
+ * How long to skip the PostgreSQL probe after one times out.
+ *
+ * A timed-out query keeps a pool client until the server answers. Re-probing
+ * every cache expiry during a stall would drain the pool; this bounds it.
+ */
+const POOL_COOLDOWN_MS = 30_000;
+/** How old a stray `.healthz-*.tmp` file must be before a sweep removes it. */
+const STRAY_PROBE_MAX_AGE_MS = 60_000;
+/** Extract a string message from an unknown rejection value. */
+function errorMessage(error) {
+    // `/healthz` is unauthenticated, so the response must never carry a raw
+    // message: a pg failure names the host, port, database and user, and a
+    // filesystem failure names the projects-root path. Both are reconnaissance
+    // for an anonymous caller. Map to a stable category and keep the detail in
+    // the server log, where an operator can still read it.
+    const code = typeof error === "object" && error !== null && "code" in error
+        ? String(error.code)
+        : "";
+    const message = error instanceof Error ? error.message : String(error);
+    console.error("[healthz] probe failed", { code, message });
+    if (message === "probe timed out")
+        return "timed out";
+    if (code === "ENOENT")
+        return "not found";
+    if (code === "EACCES" || code === "EPERM" || code === "EROFS")
+        return "permission denied";
+    if (code === "ENOSPC")
+        return "no space left on device";
+    if (code === "ECONNREFUSED" || code === "ENOTFOUND" || code === "EHOSTUNREACH") {
+        return "unreachable";
+    }
+    return "unavailable";
+}
+/**
+ * Race a promise against a timeout, rejecting with `"probe timed out"` if the
+ * timeout fires first.
+ *
+ * The timer is cleared in both branches so a resolved/rejected probe does not
+ * leak a dangling timer, and a timed-out probe does not keep the event loop
+ * alive for the remaining lifetime of the underlying promise.
+ */
+function withTimeout(promise, ms) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error("probe timed out")), ms);
+        promise.then((value) => { clearTimeout(timer); resolve(value); }, (error) => { clearTimeout(timer); reject(error); });
+    });
+}
+/**
+ * Probe PostgreSQL by running `SELECT 1` through the provided queryable.
+ *
+ * Uses the service's real pool (not a fresh connection) so pool exhaustion is
+ * itself a failure mode the probe catches. The probe is bounded by
+ * {@link PROBE_TIMEOUT_MS}.
+ */
+function probePostgres(pool, timeoutMs) {
+    const start = Date.now();
+    // The raw query is returned alongside the status because the two settle at
+    // different times: the status settles when the timeout fires, the query only
+    // when PostgreSQL answers, and it is the query that holds a pool client.
+    // Anything deciding whether to start another probe has to wait on the query.
+    const query = pool.query("SELECT 1");
+    const status = withTimeout(query, timeoutMs).then(() => ({ ok: true, latency_ms: Date.now() - start }), (error) => ({ ok: false, latency_ms: Date.now() - start, error: errorMessage(error) }));
+    return { query, status };
+}
+/**
+ * Probe the projects root by writing and immediately removing a temp file
+ * inside it.
+ *
+ * A missing directory, a read-only host mount, or a full disk all surface as
+ * a write or unlink failure. The temp file is cleaned up in every path: on
+ * success it is unlinked by the probe itself, and on failure a best-effort
+ * cleanup removes it if the write succeeded but the unlink (or timeout) did
+ * not.
+ */
+async function probeProjectsRoot(root) {
+    const start = Date.now();
+    // A pid-and-millisecond name collides when two uncached probes start in the
+    // same millisecond: whichever unlinks first makes the other report ENOENT and
+    // return a spurious 503 for a perfectly healthy volume.
+    const probeFile = path.join(root, `.healthz-${randomUUID()}.tmp`);
+    // Held so cleanup can be attached to the attempt's own settlement rather than
+    // racing it. A timeout does not cancel the underlying write: unlinking
+    // immediately can therefore run BEFORE a slow write lands, leaving the file
+    // behind permanently - the opposite of what the cleanup is for.
+    const attempt = (async () => {
+        await writeFile(probeFile, "");
+        await unlink(probeFile);
+    })();
+    try {
+        await withTimeout(attempt, PROBE_TIMEOUT_MS);
+        return { ok: true, latency_ms: Date.now() - start };
+    }
+    catch (error) {
+        // NOT awaited, and bounded. A stalled mount is the exact condition that
+        // reaches this path, and an unbounded `await unlink` here would never
+        // settle: probeProjectsRoot would never resolve, the Promise.all in
+        // compute() would never resolve, `inFlight` would never clear, and every
+        // subsequent /healthz request would await the same pending promise forever
+        // - serving nothing at all instead of 503.
+        void attempt.catch(() => undefined).finally(() => {
+            void withTimeout(unlink(probeFile), PROBE_TIMEOUT_MS).catch(() => undefined);
+        });
+        return { ok: false, latency_ms: Date.now() - start, error: errorMessage(error) };
+    }
+}
+/**
+ * Remove `.healthz-*.tmp` files older than {@link STRAY_PROBE_MAX_AGE_MS}.
+ *
+ * A probe whose write lands after its own cleanup has already run leaves a
+ * stray file that nothing else will remove. Sweeping on each healthy probe
+ * bounds how long such a file can persist, without ever failing the probe:
+ * a sweep error is not a health signal and is deliberately swallowed.
+ *
+ * @param root - The projects root to sweep.
+ */
+async function sweepStrayProbeFiles(root) {
+    try {
+        const now = Date.now();
+        for (const name of await readdir(root)) {
+            if (!name.startsWith(".healthz-") || !name.endsWith(".tmp"))
+                continue;
+            const full = path.join(root, name);
+            const info = await stat(full);
+            if (now - info.mtimeMs > STRAY_PROBE_MAX_AGE_MS)
+                await unlink(full);
+        }
+    }
+    catch {
+        // Sweeping is housekeeping, not a dependency check.
+    }
+}
+/**
+ * Run a soft-dependency probe, catching any synchronous throw, rejection, or
+ * timeout so a broken soft probe can never throw into the health handler.
+ */
+async function runSoftProbe(probe) {
+    try {
+        const status = await withTimeout(probe.probe(), PROBE_TIMEOUT_MS);
+        return [probe.name, status];
+    }
+    catch (error) {
+        return [probe.name, { ok: false, latency_ms: 0, error: errorMessage(error) }];
+    }
+}
+/**
+ * Build the Express `/healthz` request handler.
+ *
+ * The handler probes every hard dependency in parallel, adds soft-dependency
+ * results, caches the outcome for {@link CACHE_TTL_MS} milliseconds, and
+ * responds with HTTP 200 (`ok: true`) or 503 (`ok: false`). It never throws:
+ * each probe catches its own errors, and the outer `try`/`catch` is a
+ * defensive last resort.
+ */
+export function createHealthHandler(deps) {
+    let cached = null;
+    // Concurrent cache misses must share ONE computation. `withTimeout` rejects
+    // its wrapper but cannot cancel the underlying `pool.query`, so without this
+    // every request during a hung database starts another query that keeps
+    // running after the endpoint has already answered 503 - consuming pool
+    // capacity and starving the ordinary API. Single-flight bounds the damage to
+    // one in-flight probe no matter how often the endpoint is polled.
+    let inFlight = null;
+    // Epoch ms of the last PostgreSQL probe timeout, or 0 if none has timed out.
+    let lastPostgresTimeoutAt = 0;
+    // A timed-out probe's query is still outstanding: `withTimeout` rejects its
+    // wrapper, it cannot cancel `pool.query`. Elapsed time alone is therefore the
+    // wrong condition to start another one -- during a prolonged stall the
+    // cooldown expires on schedule while the previous client is still checked
+    // out, and the pool drains one client per cooldown. This holds the query
+    // itself, so at most one probe is ever outstanding however long the database
+    // takes to answer.
+    let outstandingPostgresProbe;
+    const probeTimeoutMs = deps.timing?.probeTimeoutMs ?? PROBE_TIMEOUT_MS;
+    const cacheTtlMs = deps.timing?.cacheTtlMs ?? CACHE_TTL_MS;
+    const poolCooldownMs = deps.timing?.poolCooldownMs ?? POOL_COOLDOWN_MS;
+    /**
+     * Probe every dependency once and cache the outcome.
+     *
+     * Separated from the handler so concurrent cache misses can await a single
+     * shared promise rather than each starting their own probe round.
+     *
+     * @returns The freshly computed health result, already written to the cache.
+     */
+    async function compute() {
+        let result;
+        try {
+            // `withTimeout` rejects its wrapper but cannot cancel `pool.query`, so a
+            // timed-out probe leaves a client checked out until PostgreSQL answers.
+            // Without a cooldown, every cache expiry starts another one and a stalled
+            // database drains the shared pool out from under the ordinary API. After
+            // a timeout the probe is not retried for POOL_COOLDOWN_MS; the endpoint
+            // keeps answering 503 from the reported status in the meantime.
+            /**
+             * Start one PostgreSQL probe and hold its query until PostgreSQL answers.
+             *
+             * @returns The probe's status.
+             */
+            const startPostgresProbe = () => {
+                const { query, status } = probePostgres(deps.pool, probeTimeoutMs);
+                // Cleared when the QUERY settles, not when the status does. A timed-out
+                // probe reports in milliseconds while its client stays checked out
+                // until PostgreSQL answers, so clearing on the status would let the
+                // next cooldown expiry check out another one on top of it.
+                outstandingPostgresProbe = query;
+                const release = () => {
+                    if (outstandingPostgresProbe === query)
+                        outstandingPostgresProbe = undefined;
+                };
+                void query.then(release, release);
+                return status;
+            };
+            const cooling = Date.now() - lastPostgresTimeoutAt < poolCooldownMs;
+            const outstanding = outstandingPostgresProbe !== undefined;
+            const postgresProbe = cooling || outstanding
+                ? Promise.resolve({
+                    ok: false,
+                    latency_ms: 0,
+                    error: outstanding ? "previous probe still outstanding" : "probe cooling down after timeout",
+                })
+                : startPostgresProbe().then((status) => {
+                    // "timed out" is errorMessage()'s stable category, not the raw
+                    // message: /healthz is unauthenticated, so the raw text is
+                    // deliberately never surfaced. Matching the category is what makes
+                    // this survive a change to the underlying error string.
+                    if (!status.ok && status.error === "timed out") {
+                        lastPostgresTimeoutAt = Date.now();
+                    }
+                    return status;
+                });
+            const [postgres, projectsRootStatus, ...softResults] = await Promise.all([
+                postgresProbe,
+                probeProjectsRoot(deps.projectsRoot),
+                ...(deps.softProbes?.map(runSoftProbe) ?? []),
+            ]);
+            const dependencies = {
+                postgres,
+                projects_root: projectsRootStatus,
+            };
+            for (const [name, status] of softResults) {
+                dependencies[name] = status;
+            }
+            if (projectsRootStatus.ok)
+                void sweepStrayProbeFiles(deps.projectsRoot);
+            result = {
+                ok: postgres.ok && projectsRootStatus.ok,
+                version: deps.version,
+                dependencies,
+            };
+        }
+        catch {
+            // Every probe catches its own errors; this is a defensive last resort
+            // so the handler can never throw an unhandled error into Express.
+            result = {
+                ok: false,
+                version: deps.version,
+                dependencies: {
+                    postgres: { ok: false, latency_ms: 0, error: "unexpected handler error" },
+                    projects_root: { ok: false, latency_ms: 0, error: "unexpected handler error" },
+                },
+            };
+        }
+        cached = { result, at: Date.now() };
+        return result;
+    }
+    const handler = async (_req, res) => {
+        if (cached && Date.now() - cached.at < cacheTtlMs) {
+            res.status(cached.result.ok ? 200 : 503).json(cached.result);
+            return;
+        }
+        inFlight ??= compute().finally(() => { inFlight = null; });
+        const result = await inFlight;
+        res.status(result.ok ? 200 : 503).json(result);
+    };
+    return handler;
+}
+//# sourceMappingURL=health.js.map

package/dist/health.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.js","sourceRoot":"","sources":["../src/health.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { type ExtensionApi } from "@unbrained/pm-cli/sdk";
+import { type ExtensionApi, type SuppressedHostOutput } from "@unbrained/pm-cli/sdk";
 /** Resolve the port from flag → PORT env → default 4000. */
 export declare function resolvePort(options: Record<string, unknown>, env?: NodeJS.ProcessEnv): string;
 /**
@@ -19,21 +19,43 @@ export declare function pidfilePath(port: string | number, env?: NodeJS.ProcessE
  * @returns True when the version is at least 22.18.0.
  */
 export declare function nodeVersionMeetsRequirement(version?: string): boolean;
-/** Shape a /healthz probe outcome into a stable status result object. */
+/**
+ * Shape a /healthz probe outcome into a stable status result object.
+ *
+ * Reachability and readiness are separate answers. A server whose dependencies
+ * are down answers 503 while being perfectly reachable, and reporting that as
+ * DOWN sends an operator to look for a process that is running -- so the two
+ * are reported separately, with "degraded" naming the state in between.
+ */
 export declare function shapeStatusResult(input: {
     port: string | number;
     reachable: boolean;
+    healthy?: boolean;
     body?: unknown;
     error?: string;
 }): {
-    status: "up" | "down";
+    status: "up" | "degraded" | "down";
     port: number;
     reachable: boolean;
+    healthy: boolean;
     url: string;
     version: string | null;
     healthz: unknown;
     error?: string;
 };
+/**
+ * Write a command-owned JSON or human-readable payload exactly once.
+ *
+ * The public SDK marker retains the structured result for hooks and embedded
+ * hosts while preventing the CLI presentation layer from appending a second
+ * serialization to stdout.
+ *
+ * @param json - Whether to render the structured JSON representation.
+ * @param result - Structured command result retained for host integrations.
+ * @param humanLines - Lines rendered for an interactive non-JSON invocation.
+ * @returns The host-output suppression marker carrying the structured result.
+ */
+export declare function emitOwnedOutput<TResult>(json: boolean, result: TResult, humanLines: readonly string[]): SuppressedHostOutput<TResult>;
 declare const _default: {
     name: string;
     version: string;