@objectstack/runtime 6.5.0 → 6.6.0

package/dist/index.d.cts

@@ -71,6 +71,20 @@ declare class Runtime {
     getKernel(): ObjectKernel;
 }
 
+/**
+ * Resolve the ObjectStack home directory used to store cwd-independent
+ * runtime data (default sqlite database, downloaded marketplace apps,
+ * installed plugin cache).
+ *
+ * Resolution order:
+ *   1. `OS_HOME` env var (absolute path; `~` expanded)
+ *   2. `~/.objectstack` (cross-platform user-home default)
+ *
+ * The directory is created lazily by callers that actually write to it
+ * (e.g. the sqlite driver's `mkdirSync(...)`); this helper does not
+ * touch the filesystem.
+ */
+declare function resolveObjectStackHome(): string;
 declare const StandaloneStackConfigSchema: z.ZodObject<{
     databaseUrl: z.ZodOptional<z.ZodString>;
     databaseAuthToken: z.ZodOptional<z.ZodString>;
@@ -820,6 +834,30 @@ interface KernelManagerConfig {
         warn?: (...a: any[]) => void;
         error?: (...a: any[]) => void;
     };
+    /**
+     * Optional upstream-change detector. When set, every cache hit older
+     * than `staleCheckIntervalMs` triggers this probe before returning the
+     * cached kernel. Returning `true` evicts the kernel and forces a
+     * rebuild, so changes to the control-plane state that don't reach
+     * this process via push (marketplace installs, artifact republish,
+     * etc.) become visible without waiting for the LRU TTL to expire.
+     *
+     * The probe should be cheap (single small GET). Errors thrown here
+     * are caught and treated as "still fresh" so a brief upstream
+     * outage doesn't churn every cached kernel — the worst case is
+     * stale-by-`ttlMs`, which is what we had before adding the probe.
+     *
+     * `builtAtMs` is the kernel's `createdAt` time so the probe can
+     * compare against an upstream "last changed at" timestamp.
+     */
+    freshnessProbe?: (environmentId: string, builtAtMs: number) => Promise<boolean>;
+    /**
+     * Minimum gap between successive freshness probes for the same env.
+     * Defaults to 10 seconds — enough to avoid hammering the control
+     * plane on tight render loops while still keeping the user's
+     * post-install refresh perceived as immediate.
+     */
+    staleCheckIntervalMs?: number;
 }
 /**
  * LRU + TTL cache of per-project {@link ObjectKernel} instances.
@@ -837,6 +875,8 @@ declare class KernelManager {
     private readonly logger;
     private readonly cache;
     private readonly pending;
+    private readonly freshnessProbe?;
+    private readonly staleCheckIntervalMs;
     constructor(config: KernelManagerConfig);
     /** Returns the currently cached environmentIds (ordered by insertion). */
     keys(): string[];
@@ -1716,6 +1756,24 @@ declare class ArtifactApiClient {
         commitId: string;
         publishedAt?: string | null;
     } | null>;
+    /**
+     * Cheap freshness probe — returns the env's `last_published_at`
+     * (and best-effort current commit) without rebuilding the artifact.
+     * Used by `KernelManager` on cache hits to detect when a per-env
+     * kernel has been invalidated by an upstream change (marketplace
+     * install/uninstall, artifact publish) so it can be rebuilt
+     * without waiting for the 15-minute LRU TTL to expire.
+     *
+     * Returns `null` on definitive 404 / unknown env. Errors propagate
+     * (caller decides whether to treat unreachable cloud as fresh or
+     * stale — typically fresh, so a brief outage doesn't churn every
+     * cached kernel).
+     */
+    getFreshness(environmentId: string): Promise<{
+        environmentId: string;
+        lastPublishedAt: string | null;
+        commitId: string | null;
+    } | null>;
     /** Drop cached entries for a project (and any matching hostname). */
     invalidate(environmentId: string): void;
     /** Drop everything. Used on shutdown / hot-reload. */
@@ -2521,4 +2579,4 @@ declare function actionBodyRunnerFactory(runner: ScriptRunner, opts: FactoryOpti
     timeoutMs?: number;
 }) => ((actionCtx: any) => Promise<unknown>) | undefined;
 
