@clivly/core 0.9.1 → 0.9.3

package/dist/integration-state.cjs

@@ -31,8 +31,6 @@ const STEP_PREREQUISITES = {
 function stepIndex(id) {
 	return INTEGRATION_STEPS.indexOf(id);
 }
-/** A heartbeat older than this means the app stopped checking in. */
-const HEARTBEAT_STALE_MS = 600 * 1e3;
 function formatAge(ms) {
 	if (ms < 6e4) return `${Math.max(1, Math.round(ms / 1e3))}s ago`;
 	if (ms < 36e5) return `${Math.round(ms / 6e4)}m ago`;
@@ -41,12 +39,96 @@ function formatAge(ms) {
 function heartbeatAge(facts) {
 	return facts.lastHeartbeatAt === null ? null : facts.now - facts.lastHeartbeatAt;
 }
+/** The cadence `createClivlySDK` uses when the host app configures none. */
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 6e4;
+const LIVE_INTERVALS = 2.5;
+const STALE_INTERVALS = 10;
+/**
+* The two boundaries that separate live from stale from offline, in terms of
+* the app's own reported cadence. A cadence we cannot believe — absent, zero,
+* negative — falls back to the SDK default rather than producing a window of
+* zero that would call every app offline.
+*/
+function livenessWindows(intervalMs) {
+	const interval = typeof intervalMs === "number" && intervalMs > 0 ? intervalMs : DEFAULT_HEARTBEAT_INTERVAL_MS;
+	return {
+		liveMs: interval * LIVE_INTERVALS,
+		staleMs: interval * STALE_INTERVALS
+	};
+}
+/**
+* Faults worth showing on an app that is up. Deliberately excludes anything the
+* developer simply has not done yet — no schema, no mapping, no trigger are all
+* setup stages, and painting a fresh install amber would make the signal
+* meaningless.
+*/
+function livenessIssues(facts) {
+	const issues = [...facts.reportedIssues ?? []];
+	if (facts.lastRun && !facts.lastRun.ok) issues.push({
+		code: "sync_failed",
+		message: facts.lastRun.message ?? "The last sync run failed.",
+		fix: "Open the run log to see how your app responded."
+	});
+	return issues;
+}
+function websocketLiveness(facts, presence, base) {
+	if (!(presence.connectionState === "connected" && presence.activeInstanceCount > 0)) {
+		const health = presence.connectionState === "reconnecting" ? "stale" : "offline";
+		return {
+			...base,
+			health,
+			issues: [],
+			reachable: false
+		};
+	}
+	const issues = livenessIssues(facts);
+	return {
+		...base,
+		health: issues.length > 0 ? "live_with_issues" : "live",
+		issues,
+		reachable: true
+	};
+}
+function deriveLiveness(facts) {
+	const ageMs = heartbeatAge(facts);
+	const environment = facts.environment ?? null;
+	const { liveMs, staleMs } = livenessWindows(facts.heartbeatIntervalMs);
+	const base = {
+		ageMs,
+		ageLabel: ageMs === null ? "No heartbeat yet" : formatAge(ageMs),
+		environment,
+		...facts.presence ? { presence: {
+			connectionState: facts.presence.connectionState,
+			transport: facts.presence.transport
+		} } : {}
+	};
+	if (facts.presence && facts.presence.transport === "websocket") return websocketLiveness(facts, facts.presence, base);
+	if (ageMs === null || ageMs >= staleMs) return {
+		...base,
+		health: "offline",
+		issues: [],
+		reachable: false
+	};
+	if (ageMs >= liveMs) return {
+		...base,
+		health: "stale",
+		issues: [],
+		reachable: false
+	};
+	const issues = livenessIssues(facts);
+	return {
+		...base,
+		health: issues.length > 0 ? "live_with_issues" : "live",
+		issues,
+		reachable: true
+	};
+}
 /** Is the raw condition behind each step met, ignoring prerequisites? */
 function isSatisfied(id, facts) {
 	const age = heartbeatAge(facts);
 	switch (id) {
 		case "credential": return facts.hasCredential;
-		case "application": return age !== null && age < HEARTBEAT_STALE_MS;
+		case "application": return facts.everConnected || age !== null;
 		case "schema": return facts.discoveredTableCount > 0;
 		case "mapping": return facts.mappedEntityCount > 0;
 		case "trigger": return facts.triggerConfigured;
@@ -69,19 +151,6 @@ function problemFor(id, facts) {
 		message: facts.lastRun.message ?? "The last sync run failed.",
 		fix: "Open the run log to see the host response."
 	};
-	if (id === "application") {
-		const age = heartbeatAge(facts);
-		if (age !== null && age >= HEARTBEAT_STALE_MS) return {
-			code: "heartbeat_stale",
-			message: `Your app stopped checking in ${formatAge(age)}.`,
-			fix: "Start your app, then run `npx clivly status`."
-		};
-		if (age === null && facts.everConnected) return {
-			code: "heartbeat_stale",
-			message: "Your application stopped checking in.",
-			fix: "Start your app, then run `npx clivly status`."
-		};
-	}
 	return null;
 }
 /**
@@ -147,14 +216,12 @@ const STEP_STATUS_WHEN_ACTIVE = {
 	widget: "healthy"
 };
 /**
-* Collapse the ladder to the single status the surfaces switch on. Live
-* conditions — a run in flight, a failure, a heartbeat gone quiet — win over
-* ladder position, because they describe the integration as it is now rather
-* than how far setup once got.
+* Collapse the ladder to the single status the surfaces switch on. This is the
+* setup dimension only: it answers how far configuration got, never whether the
+* app is up. Pair it with `deriveLiveness` for the second half of the picture.
 */
 function deriveStatus(steps, facts) {
 	if (facts.syncInFlight) return "syncing";
-	if (steps.find((step) => step.id === "application")?.problem?.code === "heartbeat_stale") return "disconnected";
 	if (steps.some((step) => step.state === "failed")) return "error";
 	const blocking = steps.find((step) => step.state === "active" || step.state === "blocked");
 	if (blocking) return STEP_STATUS_WHEN_ACTIVE[blocking.id];
@@ -209,13 +276,13 @@ const NEXT_BY_STEP = {
 * as the fix for a write problem (C-05). If you need a command for the
 * next-action slot, call this — do not write another one.
 */
-function nextAction(steps, status) {
+function nextAction(steps, status, liveness) {
 	if (status === "healthy" || status === "syncing") return null;
 	const blocking = steps.find((step) => step.state === "failed") ?? steps.find((step) => step.state === "active");
 	if (!blocking) return null;
-	if (blocking.problem?.code === "heartbeat_stale") return {
-		label: "Reconnect your app",
-		command: "npx clivly status",
+	if (steps.find((step) => step.id === "application")?.state === "done" && !liveness.reachable) return {
+		label: "Start your app",
+		command: null,
 		envFile: null
 	};
 	return NEXT_BY_STEP[blocking.id];
@@ -223,20 +290,25 @@ function nextAction(steps, status) {
 function computeIntegrationState(facts) {
 	const steps = resolveSteps(facts);
 	const status = deriveStatus(steps, facts);
+	const liveness = deriveLiveness(facts);
 	return {
 		status,
 		steps,
-		next: nextAction(steps, status)
+		liveness,
+		next: nextAction(steps, status, liveness)
 	};
 }
 //#endregion
+exports.DEFAULT_HEARTBEAT_INTERVAL_MS = DEFAULT_HEARTBEAT_INTERVAL_MS;
 exports.INSTALL_COMMAND = INSTALL_COMMAND;
 exports.INTEGRATION_STEPS = INTEGRATION_STEPS;
 exports.INTEGRATION_STEP_LABELS = INTEGRATION_STEP_LABELS;
 exports.STEP_PREREQUISITES = STEP_PREREQUISITES;
 exports.computeIntegrationState = computeIntegrationState;
+exports.deriveLiveness = deriveLiveness;
 exports.deriveStatus = deriveStatus;
 exports.formatAge = formatAge;
+exports.livenessWindows = livenessWindows;
 exports.nextAction = nextAction;
 exports.resolveSteps = resolveSteps;
 exports.stepIndex = stepIndex;

package/dist/integration-state.d.cts

@@ -3,7 +3,13 @@ declare const INTEGRATION_STEPS: readonly ["credential", "application", "schema"
 type StepId = (typeof INTEGRATION_STEPS)[number];
 /** `blocked` means "prerequisite unmet", never "broken" — see C-19. */
 type StepState = "done" | "active" | "blocked" | "failed" | "skipped";
-type IntegrationStatus = "not_configured" | "sdk_installed" | "awaiting_connection" | "connected" | "schema_discovered" | "mapping_required" | "trigger_required" | "ready_to_sync" | "syncing" | "healthy" | "warning" | "error" | "disconnected";
+type IntegrationStatus = "not_configured" | "sdk_installed" | "awaiting_connection" | "connected" | "schema_discovered" | "mapping_required" | "trigger_required" | "ready_to_sync" | "syncing" | "healthy" | "warning" | "error" |
+/**
+ * @deprecated No longer derived. Liveness is its own dimension — read
+ * `ConnectionHealth` from `deriveLiveness`. Setup progress does not move
+ * backwards just because an app stopped running.
+ */
+"disconnected";
 declare const INTEGRATION_STEP_LABELS: Record<StepId, string>;
 /** Each step's prerequisites. Ordering is enforced by a test, not convention. */
 declare const STEP_PREREQUISITES: Record<StepId, readonly StepId[]>;
@@ -13,8 +19,20 @@ interface RunFact {
   message?: string;
   ok: boolean;
 }
+/**
+ * Where the reporting app is running, as the app itself understands it.
+ *
+ * `unknown` is a real value, not an absence: `detectHostEnvironment` refuses to
+ * guess when nothing places the app, and a bare `node server.js` with no
+ * NODE_ENV must still be able to connect and be shown as itself. Defaulting
+ * such a host to `local_dev` would file a production box's faults under local
+ * development, where nobody would look for them.
+ */
+type HostEnvironment = "local_dev" | "preview" | "production" | "unknown";
 interface IntegrationFacts {
   discoveredTableCount: number;
+  /** The environment the app reported on its last heartbeat. */
+  environment?: HostEnvironment | null;
   /**
    * Has this app ever checked in? Distinguishes "never installed" from "was
    * working, now silent" — the same absent heartbeat means different things,
@@ -22,10 +40,27 @@ interface IntegrationFacts {
    */
   everConnected: boolean;
   hasCredential: boolean;
+  /**
+   * The cadence the app said it heartbeats at. Liveness windows are multiples
+   * of this rather than a fixed constant, so an app that deliberately reports
+   * slowly is not called dead for obeying its own configuration.
+   */
+  heartbeatIntervalMs?: number | null;
   lastHeartbeatAt: number | null;
   lastRun: RunFact | null;
   mappedEntityCount: number;
   now: number;
+  /**
+   * Deployment presence, when this deployment has one. Absent or `http`
+   * transport keeps the cadence-derived behaviour every SDK in the field uses.
+   */
+  presence?: DeploymentPresence | null;
+  /**
+   * Faults the running app diagnosed about itself on its last heartbeat — an
+   * unreadable database, a secret missing from the process environment. These
+   * are what make a reachable app `live_with_issues`; unfinished setup is not.
+   */
+  reportedIssues?: StepProblem[];
   syncInFlight: boolean;
   /** A trigger URL and secret both exist, so Clivly can ask the app to sync. */
   triggerConfigured: boolean;
@@ -46,6 +81,52 @@ interface IntegrationStep {
   state: StepState;
 }
 declare function formatAge(ms: number): string;
+/** The cadence `createClivlySDK` uses when the host app configures none. */
+declare const DEFAULT_HEARTBEAT_INTERVAL_MS = 60000;
+type ConnectionHealth = "live" | "live_with_issues" | "stale" | "offline";
+/** Which algorithm decides whether this deployment is up. */
+type PresenceTransport = "websocket" | "http";
+type PresenceConnectionState = "connected" | "reconnecting" | "disconnected";
+/**
+ * A deployment's connection state as its `PresenceRoom` last persisted it.
+ *
+ * This exists because a socket has an explicit state and a timestamp does not.
+ * Deriving WebSocket liveness from heartbeat age would leave a disconnected app
+ * shown as live for 150 seconds and offline only after ten minutes, which is
+ * the whole reason this transport exists.
+ */
+interface DeploymentPresence {
+  /** Sockets currently accepted in the room. */
+  activeInstanceCount: number;
+  connectionState: PresenceConnectionState;
+  transport: PresenceTransport;
+}
+interface ConnectionLiveness {
+  /** `"8s ago"`, or `"No heartbeat yet"` when the app has never reported. */
+  ageLabel: string;
+  ageMs: number | null;
+  environment: HostEnvironment | null;
+  health: ConnectionHealth;
+  /**
+   * Faults on a reachable app. Empty unless `health` is `live_with_issues`.
+   */
+  issues: StepProblem[];
+  /** Present when a deployment-presence record supplied this liveness result. */
+  presence?: Pick<DeploymentPresence, "connectionState" | "transport">;
+  /** Is a heartbeat recent enough to speak for the app as it is right now? */
+  reachable: boolean;
+}
+/**
+ * The two boundaries that separate live from stale from offline, in terms of
+ * the app's own reported cadence. A cadence we cannot believe — absent, zero,
+ * negative — falls back to the SDK default rather than producing a window of
+ * zero that would call every app offline.
+ */
+declare function livenessWindows(intervalMs: number | null | undefined): {
+  liveMs: number;
+  staleMs: number;
+};
+declare function deriveLiveness(facts: IntegrationFacts): ConnectionLiveness;
 /**
  * Walk the ladder once. A step is `blocked` when an earlier step it needs has
  * not been satisfied — a prerequisite statement, not a verdict about this step
@@ -54,10 +135,9 @@ declare function formatAge(ms: number): string;
  */
 declare function resolveSteps(facts: IntegrationFacts): IntegrationStep[];
 /**
- * Collapse the ladder to the single status the surfaces switch on. Live
- * conditions — a run in flight, a failure, a heartbeat gone quiet — win over
- * ladder position, because they describe the integration as it is now rather
- * than how far setup once got.
+ * Collapse the ladder to the single status the surfaces switch on. This is the
+ * setup dimension only: it answers how far configuration got, never whether the
+ * app is up. Pair it with `deriveLiveness` for the second half of the picture.
  */
 declare function deriveStatus(steps: IntegrationStep[], facts: IntegrationFacts): IntegrationStatus;
 interface NextAction {
@@ -66,6 +146,13 @@ interface NextAction {
   label: string;
 }
 interface IntegrationState {
+  /**
+   * Is the app running right now. Deliberately alongside `status` rather than
+   * folded into it: a surface must be able to say "setup reached mapping" and
+   * "the app is offline" in the same breath without either overwriting the
+   * other.
+   */
+  liveness: ConnectionLiveness;
   next: NextAction | null;
   status: IntegrationStatus;
   steps: IntegrationStep[];
@@ -82,7 +169,7 @@ declare const INSTALL_COMMAND = "npx clivly init";
  * as the fix for a write problem (C-05). If you need a command for the
  * next-action slot, call this — do not write another one.
  */
-declare function nextAction(steps: IntegrationStep[], status: IntegrationStatus): NextAction | null;
+declare function nextAction(steps: IntegrationStep[], status: IntegrationStatus, liveness: ConnectionLiveness): NextAction | null;
 declare function computeIntegrationState(facts: IntegrationFacts): IntegrationState;
 //#endregion
-export { INSTALL_COMMAND, INTEGRATION_STEPS, INTEGRATION_STEP_LABELS, IntegrationFacts, IntegrationState, IntegrationStatus, IntegrationStep, NextAction, RunFact, STEP_PREREQUISITES, StepId, StepProblem, StepState, computeIntegrationState, deriveStatus, formatAge, nextAction, resolveSteps, stepIndex };
+export { ConnectionHealth, ConnectionLiveness, DEFAULT_HEARTBEAT_INTERVAL_MS, DeploymentPresence, HostEnvironment, INSTALL_COMMAND, INTEGRATION_STEPS, INTEGRATION_STEP_LABELS, IntegrationFacts, IntegrationState, IntegrationStatus, IntegrationStep, NextAction, PresenceConnectionState, PresenceTransport, RunFact, STEP_PREREQUISITES, StepId, StepProblem, StepState, computeIntegrationState, deriveLiveness, deriveStatus, formatAge, livenessWindows, nextAction, resolveSteps, stepIndex };

package/dist/integration-state.d.mts

@@ -3,7 +3,13 @@ declare const INTEGRATION_STEPS: readonly ["credential", "application", "schema"
 type StepId = (typeof INTEGRATION_STEPS)[number];
 /** `blocked` means "prerequisite unmet", never "broken" — see C-19. */
 type StepState = "done" | "active" | "blocked" | "failed" | "skipped";
-type IntegrationStatus = "not_configured" | "sdk_installed" | "awaiting_connection" | "connected" | "schema_discovered" | "mapping_required" | "trigger_required" | "ready_to_sync" | "syncing" | "healthy" | "warning" | "error" | "disconnected";
+type IntegrationStatus = "not_configured" | "sdk_installed" | "awaiting_connection" | "connected" | "schema_discovered" | "mapping_required" | "trigger_required" | "ready_to_sync" | "syncing" | "healthy" | "warning" | "error" |
+/**
+ * @deprecated No longer derived. Liveness is its own dimension — read
+ * `ConnectionHealth` from `deriveLiveness`. Setup progress does not move
+ * backwards just because an app stopped running.
+ */
+"disconnected";
 declare const INTEGRATION_STEP_LABELS: Record<StepId, string>;
 /** Each step's prerequisites. Ordering is enforced by a test, not convention. */
 declare const STEP_PREREQUISITES: Record<StepId, readonly StepId[]>;
@@ -13,8 +19,20 @@ interface RunFact {
   message?: string;
   ok: boolean;
 }
+/**
+ * Where the reporting app is running, as the app itself understands it.
+ *
+ * `unknown` is a real value, not an absence: `detectHostEnvironment` refuses to
+ * guess when nothing places the app, and a bare `node server.js` with no
+ * NODE_ENV must still be able to connect and be shown as itself. Defaulting
+ * such a host to `local_dev` would file a production box's faults under local
+ * development, where nobody would look for them.
+ */
+type HostEnvironment = "local_dev" | "preview" | "production" | "unknown";
 interface IntegrationFacts {
   discoveredTableCount: number;
+  /** The environment the app reported on its last heartbeat. */
+  environment?: HostEnvironment | null;
   /**
    * Has this app ever checked in? Distinguishes "never installed" from "was
    * working, now silent" — the same absent heartbeat means different things,
@@ -22,10 +40,27 @@ interface IntegrationFacts {
    */
   everConnected: boolean;
   hasCredential: boolean;
+  /**
+   * The cadence the app said it heartbeats at. Liveness windows are multiples
+   * of this rather than a fixed constant, so an app that deliberately reports
+   * slowly is not called dead for obeying its own configuration.
+   */
+  heartbeatIntervalMs?: number | null;
   lastHeartbeatAt: number | null;
   lastRun: RunFact | null;
   mappedEntityCount: number;
   now: number;
+  /**
+   * Deployment presence, when this deployment has one. Absent or `http`
+   * transport keeps the cadence-derived behaviour every SDK in the field uses.
+   */
+  presence?: DeploymentPresence | null;
+  /**
+   * Faults the running app diagnosed about itself on its last heartbeat — an
+   * unreadable database, a secret missing from the process environment. These
+   * are what make a reachable app `live_with_issues`; unfinished setup is not.
+   */
+  reportedIssues?: StepProblem[];
   syncInFlight: boolean;
   /** A trigger URL and secret both exist, so Clivly can ask the app to sync. */
   triggerConfigured: boolean;
@@ -46,6 +81,52 @@ interface IntegrationStep {
   state: StepState;
 }
 declare function formatAge(ms: number): string;
+/** The cadence `createClivlySDK` uses when the host app configures none. */
+declare const DEFAULT_HEARTBEAT_INTERVAL_MS = 60000;
+type ConnectionHealth = "live" | "live_with_issues" | "stale" | "offline";
+/** Which algorithm decides whether this deployment is up. */
+type PresenceTransport = "websocket" | "http";
+type PresenceConnectionState = "connected" | "reconnecting" | "disconnected";
+/**
+ * A deployment's connection state as its `PresenceRoom` last persisted it.
+ *
+ * This exists because a socket has an explicit state and a timestamp does not.
+ * Deriving WebSocket liveness from heartbeat age would leave a disconnected app
+ * shown as live for 150 seconds and offline only after ten minutes, which is
+ * the whole reason this transport exists.
+ */
+interface DeploymentPresence {
+  /** Sockets currently accepted in the room. */
+  activeInstanceCount: number;
+  connectionState: PresenceConnectionState;
+  transport: PresenceTransport;
+}
+interface ConnectionLiveness {
+  /** `"8s ago"`, or `"No heartbeat yet"` when the app has never reported. */
+  ageLabel: string;
+  ageMs: number | null;
+  environment: HostEnvironment | null;
+  health: ConnectionHealth;
+  /**
+   * Faults on a reachable app. Empty unless `health` is `live_with_issues`.
+   */
+  issues: StepProblem[];
+  /** Present when a deployment-presence record supplied this liveness result. */
+  presence?: Pick<DeploymentPresence, "connectionState" | "transport">;
+  /** Is a heartbeat recent enough to speak for the app as it is right now? */
+  reachable: boolean;
+}
+/**
+ * The two boundaries that separate live from stale from offline, in terms of
+ * the app's own reported cadence. A cadence we cannot believe — absent, zero,
+ * negative — falls back to the SDK default rather than producing a window of
+ * zero that would call every app offline.
+ */
+declare function livenessWindows(intervalMs: number | null | undefined): {
+  liveMs: number;
+  staleMs: number;
+};
+declare function deriveLiveness(facts: IntegrationFacts): ConnectionLiveness;
 /**
  * Walk the ladder once. A step is `blocked` when an earlier step it needs has
  * not been satisfied — a prerequisite statement, not a verdict about this step
@@ -54,10 +135,9 @@ declare function formatAge(ms: number): string;
  */
 declare function resolveSteps(facts: IntegrationFacts): IntegrationStep[];
 /**
- * Collapse the ladder to the single status the surfaces switch on. Live
- * conditions — a run in flight, a failure, a heartbeat gone quiet — win over
- * ladder position, because they describe the integration as it is now rather
- * than how far setup once got.
+ * Collapse the ladder to the single status the surfaces switch on. This is the
+ * setup dimension only: it answers how far configuration got, never whether the
+ * app is up. Pair it with `deriveLiveness` for the second half of the picture.
  */
 declare function deriveStatus(steps: IntegrationStep[], facts: IntegrationFacts): IntegrationStatus;
 interface NextAction {
@@ -66,6 +146,13 @@ interface NextAction {
   label: string;
 }
 interface IntegrationState {
+  /**
+   * Is the app running right now. Deliberately alongside `status` rather than
+   * folded into it: a surface must be able to say "setup reached mapping" and
+   * "the app is offline" in the same breath without either overwriting the
+   * other.
+   */
+  liveness: ConnectionLiveness;
   next: NextAction | null;
   status: IntegrationStatus;
   steps: IntegrationStep[];
@@ -82,7 +169,7 @@ declare const INSTALL_COMMAND = "npx clivly init";
  * as the fix for a write problem (C-05). If you need a command for the
  * next-action slot, call this — do not write another one.
  */
-declare function nextAction(steps: IntegrationStep[], status: IntegrationStatus): NextAction | null;
+declare function nextAction(steps: IntegrationStep[], status: IntegrationStatus, liveness: ConnectionLiveness): NextAction | null;
 declare function computeIntegrationState(facts: IntegrationFacts): IntegrationState;
 //#endregion
-export { INSTALL_COMMAND, INTEGRATION_STEPS, INTEGRATION_STEP_LABELS, IntegrationFacts, IntegrationState, IntegrationStatus, IntegrationStep, NextAction, RunFact, STEP_PREREQUISITES, StepId, StepProblem, StepState, computeIntegrationState, deriveStatus, formatAge, nextAction, resolveSteps, stepIndex };
+export { ConnectionHealth, ConnectionLiveness, DEFAULT_HEARTBEAT_INTERVAL_MS, DeploymentPresence, HostEnvironment, INSTALL_COMMAND, INTEGRATION_STEPS, INTEGRATION_STEP_LABELS, IntegrationFacts, IntegrationState, IntegrationStatus, IntegrationStep, NextAction, PresenceConnectionState, PresenceTransport, RunFact, STEP_PREREQUISITES, StepId, StepProblem, StepState, computeIntegrationState, deriveLiveness, deriveStatus, formatAge, livenessWindows, nextAction, resolveSteps, stepIndex };

package/dist/integration-state.mjs

@@ -30,8 +30,6 @@ const STEP_PREREQUISITES = {
 function stepIndex(id) {
 	return INTEGRATION_STEPS.indexOf(id);
 }
-/** A heartbeat older than this means the app stopped checking in. */
-const HEARTBEAT_STALE_MS = 600 * 1e3;
 function formatAge(ms) {
 	if (ms < 6e4) return `${Math.max(1, Math.round(ms / 1e3))}s ago`;
 	if (ms < 36e5) return `${Math.round(ms / 6e4)}m ago`;
@@ -40,12 +38,96 @@ function formatAge(ms) {
 function heartbeatAge(facts) {
 	return facts.lastHeartbeatAt === null ? null : facts.now - facts.lastHeartbeatAt;
 }
+/** The cadence `createClivlySDK` uses when the host app configures none. */
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 6e4;
+const LIVE_INTERVALS = 2.5;
+const STALE_INTERVALS = 10;
+/**
+* The two boundaries that separate live from stale from offline, in terms of
+* the app's own reported cadence. A cadence we cannot believe — absent, zero,
+* negative — falls back to the SDK default rather than producing a window of
+* zero that would call every app offline.
+*/
+function livenessWindows(intervalMs) {
+	const interval = typeof intervalMs === "number" && intervalMs > 0 ? intervalMs : DEFAULT_HEARTBEAT_INTERVAL_MS;
+	return {
+		liveMs: interval * LIVE_INTERVALS,
+		staleMs: interval * STALE_INTERVALS
+	};
+}
+/**
+* Faults worth showing on an app that is up. Deliberately excludes anything the
+* developer simply has not done yet — no schema, no mapping, no trigger are all
+* setup stages, and painting a fresh install amber would make the signal
+* meaningless.
+*/
+function livenessIssues(facts) {
+	const issues = [...facts.reportedIssues ?? []];
+	if (facts.lastRun && !facts.lastRun.ok) issues.push({
+		code: "sync_failed",
+		message: facts.lastRun.message ?? "The last sync run failed.",
+		fix: "Open the run log to see how your app responded."
+	});
+	return issues;
+}
+function websocketLiveness(facts, presence, base) {
+	if (!(presence.connectionState === "connected" && presence.activeInstanceCount > 0)) {
+		const health = presence.connectionState === "reconnecting" ? "stale" : "offline";
+		return {
+			...base,
+			health,
+			issues: [],
+			reachable: false
+		};
+	}
+	const issues = livenessIssues(facts);
+	return {
+		...base,
+		health: issues.length > 0 ? "live_with_issues" : "live",
+		issues,
+		reachable: true
+	};
+}
+function deriveLiveness(facts) {
+	const ageMs = heartbeatAge(facts);
+	const environment = facts.environment ?? null;
+	const { liveMs, staleMs } = livenessWindows(facts.heartbeatIntervalMs);
+	const base = {
+		ageMs,
+		ageLabel: ageMs === null ? "No heartbeat yet" : formatAge(ageMs),
+		environment,
+		...facts.presence ? { presence: {
+			connectionState: facts.presence.connectionState,
+			transport: facts.presence.transport
+		} } : {}
+	};
+	if (facts.presence && facts.presence.transport === "websocket") return websocketLiveness(facts, facts.presence, base);
+	if (ageMs === null || ageMs >= staleMs) return {
+		...base,
+		health: "offline",
+		issues: [],
+		reachable: false
+	};
+	if (ageMs >= liveMs) return {
+		...base,
+		health: "stale",
+		issues: [],
+		reachable: false
+	};
+	const issues = livenessIssues(facts);
+	return {
+		...base,
+		health: issues.length > 0 ? "live_with_issues" : "live",
+		issues,
+		reachable: true
+	};
+}
 /** Is the raw condition behind each step met, ignoring prerequisites? */
 function isSatisfied(id, facts) {
 	const age = heartbeatAge(facts);
 	switch (id) {
 		case "credential": return facts.hasCredential;
-		case "application": return age !== null && age < HEARTBEAT_STALE_MS;
+		case "application": return facts.everConnected || age !== null;
 		case "schema": return facts.discoveredTableCount > 0;
 		case "mapping": return facts.mappedEntityCount > 0;
 		case "trigger": return facts.triggerConfigured;
@@ -68,19 +150,6 @@ function problemFor(id, facts) {
 		message: facts.lastRun.message ?? "The last sync run failed.",
 		fix: "Open the run log to see the host response."
 	};
-	if (id === "application") {
-		const age = heartbeatAge(facts);
-		if (age !== null && age >= HEARTBEAT_STALE_MS) return {
-			code: "heartbeat_stale",
-			message: `Your app stopped checking in ${formatAge(age)}.`,
-			fix: "Start your app, then run `npx clivly status`."
-		};
-		if (age === null && facts.everConnected) return {
-			code: "heartbeat_stale",
-			message: "Your application stopped checking in.",
-			fix: "Start your app, then run `npx clivly status`."
-		};
-	}
 	return null;
 }
 /**
@@ -146,14 +215,12 @@ const STEP_STATUS_WHEN_ACTIVE = {
 	widget: "healthy"
 };
 /**
-* Collapse the ladder to the single status the surfaces switch on. Live
-* conditions — a run in flight, a failure, a heartbeat gone quiet — win over
-* ladder position, because they describe the integration as it is now rather
-* than how far setup once got.
+* Collapse the ladder to the single status the surfaces switch on. This is the
+* setup dimension only: it answers how far configuration got, never whether the
+* app is up. Pair it with `deriveLiveness` for the second half of the picture.
 */
 function deriveStatus(steps, facts) {
 	if (facts.syncInFlight) return "syncing";
-	if (steps.find((step) => step.id === "application")?.problem?.code === "heartbeat_stale") return "disconnected";
 	if (steps.some((step) => step.state === "failed")) return "error";
 	const blocking = steps.find((step) => step.state === "active" || step.state === "blocked");
 	if (blocking) return STEP_STATUS_WHEN_ACTIVE[blocking.id];
@@ -208,13 +275,13 @@ const NEXT_BY_STEP = {
 * as the fix for a write problem (C-05). If you need a command for the
 * next-action slot, call this — do not write another one.
 */
-function nextAction(steps, status) {
+function nextAction(steps, status, liveness) {
 	if (status === "healthy" || status === "syncing") return null;
 	const blocking = steps.find((step) => step.state === "failed") ?? steps.find((step) => step.state === "active");
 	if (!blocking) return null;
-	if (blocking.problem?.code === "heartbeat_stale") return {
-		label: "Reconnect your app",
-		command: "npx clivly status",
+	if (steps.find((step) => step.id === "application")?.state === "done" && !liveness.reachable) return {
+		label: "Start your app",
+		command: null,
 		envFile: null
 	};
 	return NEXT_BY_STEP[blocking.id];
@@ -222,11 +289,13 @@ function nextAction(steps, status) {
 function computeIntegrationState(facts) {
 	const steps = resolveSteps(facts);
 	const status = deriveStatus(steps, facts);
+	const liveness = deriveLiveness(facts);
 	return {
 		status,
 		steps,
-		next: nextAction(steps, status)
+		liveness,
+		next: nextAction(steps, status, liveness)
 	};
 }
 //#endregion
-export { INSTALL_COMMAND, INTEGRATION_STEPS, INTEGRATION_STEP_LABELS, STEP_PREREQUISITES, computeIntegrationState, deriveStatus, formatAge, nextAction, resolveSteps, stepIndex };
+export { DEFAULT_HEARTBEAT_INTERVAL_MS, INSTALL_COMMAND, INTEGRATION_STEPS, INTEGRATION_STEP_LABELS, STEP_PREREQUISITES, computeIntegrationState, deriveLiveness, deriveStatus, formatAge, livenessWindows, nextAction, resolveSteps, stepIndex };