@treeseed/sdk 0.12.11 → 0.12.13

package/dist/guarantees/index.d.ts

@@ -259,6 +259,7 @@ export type TreeseedGuaranteeSceneExecutionInput = {
     };
     scenePath: string;
     record?: boolean;
+    artifactMode?: 'full' | 'screenshots';
     device?: string;
 };
 export type TreeseedGuaranteeSceneExecutor = (input: TreeseedGuaranteeSceneExecutionInput) => Promise<TreeseedGuaranteeVerifierExecutionResult>;
@@ -397,6 +398,7 @@ export declare function runTreeseedGuarantees(input: {
     includePlanned?: boolean;
     failOnSkippedReleaseGuarantees?: boolean;
     record?: boolean;
+    sceneArtifacts?: 'full' | 'screenshots';
     device?: string;
     evidenceTarget?: 'local' | 'ci' | 'release';
     sceneExecutor?: TreeseedGuaranteeSceneExecutor;

package/dist/guarantees/index.js

@@ -791,6 +791,7 @@ async function defaultTreeseedGuaranteeSceneExecutor(input) {
         scene: input.scenePath,
         environment: input.environment,
         record: input.record,
+        artifactMode: input.artifactMode,
         mode: "acceptance",
         devices
       });
@@ -807,6 +808,7 @@ async function defaultTreeseedGuaranteeSceneExecutor(input) {
       environment: input.environment,
       device: input.device ?? devices[0],
       record: input.record,
+      artifactMode: input.artifactMode,
       mode: "acceptance"
     });
     return {
@@ -913,6 +915,7 @@ async function runGuaranteeSteps(input) {
       guarantee: input.guarantee,
       scenePath,
       record: input.record ?? false,
+      artifactMode: input.sceneArtifacts,
       device: input.device
     }));
   }
@@ -1052,6 +1055,7 @@ async function runTreeseedGuarantees(input) {
         verifierExecutor: input.verifierExecutor ?? defaultTreeseedGuaranteeVerifierExecutor,
         verifierCache,
         record: input.record,
+        sceneArtifacts: input.sceneArtifacts,
         device: input.device
       }));
     }

package/dist/hosting/builtins.js