-export { AppPlugin, ArtifactApiClient, type ArtifactApiClientConfig, ArtifactEnvironmentRegistry, type ArtifactEnvironmentRegistryConfig, ArtifactKernelFactory, type ArtifactKernelFactoryConfig, AuthProxyPlugin, type BackfillPlatformSsoClientsOptions, DEFAULT_CLOUD_URL, DEFAULT_RATE_LIMITS, type DefaultHostConfigOptions, type DefaultHostConfigResult, type DispatcherPluginConfig, DriverPlugin, type EnvironmentArtifactResponse, type EnvironmentDriverRegistry, type EnvironmentKernelFactory, type EnvironmentRuntimeConfig, FileArtifactApiClient, type FileArtifactApiClientConfig, HttpDispatcher, type HttpDispatcherResult, type HttpProtocolContext, HttpServer, KernelManager, type KernelManagerConfig, type LoadArtifactBundleOptions, MarketplaceInstallLocalPlugin, type MarketplaceInstallLocalPluginConfig, MarketplaceProxyPlugin, type MarketplaceProxyPluginConfig, MiddlewareManager, type ObjectOSStackConfig, type ObjectOSStackResult, ObservabilityServicePlugin, type ObservabilityServicePluginOptions, PLATFORM_SSO_PROVIDER_ID, QuickJSScriptRunner, type QuickJSScriptRunnerOptions, type RateLimitBucketConfig, type RateLimitDecision, type RateLimitDefaults, type RateLimitStore, RateLimiter, type ResolvedHostname, Runtime, type RuntimeConfig, RuntimeConfigPlugin, type RuntimeConfigPluginConfig, SYSTEM_ENVIRONMENT_ID, SandboxError, type ScriptContext, type ScriptOrigin, type ScriptResult, type ScriptRunOptions, type ScriptRunner, type SecurityHeadersOptions, SeedLoaderService, type SeedPlatformSsoClientOptions, type StandaloneStackConfig, type StandaloneStackResult, type SystemEnvironmentPluginConfig, type TraceContext, UnimplementedScriptRunner, actionBodyRunnerFactory, backfillPlatformSsoClients, buildPlatformSsoRedirectUri, buildSecurityHeaders, collectBundleActions, collectBundleFunctions, collectBundleHooks, createDefaultHostConfig, createDispatcherPlugin, createObjectOSStack, createStandaloneStack, createSystemEnvironmentPlugin, derivePlatformSsoClientId, derivePlatformSsoClientSecret, extractRequestId, formatTraceparent, generateRequestId, hookBodyRunnerFactory, isHttpUrl, loadArtifactBundle, mergeRuntimeModule, parseTraceparent, readArtifactSource, resolveCloudUrl, resolveDefaultArtifactPath, resolveErrorReporter, resolveMetrics, resolveRequestId, seedPlatformSsoClient };
+export { AppPlugin, ArtifactApiClient, type ArtifactApiClientConfig, ArtifactEnvironmentRegistry, type ArtifactEnvironmentRegistryConfig, ArtifactKernelFactory, type ArtifactKernelFactoryConfig, AuthProxyPlugin, type BackfillPlatformSsoClientsOptions, DEFAULT_CLOUD_URL, DEFAULT_RATE_LIMITS, type DefaultHostConfigOptions, type DefaultHostConfigResult, type DispatcherPluginConfig, DriverPlugin, type EnvironmentArtifactResponse, type EnvironmentDriverRegistry, type EnvironmentKernelFactory, type EnvironmentRuntimeConfig, FileArtifactApiClient, type FileArtifactApiClientConfig, HttpDispatcher, type HttpDispatcherResult, type HttpProtocolContext, HttpServer, KernelManager, type KernelManagerConfig, type LoadArtifactBundleOptions, MarketplaceInstallLocalPlugin, type MarketplaceInstallLocalPluginConfig, MarketplaceProxyPlugin, type MarketplaceProxyPluginConfig, MiddlewareManager, type ObjectOSStackConfig, type ObjectOSStackResult, ObservabilityServicePlugin, type ObservabilityServicePluginOptions, PLATFORM_SSO_PROVIDER_ID, QuickJSScriptRunner, type QuickJSScriptRunnerOptions, type RateLimitBucketConfig, type RateLimitDecision, type RateLimitDefaults, type RateLimitStore, RateLimiter, type ResolvedHostname, Runtime, type RuntimeConfig, RuntimeConfigPlugin, type RuntimeConfigPluginConfig, SYSTEM_ENVIRONMENT_ID, SandboxError, type ScriptContext, type ScriptOrigin, type ScriptResult, type ScriptRunOptions, type ScriptRunner, type SecurityHeadersOptions, SeedLoaderService, type SeedPlatformSsoClientOptions, type StandaloneStackConfig, type StandaloneStackResult, type SystemEnvironmentPluginConfig, type TraceContext, UnimplementedScriptRunner, actionBodyRunnerFactory, backfillPlatformSsoClients, buildPlatformSsoRedirectUri, buildSecurityHeaders, collectBundleActions, collectBundleFunctions, collectBundleHooks, createDefaultHostConfig, createDispatcherPlugin, createObjectOSStack, createStandaloneStack, createSystemEnvironmentPlugin, derivePlatformSsoClientId, derivePlatformSsoClientSecret, extractRequestId, formatTraceparent, generateRequestId, hookBodyRunnerFactory, isHttpUrl, loadArtifactBundle, mergeRuntimeModule, parseTraceparent, readArtifactSource, resolveCloudUrl, resolveDefaultArtifactPath, resolveErrorReporter, resolveMetrics, resolveObjectStackHome, resolveRequestId, seedPlatformSsoClient };

package/dist/index.d.ts

@@ -71,6 +71,20 @@ declare class Runtime {
     getKernel(): ObjectKernel;
 }
 
+/**
+ * Resolve the ObjectStack home directory used to store cwd-independent
+ * runtime data (default sqlite database, downloaded marketplace apps,
+ * installed plugin cache).
+ *
+ * Resolution order:
+ *   1. `OS_HOME` env var (absolute path; `~` expanded)
+ *   2. `~/.objectstack` (cross-platform user-home default)
+ *
+ * The directory is created lazily by callers that actually write to it
+ * (e.g. the sqlite driver's `mkdirSync(...)`); this helper does not
+ * touch the filesystem.
+ */
+declare function resolveObjectStackHome(): string;
 declare const StandaloneStackConfigSchema: z.ZodObject<{
     databaseUrl: z.ZodOptional<z.ZodString>;
     databaseAuthToken: z.ZodOptional<z.ZodString>;
@@ -820,6 +834,30 @@ interface KernelManagerConfig {
         warn?: (...a: any[]) => void;
         error?: (...a: any[]) => void;
     };
+    /**
+     * Optional upstream-change detector. When set, every cache hit older
+     * than `staleCheckIntervalMs` triggers this probe before returning the
+     * cached kernel. Returning `true` evicts the kernel and forces a
+     * rebuild, so changes to the control-plane state that don't reach
+     * this process via push (marketplace installs, artifact republish,
+     * etc.) become visible without waiting for the LRU TTL to expire.
+     *
+     * The probe should be cheap (single small GET). Errors thrown here
+     * are caught and treated as "still fresh" so a brief upstream
+     * outage doesn't churn every cached kernel — the worst case is
+     * stale-by-`ttlMs`, which is what we had before adding the probe.
+     *
+     * `builtAtMs` is the kernel's `createdAt` time so the probe can
+     * compare against an upstream "last changed at" timestamp.
+     */
+    freshnessProbe?: (environmentId: string, builtAtMs: number) => Promise<boolean>;
+    /**
+     * Minimum gap between successive freshness probes for the same env.
+     * Defaults to 10 seconds — enough to avoid hammering the control
+     * plane on tight render loops while still keeping the user's
+     * post-install refresh perceived as immediate.
+     */
+    staleCheckIntervalMs?: number;
 }
 /**
  * LRU + TTL cache of per-project {@link ObjectKernel} instances.
@@ -837,6 +875,8 @@ declare class KernelManager {
     private readonly logger;
     private readonly cache;
     private readonly pending;
+    private readonly freshnessProbe?;
+    private readonly staleCheckIntervalMs;
     constructor(config: KernelManagerConfig);
     /** Returns the currently cached environmentIds (ordered by insertion). */
     keys(): string[];
@@ -1716,6 +1756,24 @@ declare class ArtifactApiClient {
         commitId: string;
         publishedAt?: string | null;
     } | null>;
+    /**
+     * Cheap freshness probe — returns the env's `last_published_at`
+     * (and best-effort current commit) without rebuilding the artifact.
+     * Used by `KernelManager` on cache hits to detect when a per-env
+     * kernel has been invalidated by an upstream change (marketplace
+     * install/uninstall, artifact publish) so it can be rebuilt
+     * without waiting for the 15-minute LRU TTL to expire.
+     *
+     * Returns `null` on definitive 404 / unknown env. Errors propagate
+     * (caller decides whether to treat unreachable cloud as fresh or
+     * stale — typically fresh, so a brief outage doesn't churn every
+     * cached kernel).
+     */
+    getFreshness(environmentId: string): Promise<{
+        environmentId: string;
+        lastPublishedAt: string | null;
+        commitId: string | null;
+    } | null>;
     /** Drop cached entries for a project (and any matching hostname). */
     invalidate(environmentId: string): void;
     /** Drop everything. Used on shutdown / hot-reload. */
@@ -2521,4 +2579,4 @@ declare function actionBodyRunnerFactory(runner: ScriptRunner, opts: FactoryOpti
     timeoutMs?: number;
 }) => ((actionCtx: any) => Promise<unknown>) | undefined;
 