@@ -36,28 +36,42 @@ function defaultPlan(input) {
 function defaultVerify(input) {
   const hostCapabilities = new Set(input.unit.host.capabilities.filter((capability) => capability.environments.includes(input.environment)).map((capability) => capability.id));
   const missing = input.unit.requiredCapabilities.filter((capability) => !hostCapabilities.has(capability));
+  const checks = [
+    {
+      key: "host-capabilities",
+      label: "Host supports required capabilities",
+      ok: missing.length === 0,
+      expected: input.unit.requiredCapabilities,
+      observed: [...hostCapabilities],
+      issues: missing.map((capability) => `Missing host capability: ${capability}`)
+    },
+    {
+      key: "secrets-redacted",
+      label: "Secrets are represented by references only",
+      ok: !JSON.stringify(input.unit.config).match(/(token|secret|password|key)\s*[:=]\s*[^",}]+/iu),
+      expected: "secretRefs",
+      observed: input.unit.secretRefs,
+      issues: []
+    }
+  ];
+  if (input.unit.host.id === "railway" && input.environment === "prod" && unitConfig(input).sourceMode === "image") {
+    const imageRef = unitConfig(input).imageRef;
+    const hasImageRef = typeof imageRef === "string" && imageRef.trim().length > 0;
+    checks.push({
+      key: "railway-image-ref",
+      label: "Production Railway service uses an immutable image reference",
+      ok: hasImageRef,
+      expected: unitConfig(input).imageRefEnv ? `${unitConfig(input).imageRefEnv}=<image>:<tag>` : "<image>:<tag>",
+      observed: imageRef ?? null,
+      issues: hasImageRef ? [] : [`Production Railway service ${unitConfig(input).serviceName ?? input.unit.id} is image-backed but no image reference was resolved.`]
+    });
+  }
+  const verified = checks.every((check) => check.ok);
   return {
     unitId: input.unit.id,
-    status: missing.length === 0 ? input.observed.status : "blocked",
-    verified: missing.length === 0,
-    checks: [
-      {
-        key: "host-capabilities",
-        label: "Host supports required capabilities",
-        ok: missing.length === 0,
-        expected: input.unit.requiredCapabilities,
-        observed: [...hostCapabilities],
-        issues: missing.map((capability) => `Missing host capability: ${capability}`)
-      },
-      {
-        key: "secrets-redacted",
-        label: "Secrets are represented by references only",
-        ok: !JSON.stringify(input.unit.config).match(/(token|secret|password|key)\s*[:=]\s*[^",}]+/iu),
-        expected: "secretRefs",
-        observed: input.unit.secretRefs,
-        issues: []
-      }
-    ],
+    status: verified ? input.observed.status : "blocked",
+    verified,
+    checks,
     warnings: []
   };
 }

package/dist/hosting/contracts.d.ts

@@ -89,6 +89,7 @@ export interface TreeseedApplicationHostingProfile {
 export interface TreeseedHostingGraphInput {
     tenantRoot: string;
     environment: TreeseedHostingEnvironment;
+    env?: Record<string, string | undefined>;
     configRoot?: string;
     appId?: string;
     deployConfig?: TreeseedDeployConfig;

package/dist/hosting/graph.js

@@ -302,6 +302,7 @@ function buildProfileFromDeployConfig(input) {
   } catch {
     railwayImageRefEnv = {};
   }
+  const launchEnv = mergeRecord(process.env, railwayImageRefEnv, input.env);
   if (config.surfaces?.web && config.surfaces.web.enabled !== false) {
     services.push({
       id: "web",
@@ -334,7 +335,7 @@ function buildProfileFromDeployConfig(input) {
     const configuredRailwayProjectName = typeof service.railway?.projectName === "string" && service.railway.projectName.trim() ? service.railway.projectName.trim() : null;
     const defaultProjectGroup = service.provider === "railway" || service.railway ? String(serviceKey).startsWith("capacityProvider") && configuredRailwayProjectName ? capacityProviderProjectGroupId(configuredRailwayProjectName) : "treeseed-control-plane" : void 0;
     const imageRefEnv = railwayImageRefEnvForService(serviceKey);
-    const imageRef = service.railway?.imageRef ?? (imageRefEnv ? railwayImageRefEnv[imageRefEnv] ?? process.env[imageRefEnv] : null) ?? defaultRailwayImageRefForService(serviceKey, input.environment) ?? null;
+    const imageRef = service.railway?.imageRef ?? (imageRefEnv ? launchEnv[imageRefEnv] ?? null : null) ?? defaultRailwayImageRefForService(serviceKey, input.environment) ?? null;
     const sourcePolicy = railwaySourcePolicy(input, serviceKey, service, imageRef);
     services.push({
       id: serviceKey,

package/dist/operations/providers/default.js

@@ -1191,6 +1191,7 @@ class DefaultTreeseedOperationsProvider {
       new DoctorOperation("doctor"),
       new InstallOperation("install"),
       new ToolsOperation("tools"),
+      new WorkflowOperation("cleanup"),
       new AuthLoginOperation("auth:login"),
       new AuthLogoutOperation("auth:logout"),
       new AuthWhoAmIOperation("auth:whoami"),

package/dist/operations/services/live-hosted-service-checks.js

@@ -125,6 +125,73 @@ function selectedServiceKeySet(options) {
 function serviceIsSelected(selected, serviceKey) {
   return selected.size === 0 || selected.has(serviceKey);
 }
+function treeseedDatabaseDescriptors(tenantRoot, options) {
+  const descriptors = [];
+  const rootConfig = loadTreeseedPlatformConfig({ tenantRoot, environment: options.target, env: process.env }).deployConfig;
+  const candidates = [
+    { applicationId: "web", applicationRoot: tenantRoot, config: rootConfig },
+    ...discoverTreeseedApplications(tenantRoot).map((application) => ({
+      applicationId: application.id,
+      applicationRoot: application.root,
+      config: application.config
+    }))
+  ];
+  for (const candidate of candidates) {
+    if (options.appId && options.appId !== candidate.applicationId) continue;
+    const service = candidate.config.services?.treeseedDatabase;
+    if (!service || service.enabled === false || service.provider !== "railway" || service.railway?.resourceType !== "postgres") {
+      continue;
+    }
+    const serviceName = typeof service.railway?.serviceName === "string" && service.railway.serviceName.trim() ? service.railway.serviceName.trim() : `${candidate.config.slug ?? "treeseed-api"}-postgres`;
+    descriptors.push({
+      applicationId: candidate.applicationId,
+      applicationRoot: candidate.applicationRoot,
+      serviceName
+    });
+  }
+  return descriptors;
+}
+async function verifyRailwayPostgresTopology(input) {
+  const ownerService = input.configuredServices.find(
+    (service) => ["api", "operationsRunner"].includes(service.key) && (!input.descriptor.applicationId || service.application?.id === input.descriptor.applicationId)
+  );
+  if (!ownerService) {
+    input.issues.push(`${input.descriptor.serviceName}: no Railway API or operations runner service is configured to own the database.`);
+    return;
+  }
+  const project = ownerService.projectId ? findByName(input.projects, ownerService.projectId) : findByName(input.projects, ownerService.projectName);
+  if (!project?.id) {
+    input.issues.push(`${input.descriptor.serviceName}: Railway project ${ownerService.projectName} was not found.`);
+    return;
+  }
+  const environments = await listRailwayEnvironments({ projectId: project.id, env: input.options.env, fetchImpl: input.options.fetchImpl });
+  const environment = findByName(environments, ownerService.railwayEnvironment);
+  if (!environment?.id) {
+    input.issues.push(`${input.descriptor.serviceName}: Railway environment ${ownerService.railwayEnvironment} was not found.`);
+    return;
+  }
+  const [services, volumes] = await Promise.all([
+    listRailwayServices({ projectId: project.id, env: input.options.env, fetchImpl: input.options.fetchImpl }),
+    listRailwayVolumes({ projectId: project.id, env: input.options.env, fetchImpl: input.options.fetchImpl }).catch(() => [])
+  ]);
+  const postgresService = findByName(services, input.descriptor.serviceName);
+  if (!postgresService?.id) {
+    input.issues.push(`${input.descriptor.serviceName}: canonical Railway PostgreSQL service was not found.`);
+  }
+  const volumeName = `${input.descriptor.serviceName}-volume`;
+  const canonicalVolume = volumes.find((volume) => volume.name === volumeName) ?? null;
+  if (!canonicalVolume) {
+    input.issues.push(`${volumeName}: canonical Railway PostgreSQL volume was not found.`);
+    return;
+  }
+  const activeInstances = activeRailwayVolumeInstances(canonicalVolume);
+  const attachedToPostgres = postgresService?.id ? activeInstances.some(
+    (instance) => instance.serviceId === postgresService.id && instance.environmentId === environment.id && instance.mountPath === "/var/lib/postgresql/data"
+  ) : false;
+  if (!attachedToPostgres) {
+    input.issues.push(`${volumeName}: canonical Railway PostgreSQL volume is not attached to ${input.descriptor.serviceName} at /var/lib/postgresql/data (states=${railwayVolumeInstanceStates(canonicalVolume)}).`);
+  }
+}
 function resolveLiveProviderEnv(options) {
   let launchValues = {};
   try {
@@ -152,7 +219,15 @@ async function collectRailwayObservations(options) {
     const workspace = await resolveRailwayWorkspaceContext({ env: options.env, fetchImpl: options.fetchImpl });
     const projects = await listRailwayProjects({ workspaceId: workspace.id, env: options.env, fetchImpl: options.fetchImpl });
     const configuredServices = configuredRailwayServices(options.tenantRoot, options.target).filter((entry) => !options.appId || entry.application?.id === options.appId).filter((entry) => serviceIsSelected(selectedServiceKeys, entry.key));
+    if (selectedServiceKeys.size === 0 || selectedServiceKeys.has("api") || selectedServiceKeys.has("operationsRunner")) {
+      for (const descriptor of treeseedDatabaseDescriptors(options.tenantRoot, options)) {
+        await verifyRailwayPostgresTopology({ descriptor, configuredServices, projects, options, issues });
+      }
+    }
     for (const service of configuredServices) {
+      if (options.target === "prod" && service.sourceMode === "image" && !service.imageRef) {
+        issues.push(`${service.serviceName}: production Railway service is configured for image deployment but no immutable image ref is resolved.`);
+      }
       const project = service.projectId ? findByName(projects, service.projectId) : findByName(projects, service.projectName);
       if (!project?.id) {
         issues.push(`${service.serviceName}: Railway project ${service.projectName} was not found.`);
@@ -172,6 +247,9 @@ async function collectRailwayObservations(options) {
           if (isRetainedDetachedRailwayVolume(volume.name)) {
             continue;
           }
+          if (String(volume.name ?? "").endsWith("-postgres-volume") && activeRailwayVolumeInstances(volume).length === 0) {
+            issues.push(`${volume.name ?? volume.id}: detached PostgreSQL volume remains in Railway project ${project.name} (states=${railwayVolumeInstanceStates(volume)}).`);
+          }
           const detachedPostgresInstances = activeRailwayVolumeInstances(volume).filter(
             (instance2) => instance2.environmentId === environment.id && instance2.mountPath === "/var/lib/postgresql/data" && !instance2.serviceId
           );

package/dist/operations/services/local-cleanup.d.ts

@@ -0,0 +1,29 @@
+export type TreeseedLocalCleanupMode = 'standard' | 'aggressive';
+export type TreeseedLocalCleanupAction = {
+    id: string;
+    kind: 'directory' | 'docker' | 'npm-cache';
+    path?: string;
+    command?: string[];
+    status: 'removed' | 'skipped' | 'failed';
+    beforeBytes?: number;
+    afterBytes?: number;
+    exitCode?: number | null;
+    error?: string;
+};
+export type TreeseedLocalCleanupReport = {
+    ok: boolean;
+    mode: TreeseedLocalCleanupMode;
+    root: string;
+    startedAt: string;
+    completedAt: string;
+    beforeBytes: number;
+    afterBytes: number;
+    reclaimedBytes: number;
+    actions: TreeseedLocalCleanupAction[];
+};
+export declare function runTreeseedLocalCleanup(input: {
+    root: string;
+    mode?: TreeseedLocalCleanupMode;
+    docker?: boolean;
+    npmCache?: boolean;
+}): TreeseedLocalCleanupReport;

package/dist/operations/services/local-cleanup.js

@@ -0,0 +1,62 @@
+import { existsSync, readdirSync, rmSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+function directoryBytes(path) {
+  if (!existsSync(path)) return 0;
+  const stat = statSync(path, { throwIfNoEntry: false });
+  if (!stat) return 0;
+  if (!stat.isDirectory()) return stat.size;
+  let total = stat.size;
+  for (const entry of readdirSync(path)) total += directoryBytes(join(path, entry));
+  return total;
+}
+function removeDirectory(root, relativePath) {
+  const path = join(root, relativePath);
+  const beforeBytes = directoryBytes(path);
+  if (!existsSync(path)) return { id: relativePath, kind: "directory", path, status: "skipped", beforeBytes: 0, afterBytes: 0 };
+  try {
+    rmSync(path, { recursive: true, force: true });
+    return { id: relativePath, kind: "directory", path, status: "removed", beforeBytes, afterBytes: directoryBytes(path) };
+  } catch (error) {
+    return { id: relativePath, kind: "directory", path, status: "failed", beforeBytes, afterBytes: directoryBytes(path), error: error instanceof Error ? error.message : String(error) };
+  }
+}
+function runCleanupCommand(id, kind, command, cwd) {
+  const result = spawnSync(command[0], command.slice(1), { cwd, encoding: "utf8", maxBuffer: 1024 * 1024 * 16 });
+  const exitCode = result.status ?? null;
+  return {
+    id,
+    kind,
+    command,
+    status: exitCode === 0 ? "removed" : "failed",
+    exitCode,
+    ...exitCode === 0 ? {} : { error: (result.stderr || result.stdout || result.error?.message || "cleanup command failed").trim() }
+  };
+}
+function runTreeseedLocalCleanup(input) {
+  const root = resolve(input.root);
+  const mode = input.mode ?? "standard";
+  const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const beforeBytes = directoryBytes(join(root, ".treeseed"));
+  const actions = [];
+  const directoryTargets = mode === "aggressive" ? [
+    ".treeseed/tmp",
+    ".treeseed/cache",
+    ".treeseed/scenes/runs",
+    ".treeseed/scenes/matrix",
+    ".treeseed/scenes/render",
+    ".treeseed/guarantees/runs",
+    ".treeseed/guarantees/release",
+    ".treeseed/generated/release-evidence",
+    ".treeseed/release/evidence"
+  ] : [".treeseed/tmp", ".treeseed/cache", ".treeseed/scenes/render"];
+  for (const target of directoryTargets) actions.push(removeDirectory(root, target));
+  if (input.docker !== false && mode === "aggressive") actions.push(runCleanupCommand("docker-system-prune", "docker", ["docker", "system", "prune", "--all", "--volumes", "--force"], root));
+  if (input.npmCache !== false) actions.push(runCleanupCommand("npm-cache-clean", "npm-cache", ["npm", "cache", "clean", "--force"], root));
+  const afterBytes = directoryBytes(join(root, ".treeseed"));
+  const completedAt = (/* @__PURE__ */ new Date()).toISOString();
+  return { ok: actions.every((entry) => entry.status !== "failed"), mode, root, startedAt, completedAt, beforeBytes, afterBytes, reclaimedBytes: Math.max(0, beforeBytes - afterBytes), actions };
+}
+export {
+  runTreeseedLocalCleanup
+};

package/dist/operations/services/operations-runner-smoke.js

@@ -115,7 +115,8 @@ async function runTreeseedOperationsRunnerSmoke(options) {
   const serviceSecret = options.serviceSecret ?? localServiceSecret ?? value("TREESEED_ACCEPTANCE_SERVICE_SECRET", values, env) ?? value("TREESEED_WEB_SERVICE_SECRET", values, env) ?? value("TREESEED_API_WEB_SERVICE_SECRET", values, env);
   const timings = [];
   const fetchImpl = options.fetchImpl ?? fetch;
-  const timeoutMs = Math.max(1e3, Math.floor(options.timeoutMs ?? (options.environment === "prod" ? 12e4 : 9e4)));
+  const defaultTimeoutMs = options.environment === "local" ? 9e4 : 6e5;
+  const timeoutMs = Math.max(1e3, Math.floor(options.timeoutMs ?? defaultTimeoutMs));
   const pollMs = Math.max(1e3, Math.floor(options.pollMs ?? 3e3));
   if (!serviceSecret) {
     return failure(baseUrl, options.environment, ["Missing API service credential for runner smoke."], timings);

package/dist/operations/services/railway-api.d.ts

@@ -287,7 +287,7 @@ export declare function getRailwayServiceInstance({ serviceId, environmentId, en
     sleepApplication: null;
     runtimeConfigSupported: false;
 }>;
-export declare function ensureRailwayServiceInstanceConfiguration({ serviceId, environmentId, buildCommand, dockerfilePath, railwayConfigFile, startCommand, cronSchedule, rootDirectory, healthcheckPath, healthcheckTimeoutSeconds, healthcheckIntervalSeconds, restartPolicy, runtimeMode, deploymentRegion, env, fetchImpl, settleAttempts, settleDelayMs, }: {
+export declare function ensureRailwayServiceInstanceConfiguration({ serviceId, environmentId, buildCommand, dockerfilePath, railwayConfigFile, startCommand, cronSchedule, rootDirectory, healthcheckPath, healthcheckTimeoutSeconds, healthcheckIntervalSeconds, restartPolicy, runtimeMode, deploymentRegion, clearSourceConfiguration, env, fetchImpl, settleAttempts, settleDelayMs, }: {
     serviceId: string;
     environmentId: string;
     buildCommand?: string | null;
@@ -302,6 +302,7 @@ export declare function ensureRailwayServiceInstanceConfiguration({ serviceId, e
     restartPolicy?: string | null;
     runtimeMode?: string | null;
     deploymentRegion?: string | null;
+    clearSourceConfiguration?: boolean;
     env?: NodeJS.ProcessEnv | Record<string, string | undefined>;
     fetchImpl?: typeof fetch;
     settleAttempts?: number;
@@ -343,6 +344,8 @@ export declare function ensureRailwayServiceInstanceConfiguration({ serviceId, e
     instance: {
         id: string;
         buildCommand: string | null;
+        dockerfilePath: string | null;
+        railwayConfigFile: string | null;
         startCommand: string | null;
         cronSchedule: string | null;
         rootDirectory: string | null;

package/dist/operations/services/railway-api.js

@@ -1476,6 +1476,7 @@ async function ensureRailwayServiceInstanceConfiguration({
   restartPolicy,
   runtimeMode,
   deploymentRegion,
+  clearSourceConfiguration = false,
   env = process.env,
   fetchImpl = fetch,
   settleAttempts = 60,
@@ -1518,7 +1519,7 @@ async function ensureRailwayServiceInstanceConfiguration({
   if (desired.restartPolicy !== null) {
     throw new Error("Railway service instance restart policies are unsupported by the current Railway API schema.");
   }
-  const drifted = desired.buildCommand !== null && desired.buildCommand !== current.buildCommand || desired.dockerfilePath !== null && desired.dockerfilePath !== current.dockerfilePath || desired.railwayConfigFile !== null && desired.railwayConfigFile !== current.railwayConfigFile || desired.startCommand !== null && desired.startCommand !== current.startCommand || desired.cronSchedule !== null && desired.cronSchedule !== current.cronSchedule || desired.rootDirectory !== null && desired.rootDirectory !== current.rootDirectory || desired.healthcheckPath !== null && desired.healthcheckPath !== current.healthcheckPath || desired.healthcheckTimeoutSeconds !== null && desired.healthcheckTimeoutSeconds !== current.healthcheckTimeoutSeconds || desired.runtimeMode !== null && desired.runtimeMode !== current.runtimeMode || desired.deploymentRegion !== null;
+  const drifted = (desired.buildCommand !== null || clearSourceConfiguration) && desired.buildCommand !== current.buildCommand || (desired.dockerfilePath !== null || clearSourceConfiguration) && desired.dockerfilePath !== current.dockerfilePath || (desired.railwayConfigFile !== null || clearSourceConfiguration) && desired.railwayConfigFile !== current.railwayConfigFile || (desired.startCommand !== null || clearSourceConfiguration) && desired.startCommand !== current.startCommand || desired.cronSchedule !== null && desired.cronSchedule !== current.cronSchedule || (desired.rootDirectory !== null || clearSourceConfiguration) && desired.rootDirectory !== current.rootDirectory || desired.healthcheckPath !== null && desired.healthcheckPath !== current.healthcheckPath || desired.healthcheckTimeoutSeconds !== null && desired.healthcheckTimeoutSeconds !== current.healthcheckTimeoutSeconds || desired.runtimeMode !== null && desired.runtimeMode !== current.runtimeMode || desired.deploymentRegion !== null;
   if (!drifted) {
     return { instance: current, updated: false };
   }
@@ -1538,12 +1539,12 @@ mutation TreeseedRailwayServiceInstanceUpdateLegacy($serviceId: String!, $enviro
         serviceId,
         environmentId,
         input: {
-          ...desired.buildCommand !== null ? { buildCommand: desired.buildCommand } : {},
-          ...desired.dockerfilePath !== null ? { dockerfilePath: desired.dockerfilePath } : {},
-          ...desired.railwayConfigFile !== null ? { railwayConfigFile: desired.railwayConfigFile } : {},
-          ...desired.startCommand !== null ? { startCommand: desired.startCommand } : {},
+          ...desired.buildCommand !== null || clearSourceConfiguration && current.buildCommand !== null ? { buildCommand: desired.buildCommand } : {},
+          ...desired.dockerfilePath !== null || clearSourceConfiguration && current.dockerfilePath !== null ? { dockerfilePath: desired.dockerfilePath } : {},
+          ...desired.railwayConfigFile !== null || clearSourceConfiguration && current.railwayConfigFile !== null ? { railwayConfigFile: desired.railwayConfigFile } : {},
+          ...desired.startCommand !== null || clearSourceConfiguration && current.startCommand !== null ? { startCommand: desired.startCommand } : {},
           ...desired.cronSchedule !== null ? { cronSchedule: desired.cronSchedule } : {},
-          ...desired.rootDirectory !== null ? { rootDirectory: desired.rootDirectory } : {},
+          ...desired.rootDirectory !== null || clearSourceConfiguration && current.rootDirectory !== null ? { rootDirectory: desired.rootDirectory } : {},
           ...desired.healthcheckPath !== null ? { healthcheckPath: desired.healthcheckPath } : {},
           ...desired.healthcheckTimeoutSeconds !== null ? { healthcheckTimeout: desired.healthcheckTimeoutSeconds } : {},
           ...desired.sleepApplication !== null ? { sleepApplication: desired.sleepApplication } : {},
@@ -1572,7 +1573,7 @@ mutation TreeseedRailwayServiceInstanceUpdateLegacy($serviceId: String!, $enviro
       env,
       fetchImpl
     });
-    if (!serviceInstanceDrifted(instance, desired) || attempt >= settleAttempts) {
+    if (!serviceInstanceDrifted(instance, desired, clearSourceConfiguration) || attempt >= settleAttempts) {
       break;
     }
     await new Promise((resolve) => setTimeout(resolve, settleDelayMs));
@@ -1581,6 +1582,8 @@ mutation TreeseedRailwayServiceInstanceUpdateLegacy($serviceId: String!, $enviro
     instance: {
       id: instance.id || current.id,
       buildCommand: instance.buildCommand,
+      dockerfilePath: instance.dockerfilePath,
+      railwayConfigFile: instance.railwayConfigFile,
       startCommand: instance.startCommand,
       cronSchedule: instance.cronSchedule,
       rootDirectory: instance.rootDirectory,
@@ -1595,8 +1598,8 @@ mutation TreeseedRailwayServiceInstanceUpdateLegacy($serviceId: String!, $enviro
     updated: true
   };
 }
-function serviceInstanceDrifted(current, desired) {
-  return desired.buildCommand !== null && desired.buildCommand !== current.buildCommand || desired.startCommand !== null && desired.startCommand !== current.startCommand || desired.cronSchedule !== null && desired.cronSchedule !== current.cronSchedule || desired.rootDirectory !== null && desired.rootDirectory !== current.rootDirectory || desired.healthcheckPath !== null && desired.healthcheckPath !== current.healthcheckPath || desired.healthcheckTimeoutSeconds !== null && desired.healthcheckTimeoutSeconds !== current.healthcheckTimeoutSeconds || desired.runtimeMode !== null && desired.runtimeMode !== current.runtimeMode;
+function serviceInstanceDrifted(current, desired, clearSourceConfiguration = false) {
+  return (desired.buildCommand !== null || clearSourceConfiguration) && desired.buildCommand !== current.buildCommand || (desired.dockerfilePath !== null && desired.dockerfilePath !== void 0 || clearSourceConfiguration) && (desired.dockerfilePath ?? null) !== current.dockerfilePath || (desired.railwayConfigFile !== null && desired.railwayConfigFile !== void 0 || clearSourceConfiguration) && (desired.railwayConfigFile ?? null) !== current.railwayConfigFile || (desired.startCommand !== null || clearSourceConfiguration) && desired.startCommand !== current.startCommand || desired.cronSchedule !== null && desired.cronSchedule !== current.cronSchedule || (desired.rootDirectory !== null || clearSourceConfiguration) && desired.rootDirectory !== current.rootDirectory || desired.healthcheckPath !== null && desired.healthcheckPath !== current.healthcheckPath || desired.healthcheckTimeoutSeconds !== null && desired.healthcheckTimeoutSeconds !== current.healthcheckTimeoutSeconds || desired.runtimeMode !== null && desired.runtimeMode !== current.runtimeMode;
 }
 async function listRailwayVariables({
   projectId,

package/dist/operations/services/railway-deploy.d.ts

@@ -59,7 +59,7 @@ export declare function waitForRailwayManagedDeploymentsSettled(tenantRoot: any,
     };
     message: string;
 }>;
-export declare function configuredRailwayServices(tenantRoot: any, scope: any): unknown[];
+export declare function configuredRailwayServices(tenantRoot: any, scope: any, envOverlay?: {}): unknown[];
 export declare function configuredRailwayScheduledJobs(tenantRoot: any, scope: any, { phase }?: {
     phase?: string | undefined;
 }): any[];

package/dist/operations/services/railway-deploy.js

@@ -611,13 +611,14 @@ query TreeseedRailwayDeploymentStatus($projectId: String!) {
   });
   return payload.data?.project ?? null;
 }
-function configuredRailwayServicesForConfig(tenantRoot, scope, deployConfig, application = null, machineConfigRoot = tenantRoot) {
+function configuredRailwayServicesForConfig(tenantRoot, scope, deployConfig, application = null, machineConfigRoot = tenantRoot, envOverlay = {}) {
   const normalizedScope = normalizeScope(scope);
   const imageRefKeys = [
     "TREESEED_API_IMAGE_REF",
     "TREESEED_OPERATIONS_RUNNER_IMAGE_REF",
     "TREESEED_AGENT_MANAGER_IMAGE_REF",
-    "TREESEED_AGENT_RUNNER_IMAGE_REF"
+    "TREESEED_AGENT_RUNNER_IMAGE_REF",
+    "TREESEED_PUBLIC_TREEDX_IMAGE_REF"
   ];
   let machineEnv = {};
   try {
@@ -625,7 +626,7 @@ function configuredRailwayServicesForConfig(tenantRoot, scope, deployConfig, app
   } catch {
     machineEnv = {};
   }
-  const imageRefEnv = { ...process.env, ...machineEnv };
+  const imageRefEnv = { ...process.env, ...machineEnv, ...envOverlay };
   let identity;
   try {
     identity = resolveTreeseedResourceIdentity(deployConfig, createPersistentDeployTarget(normalizedScope));
@@ -882,9 +883,9 @@ function resolveRailwayCapacityProviderRoot(tenantRoot, service) {
   );
   return found ?? resolve(tenantRoot, "packages", "agent");
 }
-function configuredRailwayServices(tenantRoot, scope) {
+function configuredRailwayServices(tenantRoot, scope, envOverlay = {}) {
   const deployConfig = loadCliDeployConfig(tenantRoot);
-  const direct = configuredRailwayServicesForConfig(tenantRoot, scope, deployConfig);
+  const direct = configuredRailwayServicesForConfig(tenantRoot, scope, deployConfig, null, tenantRoot, envOverlay);
   const nested = discoverTreeseedApplications(tenantRoot).filter((application) => application.root !== resolve(tenantRoot)).flatMap((application) => configuredRailwayServicesForConfig(
     application.root,
     scope,
@@ -894,7 +895,8 @@ function configuredRailwayServices(tenantRoot, scope) {
       root: application.root,
       relativeRoot: application.relativeRoot
     },
-    tenantRoot
+    tenantRoot,
+    envOverlay
   ));
   return [...direct, ...nested];
 }

package/dist/operations-registry.js

@@ -22,6 +22,7 @@ const TRESEED_OPERATION_SPECS = [
   operation({ id: "workspace.doctor", name: "doctor", aliases: [], group: "Validation", summary: "Diagnose Treeseed tooling, auth, and workflow readiness.", description: "Collect doctor-style diagnostics for workspace readiness and optional safe repairs.", provider: "default", related: ["status", "config"] }),
   operation({ id: "workspace.install", name: "install", aliases: [], group: "Utilities", summary: "Install Treeseed-managed local dependencies.", description: "Install or repair Treeseed-managed CLI dependencies including GitHub CLI, Wrangler, Railway, Copilot, and optional gh-act support.", provider: "default", related: ["config", "doctor"] }),
   operation({ id: "workspace.tools", name: "tools", aliases: [], group: "Utilities", summary: "Report Treeseed-managed executable locations.", description: "Inspect Treeseed-managed executable paths, invocation commands, cache roots, and GitHub CLI authentication state without installing or mutating tools.", provider: "default", related: ["install", "doctor"] }),
+  operation({ id: "workspace.cleanup", name: "cleanup", aliases: [], group: "Utilities", summary: "Prune local generated artifacts and package caches before long verification.", description: "Remove local Treeseed temporary/cache directories, generated scene and release evidence, npm cache, and optional Docker images and volumes.", provider: "default", related: ["save", "stage", "release"] }),
   operation({ id: "auth.login", name: "auth:login", aliases: [], group: "Validation", summary: "Authenticate against the configured Treeseed API.", description: "Start the device login flow against the active Treeseed API host and persist the returned session locally.", provider: "default", related: ["auth:check", "auth:whoami", "auth:logout"] }),
   operation({ id: "auth.logout", name: "auth:logout", aliases: [], group: "Validation", summary: "Clear locally stored Treeseed API credentials.", description: "Remove the persisted local device-flow session for the active Treeseed API host.", provider: "default", related: ["auth:login", "auth:whoami"] }),
   operation({ id: "auth.whoami", name: "auth:whoami", aliases: [], group: "Validation", summary: "Inspect the active Treeseed API identity.", description: "Use the persisted local remote session to query the active Treeseed API principal.", provider: "default", related: ["auth:login", "status"] }),

package/dist/reconcile/builtin-adapters.js

@@ -3477,6 +3477,7 @@ async function resolveRailwayTopologyForScope(input, scope, {
             healthcheckIntervalSeconds: service.healthcheckIntervalSeconds,
             restartPolicy: service.restartPolicy,
             runtimeMode: service.runtimeMode,
+            clearSourceConfiguration: service.sourceMode === "image" || Boolean(service.imageRef),
             env
           })).instance;
         } else {
@@ -3534,6 +3535,15 @@ function railwayProviderDrift(input, scope) {
   const current = input.context.session.get(railwayDriftSessionKey(scope));
   return Array.isArray(current) ? current : [];
 }
+function configuredRailwayServicesForInput(input, scope) {
+  return configuredRailwayServices(input.context.tenantRoot, scope, resolveReconcileEnvironmentValues(input, scope));
+}
+function assertNoBlockedRailwayProviderDrift(input, scope) {
+  const blocked = railwayProviderDrift(input, scope).filter((drift) => drift.status === "blocked" || drift.action === "blocked" || drift.action === "manual-repair-required");
+  if (blocked.length === 0) return;
+  const reasons = blocked.map((drift) => String(drift.reason ?? drift.kind ?? "unknown Railway drift"));
+  throw new Error(`Railway provider drift blocks reconciliation: ${reasons.join("; ")}`);
+}
 function activeRailwayVolumeInstances(volume) {
   const instances = Array.isArray(volume.instances) ? volume.instances : [];
   return instances.filter((instance) => {
@@ -3550,7 +3560,7 @@ function railwayServiceMatchesKey(service, key) {
   return service.key === key || service.instanceKey === key || service.serviceName === key || service.serviceId === key;
 }
 function configuredRailwayProjectSyncGroups(input, scope, serviceKeys) {
-  const allServices = configuredRailwayServices(input.context.tenantRoot, scope).filter((service) => service.enabled !== false).filter((service) => !isRailwayCapacityProviderService(service));
+  const allServices = configuredRailwayServicesForInput(input, scope).filter((service) => service.enabled !== false).filter((service) => !isRailwayCapacityProviderService(service));
   const selected = Array.isArray(serviceKeys) && serviceKeys.length > 0 ? allServices.filter((service) => serviceKeys.some((key) => railwayServiceMatchesKey(service, key))) : allServices;
   const selectedProjectKeys = new Set(selected.map((service) => `${service.projectName}:::${service.railwayEnvironment}`));
   const grouped = /* @__PURE__ */ new Map();
@@ -3572,6 +3582,9 @@ function railwayIacServiceInput(input, sync, service, scope) {
   if (scope === "prod" && service.sourceMode === "git") {
     throw new Error(`Railway production service ${service.serviceName} must deploy an immutable image, not Git source.`);
   }
+  if (scope === "prod" && service.sourceMode === "image" && !service.imageRef) {
+    throw new Error(`Railway production service ${service.serviceName} must deploy an immutable image, but no image reference was resolved.`);
+  }
   const serviceSync = sync.forService(service.key, service);
   const deployVariablePrefix = service.serviceName.includes("treedx") || service.key.includes("treedx") ? "TREEDX" : "TREESEED";
   const sourceVariables = service.sourceMode === "git" ? {
@@ -3648,7 +3661,7 @@ function blockedPendingRailwayVolumeAttachments(volumes, serviceIdByName, enviro
 }
 async function reconcileStaleOperationsRunnerResourcesForScope(input, topology) {
   const scope = input.context.target.kind === "persistent" ? input.context.target.scope : "staging";
-  const desiredRunners = configuredRailwayServices(input.context.tenantRoot, scope).filter((service) => service.key === "operationsRunner").filter((service) => service.enabled !== false);
+  const desiredRunners = configuredRailwayServicesForInput(input, scope).filter((service) => service.key === "operationsRunner").filter((service) => service.enabled !== false);
   const desiredServiceNames = new Set(desiredRunners.map((service) => service.serviceName).filter(Boolean));
   const desiredVolumeNames = new Set([...desiredServiceNames].map((serviceName) => `${serviceName}-volume`));
   if (desiredServiceNames.size === 0) {
@@ -3763,6 +3776,9 @@ async function syncRailwayEnvironmentForScope(input, { dryRun = false, serviceKe
     const project = resolvedEntry?.project;
     const environment = resolvedEntry?.environment;
     traceRailwayReconcile(topology.env, "sync:topology", `project-services=${projectServices.map((service) => service.serviceName).join(",")}`);
+    for (const service of projectServices) {
+      railwayIacServiceInput(input, sync, service, scope);
+    }
     if (dryRun) {
       syncedServices.push(...projectServices);
       continue;
@@ -3854,6 +3870,7 @@ async function syncRailwayEnvironmentForScope(input, { dryRun = false, serviceKe
         const diagnostics = apply.diagnostics.map((entry) => entry.message).filter(Boolean).join("; ");
         throw new Error(`Railway IaC apply failed for ${project.name}/${environment.name}${diagnostics ? `: ${diagnostics}` : "."}`);
       }
+      assertNoBlockedRailwayProviderDrift(input, scope);
       syncedServices.push(...projectServices);
     } finally {
       cleanupRailwayIacRender(rendered);
@@ -4319,7 +4336,7 @@ async function observeRailwayUnit(input, { refresh = false } = {}) {
 function collectRailwayEnvironmentSync(input, valuesOverlay = {}) {
   const scope = input.context.target.kind === "persistent" ? input.context.target.scope : "staging";
   const registry = collectTreeseedEnvironmentContext(input.context.tenantRoot);
-  const configuredServices = configuredRailwayServices(input.context.tenantRoot, scope);
+  const configuredServices = configuredRailwayServicesForInput(input, scope);
   const hasPublicTreeDxService = configuredServices.some((service) => service.key === "public-treedx-node-01" && service.enabled !== false);
   const machineValues = hasPublicTreeDxService ? normalizeEnvironmentValues(resolveTreeseedMachineEnvironmentValues(input.context.tenantRoot, scope)) : {};
   const baseValues = {
@@ -4451,7 +4468,7 @@ function capacityProviderSecretsForService(values, serviceKey) {
   return apiKey ? { TREESEED_CAPACITY_PROVIDER_API_KEY: apiKey } : {};
 }
 function ensureCapacityProviderApiKeyForRailwaySync(input, scope) {
-  const hasCapacityProviderService = configuredRailwayServices(input.context.tenantRoot, scope).some((service) => String(service.key).startsWith("capacityProvider") && service.enabled !== false);
+  const hasCapacityProviderService = configuredRailwayServicesForInput(input, scope).some((service) => String(service.key).startsWith("capacityProvider") && service.enabled !== false);
   if (!hasCapacityProviderService) return null;
   const values = resolveReconcileEnvironmentValues(input, scope);
   const existing = String(values.TREESEED_CAPACITY_PROVIDER_API_KEY ?? "").trim();
@@ -4475,7 +4492,7 @@ function ensureCapacityProviderApiKeyForRailwaySync(input, scope) {
   return generated;
 }
 function ensurePublicTreeDxSecretsForRailwaySync(input, scope, values, registry) {
-  const hasPublicTreeDxService = configuredRailwayServices(input.context.tenantRoot, scope).some((service) => service.key === "public-treedx-node-01" && service.enabled !== false);
+  const hasPublicTreeDxService = configuredRailwayServicesForInput(input, scope).some((service) => service.key === "public-treedx-node-01" && service.enabled !== false);
   if (!hasPublicTreeDxService) return {};
   const generated = {};
   const specs = [
@@ -4937,6 +4954,16 @@ async function verifyRailwayUnit(input) {
           issues: entry.instance?.id ? [] : [`Railway service instance for ${service.serviceName ?? service.key} in ${service.railwayEnvironment} is missing.`]
         })
       ];
+      if (service.sourceMode === "image") {
+        const hasImageRef = typeof service.imageRef === "string" && service.imageRef.trim().length > 0;
+        checks.push(verificationCheck("railway.instance.image-ref", "Railway image source has an immutable image reference", "sdk", {
+          exists: hasImageRef,
+          configured: hasImageRef,
+          expected: service.imageRefEnv ? `${service.imageRefEnv}=<image>:<tag>` : "<image>:<tag>",
+          observed: service.imageRef ?? null,
+          issues: hasImageRef ? [] : [`Railway production service ${service.serviceName ?? service.key} is configured for image deployment but no image reference was resolved.`]
+        }));
+      }
       if (service.startCommand) {
         const startCommandMatches = railwayStartCommandMatches(serviceKey, entry.instance?.startCommand, service.startCommand);
         checks.push(verificationCheck("railway.instance.start-command", "Railway start command matches desired config", "api", {
@@ -5129,7 +5156,7 @@ function buildRailwayDiff(input, observed) {
 async function reconcileRailwayUnit(input, diff) {
   const scope = input.context.target.kind === "persistent" ? input.context.target.scope : "staging";
   const serviceKey = String(input.unit.metadata.serviceKey ?? "").trim();
-  const configuredService = configuredRailwayServices(input.context.tenantRoot, scope).find((candidate) => candidate.key === serviceKey || candidate.instanceKey === serviceKey || candidate.serviceName === serviceKey) ?? null;
+  const configuredService = configuredRailwayServicesForInput(input, scope).find((candidate) => candidate.key === serviceKey || candidate.instanceKey === serviceKey || candidate.serviceName === serviceKey) ?? null;
   const requiresProjectLevelSync = Boolean(configuredService);
   const serviceKeys = serviceKey && !requiresProjectLevelSync ? [serviceKey] : void 0;
   const cacheKey = requiresProjectLevelSync ? `railway:sync:${scope}:project:${configuredService?.projectName ?? "default"}:${configuredService?.railwayEnvironment ?? scope}` : `railway:sync:${scope}:${serviceKey || "all"}`;

package/dist/scenes/device-matrix.js

@@ -64,6 +64,7 @@ async function runTreeseedSceneDeviceMatrix(input) {
       environment: input.environment,
       device,
       record: input.record,
+      artifactMode: input.artifactMode,
       mode: input.mode,
       timestamp: input.timestamp,
       runId: `${matrixId}-${device}`,

package/dist/scenes/devices.js

@@ -1,12 +1,30 @@
 import { sceneErrorDiagnostic } from "./diagnostics.js";
 import { defaultTreeseedSceneDeviceConfig } from "./schema.js";
+const LEGACY_DEVICE_PROFILE_ALIASES = {
+  desktop_chromium: "desktop",
+  desktop_firefox: "desktop",
+  desktop_webkit: "desktop",
+  tablet_chromium: "tablet",
+  tablet_firefox: "tablet",
+  tablet_webkit: "tablet",
+  mobile_chromium: "mobile",
+  mobile_firefox: "mobile",
+  mobile_webkit: "mobile"
+};
 function listTreeseedSceneDeviceProfiles(scene) {
-  return scene.devices?.profiles?.length ? scene.devices.profiles : defaultTreeseedSceneDeviceConfig().profiles;
+  const sceneProfiles = scene.devices?.profiles ?? [];
+  if (sceneProfiles.length === 0) return defaultTreeseedSceneDeviceConfig().profiles;
+  const seen = new Set(sceneProfiles.map((entry) => entry.id));
+  return [
+    ...sceneProfiles,
+    ...defaultTreeseedSceneDeviceConfig().profiles.filter((entry) => !seen.has(entry.id))
+  ];
 }
 function resolveTreeseedSceneDeviceProfile(input) {
   const profiles = listTreeseedSceneDeviceProfiles(input.scene);
   const selected = input.device ?? input.scene.devices?.defaultProfile ?? "desktop";
-  const profile = profiles.find((entry) => entry.id === selected) ?? null;
+  const normalized = LEGACY_DEVICE_PROFILE_ALIASES[selected] ?? selected;
+  const profile = profiles.find((entry) => entry.id === normalized) ?? (selected in LEGACY_DEVICE_PROFILE_ALIASES ? profiles.find((entry) => entry.id === input.scene.devices?.defaultProfile) ?? profiles[0] ?? null : null);
   if (!profile) {
     return {
       profile: null,

package/dist/scenes/runner.js

@@ -221,8 +221,9 @@ async function runTreeseedScene(input) {
   }
   const paths = plan.artifactPaths;
   ensureTreeseedSceneRunDirectories(paths);
+  const screenshotOnlyArtifacts = input.artifactMode === "screenshots";
   const tracePath = scene.artifacts.trace ? join(paths.playwrightRoot, "trace.zip") : null;
-  const videoDir = input.record || scene.artifacts.video ? join(paths.playwrightRoot, "videos") : null;
+  const videoDir = !screenshotOnlyArtifacts && (input.record || scene.artifacts.video) ? join(paths.playwrightRoot, "videos") : null;
   const recordingVideo = Boolean(videoDir);
   const capture = resolveCapture({ scene, device, runtimeMode: runtime.mode, recording: Boolean(videoDir) });
   const artifacts = createTreeseedSceneRunArtifacts({ paths, playwrightTracePath: tracePath });

package/dist/scenes/types.d.ts

@@ -470,6 +470,7 @@ export type TreeseedSceneRunOptions = {
     environment?: TreeseedSceneEnvironment;
     device?: TreeseedSceneDeviceProfileId;
     record?: boolean;
+    artifactMode?: 'full' | 'screenshots';
     runId?: string;
     timestamp?: string;
     browserAdapter?: TreeseedSceneBrowserAdapter;
@@ -491,6 +492,7 @@ export type TreeseedSceneDeviceMatrixOptions = {
     environment?: TreeseedSceneEnvironment;
     devices?: TreeseedSceneDeviceProfileId[];
     record?: boolean;
+    artifactMode?: 'full' | 'screenshots';
     mode?: TreeseedSceneExecutionMode;
     timestamp?: string;
     browserAdapter?: TreeseedSceneBrowserAdapter;

package/dist/workflow/operations.d.ts

@@ -525,6 +525,8 @@ export declare function workflowSave(helpers: WorkflowOperationHelpers, input: T
         } | null;
     } | null;
     workspaceLinks: import("../operations/services/workspace-dependency-mode.js").WorkspaceDependencyModeReport;
+    sceneArtifacts: "full" | "screenshots";
+    localCleanup: import("../workflow-support.js").TreeseedLocalCleanupReport | null;
     ciMode: "hosted" | "off";
     lane: string;
     verifyMode: "action-first" | "local-only" | import("../workflow.js").TreeseedWorkflowVerifyMode;
@@ -690,6 +692,8 @@ export declare function workflowClose(helpers: WorkflowOperationHelpers, input:
             } | null;
         } | null;
         workspaceLinks: import("../operations/services/workspace-dependency-mode.js").WorkspaceDependencyModeReport;
+        sceneArtifacts: "full" | "screenshots";
+        localCleanup: import("../workflow-support.js").TreeseedLocalCleanupReport | null;
         ciMode: "hosted" | "off";
         lane: string;
         verifyMode: "action-first" | "local-only" | import("../workflow.js").TreeseedWorkflowVerifyMode;
@@ -869,6 +873,8 @@ export declare function workflowStage(helpers: WorkflowOperationHelpers, input:
     cleanupMode: StageCleanupMode;
     updateFrom: string;
     waitForStaging: boolean;
+    sceneArtifacts: "full" | "screenshots";
+    localCleanup: import("../workflow-support.js").TreeseedLocalCleanupReport | null;
     applicationSelection: WorkflowApplicationSelection;
     plan: {
         schemaVersion: 1;
@@ -903,6 +909,8 @@ export declare function workflowRelease(helpers: WorkflowOperationHelpers, input
     target: TreeseedReconcileTarget;
     executionMode: TreeseedWorkflowExecutionMode;
     verifyDeployedResources: boolean;
+    releaseImageRefs: Record<string, string>;
+    includeHostedReleaseGates: boolean;
     desiredGraph: import("../index.js").TreeseedDesiredResourceGraph;
     units: {
         unitId: string;
@@ -945,6 +953,8 @@ export declare function workflowRelease(helpers: WorkflowOperationHelpers, input
         ciMode: "hosted" | "off";
         level: "patch" | "major" | "minor";
         fresh: boolean;
+        sceneArtifacts: "full" | "screenshots";
+        localCleanup: import("../workflow-support.js").TreeseedLocalCleanupReport | null;
         autoResumeCandidate: {
             runId: string;
             branch: string | null;
@@ -1182,6 +1192,8 @@ export declare function workflowRelease(helpers: WorkflowOperationHelpers, input
     ciMode: "hosted" | "off";
     level: "patch" | "major" | "minor";
     fresh: boolean;
+    sceneArtifacts: "full" | "screenshots";
+    localCleanup: import("../workflow-support.js").TreeseedLocalCleanupReport | null;
     freshArchivedRuns: never[];
     autoResumeCandidate: {
         runId: string;
@@ -1241,6 +1253,20 @@ export declare function workflowRelease(helpers: WorkflowOperationHelpers, input
 export declare function workflowResume(helpers: WorkflowOperationHelpers, input: TreeseedResumeInput): Promise<any>;
 export declare function workflowRecover(helpers: WorkflowOperationHelpers, input?: TreeseedRecoverInput): Promise<TreeseedWorkflowResult<{
     lock: import("./runs.js").TreeseedWorkflowLockInspection;
+    locks: {
+        lock: import("./runs.js").TreeseedWorkflowLockRecord | null;
+        active: boolean;
+        stale: boolean;
+        staleReason: string | null;
+        scope: "worktree" | "shared";
+    }[];
+    clearedStaleLocks: {
+        scope: "worktree" | "shared";
+        runId: string;
+        command: TreeseedWorkflowRunCommand;
+        staleReason: string | null;
+        removed: boolean;
+    }[];
     interruptedRuns: {
         runId: string;
         command: TreeseedWorkflowRunCommand;

package/dist/workflow/operations.js

@@ -158,6 +158,7 @@ import {
   resolveTreeseedWorkflowSession
 } from "./session.js";
 import { checkedOutManagedWorkflowRepos } from "../operations/services/managed-repositories.js";
+import { runTreeseedLocalCleanup } from "../operations/services/local-cleanup.js";
 import {
   classifyTreeseedBranchRole,
   resolveTreeseedWorkflowPaths
@@ -326,6 +327,14 @@ function normalizeSaveLane(lane) {
   const value = lane ?? process.env.TREESEED_SAVE_LANE;
   return value === "promotion" ? "promotion" : "fast";
 }
+function normalizeSceneArtifactsMode(value) {
+  return value === "screenshots" ? "screenshots" : "full";
+}
+function maybeRunLocalWorkflowCleanup(helpers, root, operation, input) {
+  if (normalizeExecutionMode(input) === "plan" || input.skipCleanup === true) return null;
+  helpers.write(`Treeseed ${operation} cleanup: pruning local caches, generated evidence, npm cache, and Docker artifacts before long verification.`, "stderr");
+  return runTreeseedLocalCleanup({ root, mode: "aggressive" });
+}
 function normalizeSaveCiMode(mode, branch, lane = "fast") {
   if (mode === "hosted" || mode === "off") return mode;
   if (lane === "promotion") return branch === STAGING_BRANCH || branch === PRODUCTION_BRANCH ? "hosted" : "off";
@@ -524,8 +533,14 @@ function selectorFromWorkflowHostingGraph(graph) {
     }))]
   };
 }
-async function reconcileSaveHostedEnvironment(root, environment, helpers, workflowRunId, operation = "save") {
-  const graph = compileTreeseedHostingGraph({ tenantRoot: root, environment });
+async function reconcileSaveHostedEnvironment(root, environment, helpers, workflowRunId, operation = "save", envOverlay = {}) {
+  const target = createPersistentDeployTarget(environment);
+  const env = {
+    ...helpers.context.env,
+    ...collectTreeseedConfigSeedValues(root, environment, helpers.context.env),
+    ...envOverlay
+  };
+  const graph = compileTreeseedHostingGraph({ tenantRoot: root, environment, env });
   const selector = selectorFromWorkflowHostingGraph(graph);
   if (process.env.TREESEED_WORKFLOW_HOSTED_RECONCILE_MODE === "skip") {
     return {
@@ -542,11 +557,6 @@ async function reconcileSaveHostedEnvironment(root, environment, helpers, workfl
       }))
     };
   }
-  const target = createPersistentDeployTarget(environment);
-  const env = {
-    ...helpers.context.env,
-    ...collectTreeseedConfigSeedValues(root, environment, helpers.context.env)
-  };
   const reconcileSession = /* @__PURE__ */ new Map([["workflowRunId", workflowRunId]]);
   helpers.write(`[${operation}][workflow] Reconciling ${environment} hosted deployments for ${graph.units.length} selected resources.`);
   const reconcile = await reconcileTreeseedTarget({
@@ -605,6 +615,24 @@ ${liveFailures.join("\n")}`, {
     liveVerification: live
   };
 }
+function productionReleaseImageRefEnv(selectedVersions) {
+  const refs = {};
+  const apiVersion = selectedVersions.get("@treeseed/api");
+  if (apiVersion) {
+    refs.TREESEED_API_IMAGE_REF = `treeseed/api:${apiVersion}`;
+    refs.TREESEED_OPERATIONS_RUNNER_IMAGE_REF = `treeseed/op-runner:${apiVersion}`;
+  }
+  const agentVersion = selectedVersions.get("@treeseed/agent");
+  if (agentVersion) {
+    refs.TREESEED_AGENT_MANAGER_IMAGE_REF = `treeseed/agent-manager:${agentVersion}`;
+    refs.TREESEED_AGENT_RUNNER_IMAGE_REF = `treeseed/agent-runner:${agentVersion}`;
+  }
+  const treedxVersion = selectedVersions.get("treedx") ?? selectedVersions.get("@treeseed/treedx");
+  if (treedxVersion) {
+    refs.TREESEED_PUBLIC_TREEDX_IMAGE_REF = `treeseed/treedx:${treedxVersion}`;
+  }
+  return refs;
+}
 function recordHostedDeploymentStatesFromRootGates(root, rootRelease, workflowGates) {
   const gates = Array.isArray(workflowGates) ? workflowGates.map((gate) => stringRecord(gate)).filter((gate) => Boolean(gate)) : [];
   const releaseRecord = stringRecord(rootRelease) ?? {};
@@ -2455,7 +2483,10 @@ async function fetchJsonForArtifact(url) {
   const timeout = setTimeout(() => controller.abort(), 2e4);
   try {
     const response = await fetch(url, {
-      headers: { accept: "application/json" },
+      headers: {
+        accept: "application/json",
+        "user-agent": "treeseed-release-verifier/1.0 (https://treeseed.dev)"
+      },
       signal: controller.signal
     });
     let json = null;
@@ -4019,6 +4050,7 @@ async function workflowSave(helpers, input) {
       const autoResumeRun = executionMode === "execute" && !explicitResumeRunId ? findAutoResumableSaveRun(root, branch) : null;
       const planAutoResumeRun = executionMode === "plan" ? findAutoResumableSaveRun(root, branch) : null;
       const effectiveInput = autoResumeRun ? autoResumeRun.input : input;
+      const localCleanup = maybeRunLocalWorkflowCleanup(helpers, root, "save", effectiveInput);
       const message = String(effectiveInput.message ?? "").trim();
       const saveLane = normalizeSaveLane(effectiveInput.lane);
       const saveCiMode = normalizeSaveCiMode(effectiveInput.ciMode, branch, saveLane);
@@ -4075,6 +4107,8 @@ async function workflowSave(helpers, input) {
               failure: planAutoResumeRun.failure
             } : null,
             workspaceLinks,
+            sceneArtifacts: normalizeSceneArtifactsMode(effectiveInput.sceneArtifacts),
+            localCleanup,
             ciMode: saveCiMode,
             lane: saveLane,
             verifyMode: effectiveInput.verifyMode ?? "fast",
@@ -4854,6 +4888,7 @@ async function workflowStage(helpers, input) {
       const autoResumeRun = rawAutoResumeRun?.steps.some((step) => step.id === "preflight") ? rawAutoResumeRun : null;
       const planAutoResumeRun = executionMode === "plan" ? findAutoResumableTaskRun(root, "stage", session.branchName) : null;
       const effectiveInput = autoResumeRun ? autoResumeRun.input : input;
+      const localCleanup = maybeRunLocalWorkflowCleanup(helpers, root, "stage", effectiveInput);
       const message = ensureMessage("stage", effectiveInput.message, "a resolution message");
       if (effectiveInput.verifyDeployedResources === true) {
         workflowError("stage", "validation_failed", "Stage no longer verifies deployed resources. Promote refs with stage, then run staging release/hosting verification separately.");
@@ -4881,6 +4916,8 @@ async function workflowStage(helpers, input) {
         cleanupMode,
         updateFrom,
         waitForStaging: ciMode === "hosted",
+        sceneArtifacts: normalizeSceneArtifactsMode(effectiveInput.sceneArtifacts),
+        localCleanup,
         applicationSelection,
         plan,
         phases: plan.phases,
@@ -5123,13 +5160,15 @@ ${currentBlockers.map((entry) => `- ${entry}`).join("\n")}`, {
 }
 async function runReleaseGateReconcileFacade(operation, helpers, root, target, input, extraPayload = {}) {
   const executionMode = normalizeExecutionMode(input);
+  const reconcileEnv = { ...helpers.context.env, ...input.releaseImageRefs ?? {} };
+  const includeHostedReleaseGates = input.includeHostedReleaseGates === true;
   const selector = {
     environment: target.kind === "persistent" ? target.scope : "staging",
     resourceKind: ["release-gate"],
     provider: ["treeseed"]
   };
   const desiredGraph = compileTreeseedDesiredResourceGraph({ tenantRoot: root, target });
-  const rawUnits = compileTreeseedDesiredUnitsFromGraph(desiredGraph).filter((unit) => unit.provider === "treeseed" && (unit.unitType === "package-manifest" || unit.unitType.startsWith("release-gate:")) || unit.provider === "github" && (unit.unitType === "github-environment" || unit.unitType === "github-secret-binding" || unit.unitType === "github-variable-binding"));
+  const rawUnits = compileTreeseedDesiredUnitsFromGraph(desiredGraph).filter((unit) => unit.provider === "treeseed" && (unit.unitType === "package-manifest" || unit.unitType.startsWith("release-gate:")) && (includeHostedReleaseGates || unit.unitType !== "release-gate:hosted-reconcile" && unit.unitType !== "release-gate:live-verify") || unit.provider === "github" && (unit.unitType === "github-environment" || unit.unitType === "github-secret-binding" || unit.unitType === "github-variable-binding"));
   const rawUnitIds = new Set(rawUnits.map((unit) => unit.unitId));
   const units = rawUnits.map((unit) => ({
     ...unit,
@@ -5142,7 +5181,7 @@ async function runReleaseGateReconcileFacade(operation, helpers, root, target, i
   const plan = await planTreeseedReconciliation({
     tenantRoot: root,
     target,
-    env: helpers.context.env,
+    env: reconcileEnv,
     units,
     selector: unitSelector,
     write: (line) => helpers.write(`[${operation}][reconcile] ${line}`, "stderr")
@@ -5165,7 +5204,7 @@ ${blockers.join("\n")}`, {
   const result = executionMode === "execute" ? await reconcileTreeseedTarget({
     tenantRoot: root,
     target,
-    env: helpers.context.env,
+    env: reconcileEnv,
     units,
     selector: unitSelector,
     dryRun: input.execute !== true,
@@ -5177,6 +5216,8 @@ ${blockers.join("\n")}`, {
     target,
     executionMode,
     verifyDeployedResources: input.verifyDeployedResources === true,
+    releaseImageRefs: input.releaseImageRefs ?? {},
+    includeHostedReleaseGates,
     desiredGraph,
     units: units.map((unit) => ({
       unitId: unit.unitId,
@@ -5217,6 +5258,7 @@ async function workflowRelease(helpers, input) {
         ...autoResumeRun.input,
         ciMode: input.ciMode ?? autoResumeRun.input.ciMode
       } : input;
+      const localCleanup = maybeRunLocalWorkflowCleanup(helpers, root, "release", effectiveInput);
       const level = effectiveInput.bump ?? "patch";
       const ciMode = normalizeCiMode(effectiveInput.ciMode, "release");
       const packageSelection = session.packageSelection;
@@ -5249,6 +5291,8 @@ async function workflowRelease(helpers, input) {
         ciMode,
         level,
         fresh: input.fresh === true,
+        sceneArtifacts: normalizeSceneArtifactsMode(effectiveInput.sceneArtifacts),
+        localCleanup,
         freshArchivedRuns: [],
         autoResumeCandidate: planAutoResumeRun ? {
           runId: planAutoResumeRun.runId,
@@ -5342,7 +5386,8 @@ ${blockers.join("\n")}`, {
           { kind: "persistent", scope: "prod" },
           {
             execute: true,
-            verifyDeployedResources: effectiveInput.verifyDeployedResources
+            verifyDeployedResources: effectiveInput.verifyDeployedResources,
+            releaseImageRefs: productionReleaseImageRefEnv(selectedVersions)
           },
           {
             ...releaseBasePayload,
@@ -5472,7 +5517,7 @@ ${rendered}`);
           onProgress: (line, stream) => helpers.write(line, stream)
         }).then((workflowGates) => ({ workflowGates })));
         const publishedArtifacts = await executeJournalStep(root, workflowRun.runId, "verify-published-artifacts", () => verifyPublishedReleaseArtifacts(selectedVersions));
-        const productionHosting = await executeJournalStep(root, workflowRun.runId, "production-hosting", () => reconcileSaveHostedEnvironment(root, "prod", helpers, workflowRun.runId, "release"));
+        const productionHosting = await executeJournalStep(root, workflowRun.runId, "production-hosting", () => reconcileSaveHostedEnvironment(root, "prod", helpers, workflowRun.runId, "release", productionReleaseImageRefEnv(selectedVersions)));
         const backMerge = await executeJournalStep(root, workflowRun.runId, "release-back-merge", () => {
           const packageBackMerges = checkedOutWorkspacePackageRepos(root).filter((pkg) => selectedPackageSet.has(pkg.name)).map((pkg) => backMergeProductionIntoStaging(pkg.dir, pkg.name, releaseAdminMessage({
             subject: `release: back-merge ${PRODUCTION_BRANCH} into ${STAGING_BRANCH}`,
@@ -5611,7 +5656,22 @@ async function workflowRecover(helpers, input = {}) {
   try {
     return await withContextEnv(helpers.context.env, async () => {
       const root = resolveProjectRootOrThrow("recover", helpers.cwd());
-      const lock = inspectWorkflowLock(root, { scope: "worktree" });
+      const initialLocks = ["worktree", "shared"].map((scope) => ({
+        scope,
+        inspection: inspectWorkflowLock(root, { scope })
+      }));
+      const clearedStaleLocks = initialLocks.filter((entry) => entry.inspection.stale && entry.inspection.lock?.runId).map((entry) => ({
+        scope: entry.scope,
+        runId: entry.inspection.lock.runId,
+        command: entry.inspection.lock.command,
+        staleReason: entry.inspection.staleReason,
+        removed: releaseWorkflowLock(root, entry.inspection.lock.runId)
+      }));
+      const locks = ["worktree", "shared"].map((scope) => ({
+        scope,
+        inspection: inspectWorkflowLock(root, { scope })
+      }));
+      const lock = locks.find((entry) => entry.inspection.active)?.inspection ?? locks.find((entry) => entry.inspection.stale)?.inspection ?? locks[0].inspection;
       const journals = listWorkflowRunJournals(root);
       const session = resolveTreeseedWorkflowSession(root);
       const currentHeads = Object.fromEntries(
@@ -5682,6 +5742,8 @@ async function workflowRecover(helpers, input = {}) {
         root,
         {
           lock,
+          locks: locks.map((entry) => ({ scope: entry.scope, ...entry.inspection })),
+          clearedStaleLocks,
           interruptedRuns,
           staleRuns,
           obsoleteRuns,

package/dist/workflow/runs.js

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { closeSync, existsSync, fstatSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { hostname } from "node:os";
 import { dirname, resolve } from "node:path";
 const WORKFLOW_CONTROL_DIR = ".treeseed/workflow";
@@ -226,6 +226,80 @@ function writeWorkflowRunJournal(root, journal) {
 function readWorkflowRunJournal(root, runId) {
   return safeJsonParse(workflowRunPath(root, runId));
 }
+function jsonStringField(source, key) {
+  const pattern = new RegExp(`"${key}"\\s*:\\s*"([^"\\\\]*(?:\\\\.[^"\\\\]*)*)"`, "u");
+  const match = source.match(pattern);
+  if (!match) return null;
+  try {
+    return JSON.parse(`"${match[1]}"`);
+  } catch {
+    return match[1];
+  }
+}
+function jsonBooleanField(source, key) {
+  const pattern = new RegExp(`"${key}"\\s*:\\s*(true|false)`, "u");
+  const match = source.match(pattern);
+  return match ? match[1] === "true" : null;
+}
+function readFileEnds(path, bytes) {
+  const fd = openSync(path, "r");
+  try {
+    const stat = fstatSync(fd);
+    const headLength = Math.min(bytes, stat.size);
+    const tailLength = Math.min(bytes, stat.size);
+    const head = Buffer.alloc(headLength);
+    const tail = Buffer.alloc(tailLength);
+    readSync(fd, head, 0, headLength, 0);
+    readSync(fd, tail, 0, tailLength, Math.max(0, stat.size - tailLength));
+    return { size: stat.size, head: head.toString("utf8"), tail: tail.toString("utf8") };
+  } finally {
+    closeSync(fd);
+  }
+}
+function archivedWorkflowRunSummary(path) {
+  const { head, tail } = readFileEnds(path, 128 * 1024);
+  if (!tail.includes('"archivedAt"')) {
+    return null;
+  }
+  const runId = jsonStringField(head, "runId");
+  const command = jsonStringField(head, "command");
+  const executionMode = jsonStringField(head, "executionMode");
+  const status = jsonStringField(head, "status");
+  const createdAt = jsonStringField(head, "createdAt");
+  const updatedAt = jsonStringField(head, "updatedAt");
+  const archivedAt = jsonStringField(tail, "archivedAt");
+  const classifiedAt = jsonStringField(tail, "classifiedAt") ?? archivedAt;
+  if (!runId || !command || !executionMode || !status || !createdAt || !updatedAt || !archivedAt || !classifiedAt) {
+    return null;
+  }
+  return {
+    schemaVersion: 1,
+    kind: "treeseed.workflow.run",
+    runId,
+    command,
+    executionMode,
+    status,
+    createdAt,
+    updatedAt,
+    resumable: jsonBooleanField(head, "resumable") ?? false,
+    input: {},
+    session: {
+      root: "",
+      mode: "root-only",
+      branchName: null,
+      repos: []
+    },
+    steps: [],
+    failure: null,
+    result: null,
+    classification: {
+      state: "obsolete",
+      reasons: ["workflow run was archived"],
+      classifiedAt,
+      archivedAt
+    }
+  };
+}
 function updateWorkflowRunJournal(root, runId, updater) {
   const current = readWorkflowRunJournal(root, runId);
   if (!current) {
@@ -480,7 +554,18 @@ function listWorkflowRunJournalsForScope(root, scope) {
   if (!existsSync(runsDir)) {
     return [];
   }
-  return readdirSync(runsDir).filter((entry) => entry.endsWith(".json")).map((entry) => safeJsonParse(resolve(runsDir, entry))).filter((entry) => entry != null).sort((left, right) => right.createdAt.localeCompare(left.createdAt));
+  return readdirSync(runsDir).filter((entry) => entry.endsWith(".json")).map((entry) => {
+    const path = resolve(runsDir, entry);
+    try {
+      if (statSync(path).size > 5 * 1024 * 1024) {
+        const archivedSummary = archivedWorkflowRunSummary(path);
+        if (archivedSummary) return archivedSummary;
+      }
+    } catch {
+      return null;
+    }
+    return safeJsonParse(path);
+  }).filter((entry) => entry != null).sort((left, right) => right.createdAt.localeCompare(left.createdAt));
 }
 function listWorkflowRunJournals(root) {
   const local = listWorkflowRunJournalsForScope(root, "worktree");

package/dist/workflow-support.d.ts

@@ -5,6 +5,7 @@ export { collectTreeseedHostedServiceChecks, type TreeseedHostedServiceCheck, ty
 export { collectTreeseedDeploymentReadiness, formatTreeseedReadinessReport, type TreeseedDeploymentReadinessCheck, type TreeseedDeploymentReadinessReport, type TreeseedDeploymentReadinessStatus, } from './operations/services/deployment-readiness.js';
 export { collectTreeseedLiveHostedServiceChecks, type TreeseedLiveHostedServiceCheckOptions, type TreeseedLiveHostedServiceCheckReport, } from './operations/services/live-hosted-service-checks.js';
 export { runTreeseedOperationsRunnerSmoke, type TreeseedOperationsRunnerSmokeOptions, type TreeseedOperationsRunnerSmokeReport, } from './operations/services/operations-runner-smoke.js';
+export { runTreeseedLocalCleanup, type TreeseedLocalCleanupAction, type TreeseedLocalCleanupMode, type TreeseedLocalCleanupReport, } from './operations/services/local-cleanup.js';
 export { readTreeseedVerificationCache, treeseedVerificationCacheKey, writeTreeseedVerificationCache, type TreeseedVerificationCacheEntry, } from './operations/services/verification-cache.js';
 export { assertDeploymentInitialized, cleanupDestroyedState, createBranchPreviewDeployTarget, createPersistentDeployTarget, deployTargetLabel, destroyCloudflareResources, ensureGeneratedWranglerConfig, finalizeDeploymentState, loadDeployState, printDeploySummary, printDestroySummary, provisionCloudflareResources, runRemoteD1Migrations, syncCloudflareSecrets, validateDeployPrerequisites, validateDestroyPrerequisites, } from './operations/services/deploy.js';
 export { assertCleanWorktree, assertFeatureBranch, branchExists, checkoutBranch, createFeatureBranchFromStaging, currentManagedBranch, deleteLocalBranch, deleteRemoteBranch, ensureLocalBranchTracking, gitWorkflowRoot, listTaskBranches, mergeCurrentBranchIntoStaging, mergeStagingIntoMain, prepareReleaseBranches, PRODUCTION_BRANCH, pushBranch, remoteBranchExists, STAGING_BRANCH, syncBranchWithOrigin, waitForStagingAutomation, } from './operations/services/git-workflow.js';

package/dist/workflow-support.js

@@ -58,6 +58,9 @@ import {
 import {
   runTreeseedOperationsRunnerSmoke
 } from "./operations/services/operations-runner-smoke.js";
+import {
+  runTreeseedLocalCleanup
+} from "./operations/services/local-cleanup.js";
 import {
   readTreeseedVerificationCache,
   treeseedVerificationCacheKey,
@@ -349,6 +352,7 @@ export {
   runTreeseedGit,
   runTreeseedGitBatch,
   runTreeseedHostingAudit,
+  runTreeseedLocalCleanup,
   runTreeseedOperationsRunnerSmoke,
   runTreeseedPackageImageWorkflow,
   runWorkspaceReleasePreflight,

package/dist/workflow.d.ts

@@ -119,6 +119,8 @@ export type TreeseedSaveInput = {
     workspaceLinks?: 'auto' | 'off';
     releaseCandidate?: TreeseedReleaseCandidateMode;
     verifyDeployedResources?: boolean;
+    skipCleanup?: boolean;
+    sceneArtifacts?: 'full' | 'screenshots';
     plan?: boolean;
     dryRun?: boolean;
 };
@@ -175,6 +177,8 @@ export type TreeseedStageInput = {
     worktreeMode?: TreeseedWorkflowWorktreeMode;
     workspaceLinks?: 'auto' | 'off';
     verifyDeployedResources?: boolean;
+    skipCleanup?: boolean;
+    sceneArtifacts?: 'full' | 'screenshots';
     plan?: boolean;
     dryRun?: boolean;
 };
@@ -258,6 +262,8 @@ export type TreeseedReleaseInput = {
     workspaceLinks?: 'auto' | 'off';
     verifyDeployedResources?: boolean;
     fresh?: boolean;
+    skipCleanup?: boolean;
+    sceneArtifacts?: 'full' | 'screenshots';
     plan?: boolean;
     dryRun?: boolean;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@treeseed/sdk",
-  "version": "0.12.11",
+  "version": "0.12.13",
   "description": "Shared Treeseed SDK for content-backed and D1-backed object models.",
   "license": "AGPL-3.0-only",
   "repository": {