-export { AppPlugin, ArtifactApiClient, type ArtifactApiClientConfig, ArtifactEnvironmentRegistry, type ArtifactEnvironmentRegistryConfig, ArtifactKernelFactory, type ArtifactKernelFactoryConfig, AuthProxyPlugin, type BackfillPlatformSsoClientsOptions, DEFAULT_CLOUD_URL, DEFAULT_RATE_LIMITS, type DefaultHostConfigOptions, type DefaultHostConfigResult, type DispatcherPluginConfig, DriverPlugin, type EnvironmentArtifactResponse, type EnvironmentDriverRegistry, type EnvironmentKernelFactory, type EnvironmentRuntimeConfig, FileArtifactApiClient, type FileArtifactApiClientConfig, HttpDispatcher, type HttpDispatcherResult, type HttpProtocolContext, HttpServer, KernelManager, type KernelManagerConfig, type LoadArtifactBundleOptions, MarketplaceInstallLocalPlugin, type MarketplaceInstallLocalPluginConfig, MarketplaceProxyPlugin, type MarketplaceProxyPluginConfig, MiddlewareManager, type ObjectOSStackConfig, type ObjectOSStackResult, ObservabilityServicePlugin, type ObservabilityServicePluginOptions, PLATFORM_SSO_PROVIDER_ID, QuickJSScriptRunner, type QuickJSScriptRunnerOptions, type RateLimitBucketConfig, type RateLimitDecision, type RateLimitDefaults, type RateLimitStore, RateLimiter, type ResolvedHostname, Runtime, type RuntimeConfig, RuntimeConfigPlugin, type RuntimeConfigPluginConfig, SYSTEM_ENVIRONMENT_ID, SandboxError, type ScriptContext, type ScriptOrigin, type ScriptResult, type ScriptRunOptions, type ScriptRunner, type SecurityHeadersOptions, SeedLoaderService, type SeedPlatformSsoClientOptions, type StandaloneStackConfig, type StandaloneStackResult, type SystemEnvironmentPluginConfig, type TraceContext, UnimplementedScriptRunner, actionBodyRunnerFactory, backfillPlatformSsoClients, buildPlatformSsoRedirectUri, buildSecurityHeaders, collectBundleActions, collectBundleFunctions, collectBundleHooks, createDefaultHostConfig, createDispatcherPlugin, createObjectOSStack, createStandaloneStack, createSystemEnvironmentPlugin, derivePlatformSsoClientId, derivePlatformSsoClientSecret, extractRequestId, formatTraceparent, generateRequestId, hookBodyRunnerFactory, isHttpUrl, loadArtifactBundle, mergeRuntimeModule, parseTraceparent, readArtifactSource, resolveCloudUrl, resolveDefaultArtifactPath, resolveErrorReporter, resolveMetrics, resolveRequestId, seedPlatformSsoClient };
+export { AppPlugin, ArtifactApiClient, type ArtifactApiClientConfig, ArtifactEnvironmentRegistry, type ArtifactEnvironmentRegistryConfig, ArtifactKernelFactory, type ArtifactKernelFactoryConfig, AuthProxyPlugin, type BackfillPlatformSsoClientsOptions, DEFAULT_CLOUD_URL, DEFAULT_RATE_LIMITS, type DefaultHostConfigOptions, type DefaultHostConfigResult, type DispatcherPluginConfig, DriverPlugin, type EnvironmentArtifactResponse, type EnvironmentDriverRegistry, type EnvironmentKernelFactory, type EnvironmentRuntimeConfig, FileArtifactApiClient, type FileArtifactApiClientConfig, HttpDispatcher, type HttpDispatcherResult, type HttpProtocolContext, HttpServer, KernelManager, type KernelManagerConfig, type LoadArtifactBundleOptions, MarketplaceInstallLocalPlugin, type MarketplaceInstallLocalPluginConfig, MarketplaceProxyPlugin, type MarketplaceProxyPluginConfig, MiddlewareManager, type ObjectOSStackConfig, type ObjectOSStackResult, ObservabilityServicePlugin, type ObservabilityServicePluginOptions, PLATFORM_SSO_PROVIDER_ID, QuickJSScriptRunner, type QuickJSScriptRunnerOptions, type RateLimitBucketConfig, type RateLimitDecision, type RateLimitDefaults, type RateLimitStore, RateLimiter, type ResolvedHostname, Runtime, type RuntimeConfig, RuntimeConfigPlugin, type RuntimeConfigPluginConfig, SYSTEM_ENVIRONMENT_ID, SandboxError, type ScriptContext, type ScriptOrigin, type ScriptResult, type ScriptRunOptions, type ScriptRunner, type SecurityHeadersOptions, SeedLoaderService, type SeedPlatformSsoClientOptions, type StandaloneStackConfig, type StandaloneStackResult, type SystemEnvironmentPluginConfig, type TraceContext, UnimplementedScriptRunner, actionBodyRunnerFactory, backfillPlatformSsoClients, buildPlatformSsoRedirectUri, buildSecurityHeaders, collectBundleActions, collectBundleFunctions, collectBundleHooks, createDefaultHostConfig, createDispatcherPlugin, createObjectOSStack, createStandaloneStack, createSystemEnvironmentPlugin, derivePlatformSsoClientId, derivePlatformSsoClientSecret, extractRequestId, formatTraceparent, generateRequestId, hookBodyRunnerFactory, isHttpUrl, loadArtifactBundle, mergeRuntimeModule, parseTraceparent, readArtifactSource, resolveCloudUrl, resolveDefaultArtifactPath, resolveErrorReporter, resolveMetrics, resolveObjectStackHome, resolveRequestId, seedPlatformSsoClient };

package/dist/index.js

@@ -2107,7 +2107,16 @@ var Runtime = class {
 init_load_artifact_bundle();
 import { resolve as resolvePath2 } from "path";
 import { mkdirSync } from "fs";
+import { homedir } from "os";
 import { z } from "zod";
+function resolveObjectStackHome() {
+  const raw = process.env.OS_HOME?.trim();
+  if (raw && raw.length > 0) {
+    if (raw.startsWith("~")) return resolvePath2(homedir(), raw.slice(1).replace(/^[/\\]/, ""));
+    return resolvePath2(raw);
+  }
+  return resolvePath2(homedir(), ".objectstack");
+}
 var StandaloneStackConfigSchema = z.object({
   databaseUrl: z.string().optional(),
   databaseAuthToken: z.string().optional(),
@@ -2138,7 +2147,7 @@ async function createStandaloneStack(config) {
   const environmentId = cfg.environmentId ?? process.env.OS_ENVIRONMENT_ID ?? "proj_local";
   const artifactPathInput = cfg.artifactPath ?? process.env.OS_ARTIFACT_PATH ?? resolvePath2(cwd, "dist/objectstack.json");
   const artifactPath = isHttpUrl(artifactPathInput) ? artifactPathInput : artifactPathInput.startsWith("/") ? artifactPathInput : resolvePath2(cwd, artifactPathInput);
-  const dbUrl = cfg.databaseUrl ?? process.env.OS_DATABASE_URL?.trim() ?? process.env.TURSO_DATABASE_URL?.trim() ?? `file:${resolvePath2(cwd, ".objectstack/data/standalone.db")}`;
+  const dbUrl = cfg.databaseUrl ?? process.env.OS_DATABASE_URL?.trim() ?? process.env.TURSO_DATABASE_URL?.trim() ?? `file:${resolvePath2(resolveObjectStackHome(), "data/standalone.db")}`;
   const dbAuthToken = cfg.databaseAuthToken ?? process.env.OS_DATABASE_AUTH_TOKEN?.trim() ?? process.env.TURSO_AUTH_TOKEN?.trim();
   const explicitDriver = cfg.databaseDriver ?? process.env.OS_DATABASE_DRIVER?.trim();
   const dbDriver = explicitDriver ?? detectDriverFromUrl(dbUrl);
@@ -2248,7 +2257,7 @@ async function createStandaloneStack(config) {
 
 // src/default-host.ts
 import { resolve as resolvePath3 } from "path";
-import { existsSync } from "fs";
+import { existsSync, mkdirSync as mkdirSync2, writeFileSync } from "fs";
 init_load_artifact_bundle();
 function resolveDefaultArtifactPath(explicitPath, cwd = process.cwd()) {
   const candidate = explicitPath ?? process.env.OS_ARTIFACT_PATH ?? resolvePath3(cwd, "dist/objectstack.json");
@@ -2258,12 +2267,42 @@ function resolveDefaultArtifactPath(explicitPath, cwd = process.cwd()) {
 }
 async function createDefaultHostConfig(options = {}) {
   const { requireArtifact = true, ...standaloneOpts } = options;
-  const resolvedArtifact = resolveDefaultArtifactPath(standaloneOpts.artifactPath);
+  let resolvedArtifact = resolveDefaultArtifactPath(standaloneOpts.artifactPath);
   if (!resolvedArtifact && requireArtifact) {
     throw new Error(
       "[createDefaultHostConfig] No artifact source available. Set OS_ARTIFACT_PATH (file path or http(s):// URL), place the artifact at <cwd>/dist/objectstack.json, or pass `{ artifactPath: ... }` explicitly. To boot an empty kernel anyway, pass `{ requireArtifact: false }`."
     );
   }
+  if (!resolvedArtifact && !requireArtifact) {
+    const home = resolveObjectStackHome();
+    const stubPath = resolvePath3(home, "dist/objectstack.json");
+    if (!existsSync(stubPath)) {
+      mkdirSync2(resolvePath3(stubPath, ".."), { recursive: true });
+      writeFileSync(
+        stubPath,
+        JSON.stringify(
+          {
+            manifest: {
+              id: "com.objectstack.empty",
+              name: "empty",
+              version: "0.0.0",
+              type: "app",
+              description: "Empty starter kernel \u2014 install apps via the Studio marketplace."
+            },
+            objects: [],
+            views: [],
+            apps: [],
+            flows: [],
+            requires: []
+          },
+          null,
+          2
+        ),
+        "utf8"
+      );
+    }
+    resolvedArtifact = stubPath;
+  }
   return createStandaloneStack({
     ...standaloneOpts,
     artifactPath: resolvedArtifact
@@ -6821,6 +6860,8 @@ var KernelManager = class {
     this.maxSize = config.maxSize ?? 32;
     this.ttlMs = config.ttlMs ?? 15 * 60 * 1e3;
     this.logger = config.logger ?? console;
+    this.freshnessProbe = config.freshnessProbe;
+    this.staleCheckIntervalMs = config.staleCheckIntervalMs ?? 1e4;
   }
   /** Returns the currently cached environmentIds (ordered by insertion). */
   keys() {
@@ -6843,8 +6884,31 @@ var KernelManager = class {
       if (this.ttlMs > 0 && Date.now() - existing.lastAccess > this.ttlMs) {
         await this.evict(environmentId);
       } else {
-        existing.lastAccess = Date.now();
-        return existing.kernel;
+        if (this.freshnessProbe) {
+          const now = Date.now();
+          if (now - existing.lastStaleCheckAt >= this.staleCheckIntervalMs) {
+            existing.lastStaleCheckAt = now;
+            let stale = false;
+            try {
+              stale = await this.freshnessProbe(environmentId, existing.createdAt);
+            } catch (err) {
+              this.logger.warn?.("[KernelManager] freshness probe failed", { environmentId, err });
+            }
+            if (stale) {
+              this.logger.info?.("[KernelManager] kernel evicted by freshness probe", { environmentId });
+              await this.evict(environmentId);
+            } else {
+              existing.lastAccess = Date.now();
+              return existing.kernel;
+            }
+          } else {
+            existing.lastAccess = Date.now();
+            return existing.kernel;
+          }
+        } else {
+          existing.lastAccess = Date.now();
+          return existing.kernel;
+        }
       }
     }
     const inflight = this.pending.get(environmentId);
@@ -6852,7 +6916,7 @@ var KernelManager = class {
     const promise = (async () => {
       const kernel = await this.factory.create(environmentId);
       const now = Date.now();
-      this.cache.set(environmentId, { kernel, createdAt: now, lastAccess: now });
+      this.cache.set(environmentId, { kernel, createdAt: now, lastAccess: now, lastStaleCheckAt: now });
       await this.enforceMaxSize();
       return kernel;
     })();
@@ -7020,6 +7084,30 @@ var ArtifactApiClient = class {
     if (!found?.headCommitId) return null;
     return { commitId: String(found.headCommitId), publishedAt: found.headPublishedAt ?? null };
   }
+  /**
+   * Cheap freshness probe — returns the env's `last_published_at`
+   * (and best-effort current commit) without rebuilding the artifact.
+   * Used by `KernelManager` on cache hits to detect when a per-env
+   * kernel has been invalidated by an upstream change (marketplace
+   * install/uninstall, artifact publish) so it can be rebuilt
+   * without waiting for the 15-minute LRU TTL to expire.
+   *
+   * Returns `null` on definitive 404 / unknown env. Errors propagate
+   * (caller decides whether to treat unreachable cloud as fresh or
+   * stale — typically fresh, so a brief outage doesn't churn every
+   * cached kernel).
+   */
+  async getFreshness(environmentId) {
+    const url = `${this.base}/api/v1/cloud/environments/${encodeURIComponent(environmentId)}/freshness`;
+    const res = await this.request(url);
+    if (res === null) return null;
+    const body = res.success === false ? null : res.data ?? res;
+    if (!body || typeof body !== "object") return null;
+    const envId = typeof body.environmentId === "string" ? body.environmentId : environmentId;
+    const lastPublishedAt = typeof body.lastPublishedAt === "string" ? body.lastPublishedAt : null;
+    const commitId = typeof body.commitId === "string" ? body.commitId : null;
+    return { environmentId: envId, lastPublishedAt, commitId };
+  }
   /** Drop cached entries for a project (and any matching hostname). */
   invalidate(environmentId) {
     this.artifactCache.delete(environmentId);
@@ -7771,7 +7859,30 @@ var ArtifactKernelFactory = class {
 };
 
 // src/cloud/auth-proxy-plugin.ts
+import { createHmac as createHmac3, randomUUID as randomUUID2 } from "crypto";
 var AUTH_PREFIX = "/api/v1/auth";
+function signSessionCookieValue(rawToken, secret) {
+  const signature = createHmac3("sha256", secret).update(rawToken).digest("base64");
+  return encodeURIComponent(`${rawToken}.${signature}`);
+}
+function buildSetCookieHeader(name, encodedValue, attrs, maxAgeSec) {
+  const parts = [`${name}=${encodedValue}`];
+  const a = attrs ?? {};
+  if (a.path) parts.push(`Path=${a.path}`);
+  else parts.push("Path=/");
+  if (Number.isFinite(maxAgeSec) && maxAgeSec > 0) parts.push(`Max-Age=${Math.floor(maxAgeSec)}`);
+  if (a.domain) parts.push(`Domain=${a.domain}`);
+  if (a.sameSite) {
+    const ss = String(a.sameSite);
+    parts.push(`SameSite=${ss.charAt(0).toUpperCase() + ss.slice(1)}`);
+  } else {
+    parts.push("SameSite=Lax");
+  }
+  if (a.secure) parts.push("Secure");
+  if (a.httpOnly !== false) parts.push("HttpOnly");
+  if (a.partitioned) parts.push("Partitioned");
+  return parts.join("; ");
+}
 function pickHandler(svc) {
   if (!svc) return void 0;
   if (typeof svc.handleRequest === "function") return svc.handleRequest.bind(svc);
@@ -7865,6 +7976,115 @@ var AuthProxyPlugin = class {
                 return c.json({ hasOwner: true });
               }
             }
+            if (c.req.method === "POST" && subPath === "sso-handoff-issue") {
+              try {
+                const expected = (process.env.OS_CLOUD_API_KEY ?? "").trim();
+                if (!expected) {
+                  return c.json({ error: "sso_handoff_disabled", reason: "OS_CLOUD_API_KEY unset on env runtime" }, 503);
+                }
+                const authz = c.req.header("authorization") ?? "";
+                const provided = authz.toLowerCase().startsWith("bearer ") ? authz.slice(7).trim() : "";
+                if (!provided || provided !== expected) {
+                  return c.json({ error: "unauthorized" }, 401);
+                }
+                if (typeof authSvc?.getAuthContext !== "function") {
+                  return c.json({ error: "auth_service_unavailable" }, 503);
+                }
+                const handoffAuthCtx = await authSvc.getAuthContext();
+                const internal = handoffAuthCtx?.internalAdapter;
+                if (!internal?.createVerificationValue) {
+                  return c.json({ error: "verification_api_unavailable" }, 503);
+                }
+                let body = {};
+                try {
+                  body = await c.req.json();
+                } catch {
+                  body = {};
+                }
+                const email = String(body?.email ?? "").toLowerCase().trim();
+                if (!email) return c.json({ error: "email_required" }, 400);
+                const name = body?.name == null ? null : String(body.name);
+                const by = body?.by == null ? "service" : String(body.by);
+                const envIdInBody = body?.envId == null ? null : String(body.envId);
+                const handoff = randomUUID2().replace(/-/g, "") + randomUUID2().replace(/-/g, "");
+                const ttlSec = 60;
+                const expiresAt = new Date(Date.now() + ttlSec * 1e3);
+                await internal.createVerificationValue({
+                  identifier: `sso-handoff:${handoff}`,
+                  value: JSON.stringify({ email, name, by, envId: envIdInBody ?? environmentId }),
+                  expiresAt
+                });
+                return c.json({
+                  token: handoff,
+                  expiresAt: expiresAt.toISOString(),
+                  ttlSec
+                });
+              } catch (err) {
+                ctx.logger?.error?.("[AuthProxyPlugin] sso-handoff-issue failed", err instanceof Error ? err : new Error(String(err)));
+                return c.json({ error: "sso_handoff_issue_failed", message: String(err?.message ?? err) }, 500);
+              }
+            }
+            if (c.req.method === "GET" && subPath === "sso-exchange") {
+              try {
+                const token = (url.searchParams.get("token") ?? "").trim();
+                const nextRaw = url.searchParams.get("next") ?? "/";
+                const next = nextRaw.startsWith("/") ? nextRaw : "/";
+                if (!token) return c.text("missing token", 400);
+                if (typeof authSvc?.getAuthContext !== "function") {
+                  return c.text("auth service unavailable", 503);
+                }
+                const authCtx = await authSvc.getAuthContext();
+                const internal = authCtx?.internalAdapter;
+                if (!internal?.consumeVerificationValue) {
+                  return c.text("verification API unavailable", 503);
+                }
+                const consumed = await internal.consumeVerificationValue(`sso-handoff:${token}`);
+                if (!consumed) return c.text("invalid or expired token", 401);
+                const expiresAt = consumed?.expiresAt ? new Date(consumed.expiresAt).getTime() : 0;
+                if (!expiresAt || expiresAt < Date.now()) return c.text("expired token", 401);
+                let payload = {};
+                try {
+                  payload = JSON.parse(String(consumed.value));
+                } catch {
+                  payload = { email: String(consumed.value) };
+                }
+                const email = String(payload.email ?? "").toLowerCase().trim();
+                if (!email) return c.text("handoff missing email", 400);
+                const found = await internal.findUserByEmail(email, { includeAccounts: true });
+                let userId = found?.user?.id;
+                let hasCredentialAccount = (found?.accounts ?? []).some((a) => a.providerId === "credential" && a.password);
+                if (!userId) {
+                  const created = await internal.createUser({
+                    email,
+                    name: payload.name ?? email,
+                    emailVerified: true
+                  });
+                  userId = created?.id;
+                  hasCredentialAccount = false;
+                }
+                if (!userId) return c.text("failed to provision user", 500);
+                const session = await internal.createSession(userId, false);
+                const rawToken = session?.token;
+                const sessionExpiresAt = session?.expiresAt ? new Date(session.expiresAt) : new Date(Date.now() + 7 * 24 * 3600 * 1e3);
+                if (!rawToken) return c.text("failed to mint session", 500);
+                const secret = authCtx?.secret ?? "";
+                if (!secret) return c.text("auth secret unavailable", 503);
+                const cookieName = authCtx?.authCookies?.sessionToken?.name ?? "better-auth.session_token";
+                const cookieAttrs = authCtx?.authCookies?.sessionToken?.attributes ?? {};
+                const encoded = signSessionCookieValue(rawToken, secret);
+                const maxAgeSec = Math.max(60, Math.floor((sessionExpiresAt.getTime() - Date.now()) / 1e3));
+                const setCookie = buildSetCookieHeader(cookieName, encoded, cookieAttrs, maxAgeSec);
+                const finalNext = hasCredentialAccount ? next : `/_console/system/profile?recovery_needed=true&next=${encodeURIComponent(next)}`;
+                const headers = new Headers();
+                headers.set("Set-Cookie", setCookie);
+                headers.set("Location", finalNext);
+                headers.set("Cache-Control", "no-store");
+                return new Response(null, { status: 302, headers });
+              } catch (err) {
+                ctx.logger?.error?.("[AuthProxyPlugin] sso-exchange failed", err instanceof Error ? err : new Error(String(err)));
+                return c.text(`sso-exchange failed: ${err?.message ?? String(err)}`, 500);
+              }
+            }
             const fn = await resolveAuthHandler(authSvc);
             if (!fn) {
               return c.json({ error: "auth_service_unavailable", environmentId }, 503);
@@ -8047,20 +8267,46 @@ var RuntimeConfigPlugin = class {
           return;
         }
         const rawApp = httpServer.getRawApp();
-        const payload = {
-          cloudUrl: this.cloudUrl,
-          singleEnvironment: this.singleEnvironment,
-          features: {
-            installLocal: this.installLocal,
-            marketplace: true
+        const features = {
+          installLocal: this.installLocal,
+          marketplace: true
+        };
+        let envRegistry = null;
+        try {
+          envRegistry = ctx.getService("env-registry");
+        } catch {
+        }
+        const handler = async (c) => {
+          const rawHost = c.req.header("host") ?? "";
+          const host = rawHost.split(":")[0].toLowerCase().trim();
+          let defaultEnvironmentId;
+          let defaultOrgId;
+          let resolvedSingleEnv = this.singleEnvironment;
+          if (envRegistry && host && typeof envRegistry.resolveHostname === "function") {
+            try {
+              const resolved = await envRegistry.resolveHostname(host);
+              if (resolved?.environmentId) {
+                defaultEnvironmentId = resolved.environmentId;
+                if (resolved.organizationId) defaultOrgId = String(resolved.organizationId);
+                resolvedSingleEnv = true;
+              }
+            } catch {
+            }
           }
+          return c.json({
+            cloudUrl: this.cloudUrl,
+            singleEnvironment: resolvedSingleEnv,
+            defaultOrgId,
+            defaultEnvironmentId,
+            features
+          });
         };
-        const handler = (c) => c.json(payload);
         rawApp.get("/api/v1/runtime/config", handler);
         rawApp.get("/api/v1/studio/runtime-config", handler);
         ctx.logger?.info?.("[RuntimeConfigPlugin] mounted /api/v1/runtime/config", {
           cloudUrl: this.cloudUrl || "(empty)",
-          installLocal: this.installLocal
+          installLocal: this.installLocal,
+          perHostEnvResolution: !!envRegistry
         });
       });
     };
@@ -8261,7 +8507,21 @@ var ObjectOSEnvironmentPlugin = class {
         factory,
         maxSize: this.config.kernelCacheSize,
         ttlMs: this.config.kernelTtlMs,
-        logger: ctx.logger
+        logger: ctx.logger,
+        // Only the HTTP client exposes /freshness; file-mode (CLI dev)
+        // has no upstream to probe.
+        freshnessProbe: this.config.controlPlaneUrl === "file" ? void 0 : async (envId, builtAtMs) => {
+          const fresh = await client.getFreshness(envId);
+          if (!fresh) return false;
+          const t = fresh.lastPublishedAt ? Date.parse(fresh.lastPublishedAt) : NaN;
+          if (!Number.isFinite(t)) return false;
+          if (t <= builtAtMs) return false;
+          try {
+            client.invalidate(envId);
+          } catch {
+          }
+          return true;
+        }
       });
       this.kernelManager = kernelManager;
       ctx.registerService("env-registry", envRegistry);
@@ -8313,7 +8573,7 @@ async function createObjectOSStack(config) {
 }
 
 // src/cloud/marketplace-install-local-plugin.ts
-import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync, readdirSync, unlinkSync, writeFileSync } from "fs";
+import { existsSync as existsSync2, mkdirSync as mkdirSync3, readFileSync, readdirSync, unlinkSync, writeFileSync as writeFileSync2 } from "fs";
 import { join, resolve } from "path";
 var ROUTE_BASE = "/api/v1/marketplace/install-local";
 var DEFAULT_DIR = ".objectstack/installed-packages";
@@ -8446,8 +8706,8 @@ var MarketplaceInstallLocalPlugin = class {
         installedBy: userId
       };
       try {
-        mkdirSync2(this.storageDir, { recursive: true });
-        writeFileSync(join(this.storageDir, safeFilename(manifestId)), JSON.stringify(entry, null, 2), "utf8");
+        mkdirSync3(this.storageDir, { recursive: true });
+        writeFileSync2(join(this.storageDir, safeFilename(manifestId)), JSON.stringify(entry, null, 2), "utf8");
       } catch (err) {
         return c.json({
           success: false,
@@ -8866,6 +9126,7 @@ export {
   resolveDefaultArtifactPath,
   resolveErrorReporter,
   resolveMetrics,
+  resolveObjectStackHome,
   resolveRequestId,
   seedPlatformSsoClient
 };